diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index c3ea27f9..819922bf 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -24,15 +24,19 @@ jobs: run: | export DEBIAN_FRONTEND=noninteractive sudo apt-get update - sudo apt-get upgrade -y --no-install-recommends - sudo apt-get install -y libenchant-2-2 + sudo apt-get upgrade -y --no-install-recommends + sudo apt-get install -y --fix-missing \ + nodejs \ + libenchant-2-2 \ + pandoc \ + zip sudo apt-get autoremove sudo apt-get autoclean sudo apt-get clean sudo rm -rf /var/lib/apt/lists/* python3 -m pip install --upgrade pip python3 -m pip install -r requirements-dev.txt - python3 -m pip install wheel + python3 -m pip install setuptools wheel - name: Run integrity checks run: | ./scripts/version.sh @@ -40,6 +44,7 @@ jobs: python3 -m pylint archivist examples functests unittests python3 -m pyright archivist black archivist examples unittests functests + ./scripts/zipnotebooks.sh (cd docs && make clean && make html) modified=$(git status -s | wc -l) if [ $modified -gt 0 ] diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml index 63209d2e..9427e987 100644 --- a/.github/workflows/python-publish.yml +++ b/.github/workflows/python-publish.yml @@ -23,7 +23,11 @@ jobs: export DEBIAN_FRONTEND=noninteractive sudo apt-get update sudo apt-get upgrade -y --no-install-recommends - sudo apt-get install -y libenchant-2-2 + sudo apt-get install -y --fix-missing \ + nodejs \ + libenchant-2-2 \ + pandoc \ + zip sudo apt-get autoremove sudo apt-get autoclean sudo apt-get clean @@ -38,16 +42,14 @@ jobs: run: | rm -f archivist/about.py ./scripts/version.sh - cat archivist/about.py python3 -m build --sdist python3 -m build --wheel twine check dist/* twine upload dist/* - name: Build docs run: | - ls -l - cd ./docs - make html + ./scripts/zipnotebooks.sh + (cd docs && make clean && make html) - name: Publish docs uses: peaceiris/actions-gh-pages@v3 with: diff --git a/.gitignore b/.gitignore index 1e61de30..cef82473 100644 --- a/.gitignore +++ b/.gitignore @@ -9,7 +9,6 @@ dist/ htmlcov/ coverage.xml .ipython/ -.jupyter/ .cache/ .local/ .python_history @@ -19,6 +18,7 @@ coverage.xml .pip-audit-cache/ *.pyi .vscode +rkvst-venv/ stuntidp* .npm/ functest-results/ diff --git a/.jupyter/jupyter_notebook_config.py b/.jupyter/jupyter_notebook_config.py new file mode 100644 index 00000000..69444959 --- /dev/null +++ b/.jupyter/jupyter_notebook_config.py @@ -0,0 +1,1438 @@ +# Configuration file for jupyter-notebook. + +c = get_config() #noqa + +#------------------------------------------------------------------------------ +# Application(SingletonConfigurable) configuration +#------------------------------------------------------------------------------ +## This is an application. + +## The date format used by logging formatters for %(asctime)s +# Default: '%Y-%m-%d %H:%M:%S' +# c.Application.log_datefmt = '%Y-%m-%d %H:%M:%S' + +## The Logging format template +# Default: '[%(name)s]%(highlevel)s %(message)s' +# c.Application.log_format = '[%(name)s]%(highlevel)s %(message)s' + +## Set the log level by value or name. +# Choices: any of [0, 10, 20, 30, 40, 50, 'DEBUG', 'INFO', 'WARN', 'ERROR', 'CRITICAL'] +# Default: 30 +# c.Application.log_level = 30 + +## Configure additional log handlers. +# +# The default stderr logs handler is configured by the log_level, log_datefmt +# and log_format settings. +# +# This configuration can be used to configure additional handlers (e.g. to +# output the log to a file) or for finer control over the default handlers. +# +# If provided this should be a logging configuration dictionary, for more +# information see: +# https://docs.python.org/3/library/logging.config.html#logging-config- +# dictschema +# +# This dictionary is merged with the base logging configuration which defines +# the following: +# +# * A logging formatter intended for interactive use called +# ``console``. +# * A logging handler that writes to stderr called +# ``console`` which uses the formatter ``console``. +# * A logger with the name of this application set to ``DEBUG`` +# level. +# +# This example adds a new handler that writes to a file: +# +# .. code-block:: python +# +# c.Application.logging_config = { +# 'handlers': { +# 'file': { +# 'class': 'logging.FileHandler', +# 'level': 'DEBUG', +# 'filename': '', +# } +# }, +# 'loggers': { +# '': { +# 'level': 'DEBUG', +# # NOTE: if you don't list the default "console" +# # handler here then it will be disabled +# 'handlers': ['console', 'file'], +# }, +# } +# } +# Default: {} +# c.Application.logging_config = {} + +## Instead of starting the Application, dump configuration to stdout +# Default: False +# c.Application.show_config = False + +## Instead of starting the Application, dump configuration to stdout (as JSON) +# Default: False +# c.Application.show_config_json = False + +#------------------------------------------------------------------------------ +# JupyterApp(Application) configuration +#------------------------------------------------------------------------------ +## Base class for Jupyter applications + +## Answer yes to any prompts. +# Default: False +# c.JupyterApp.answer_yes = False + +## Full path of a config file. +# Default: '' +# c.JupyterApp.config_file = '' + +## Specify a config file to load. +# Default: '' +# c.JupyterApp.config_file_name = '' + +## Generate default config file. +# Default: False +# c.JupyterApp.generate_config = False + +## The date format used by logging formatters for %(asctime)s +# See also: Application.log_datefmt +# c.JupyterApp.log_datefmt = '%Y-%m-%d %H:%M:%S' + +## The Logging format template +# See also: Application.log_format +# c.JupyterApp.log_format = '[%(name)s]%(highlevel)s %(message)s' + +## Set the log level by value or name. +# See also: Application.log_level +# c.JupyterApp.log_level = 30 + +## +# See also: Application.logging_config +# c.JupyterApp.logging_config = {} + +## Instead of starting the Application, dump configuration to stdout +# See also: Application.show_config +# c.JupyterApp.show_config = False + +## Instead of starting the Application, dump configuration to stdout (as JSON) +# See also: Application.show_config_json +# c.JupyterApp.show_config_json = False + +#------------------------------------------------------------------------------ +# NotebookApp(JupyterApp) configuration +#------------------------------------------------------------------------------ +## Set the Access-Control-Allow-Credentials: true header +# Default: False +# c.NotebookApp.allow_credentials = False + +## Set the Access-Control-Allow-Origin header +# +# Use '*' to allow any origin to access your server. +# +# Takes precedence over allow_origin_pat. +# Default: '' +# c.NotebookApp.allow_origin = '' + +## Use a regular expression for the Access-Control-Allow-Origin header +# +# Requests from an origin matching the expression will get replies with: +# +# Access-Control-Allow-Origin: origin +# +# where `origin` is the origin of the request. +# +# Ignored if allow_origin is set. +# Default: '' +# c.NotebookApp.allow_origin_pat = '' + +## Allow password to be changed at login for the notebook server. +# +# While logging in with a token, the notebook server UI will give the opportunity to +# the user to enter a new password at the same time that will replace +# the token login mechanism. +# +# This can be set to false to prevent changing password from +# the UI/API. +# Default: True +# c.NotebookApp.allow_password_change = True + +## Allow requests where the Host header doesn't point to a local server +# +# By default, requests get a 403 forbidden response if the 'Host' header +# shows that the browser thinks it's on a non-local domain. +# Setting this option to True disables this check. +# +# This protects against 'DNS rebinding' attacks, where a remote web server +# serves you a page and then changes its DNS to send later requests to a +# local IP, bypassing same-origin checks. +# +# Local IP addresses (such as 127.0.0.1 and ::1) are allowed as local, +# along with hostnames configured in local_hostnames. +# Default: False +# c.NotebookApp.allow_remote_access = False + +## Whether to allow the user to run the notebook as root. +# Default: False +# c.NotebookApp.allow_root = False + +## Answer yes to any prompts. +# See also: JupyterApp.answer_yes +# c.NotebookApp.answer_yes = False + +## " +# Require authentication to access prometheus metrics. +# Default: True +# c.NotebookApp.authenticate_prometheus = True + +## Reload the webapp when changes are made to any Python src files. +# Default: False +# c.NotebookApp.autoreload = False + +## DEPRECATED use base_url +# Default: '/' +# c.NotebookApp.base_project_url = '/' + +## The base URL for the notebook server. +# +# Leading and trailing slashes can be omitted, +# and will automatically be added. +# Default: '/' +# c.NotebookApp.base_url = '/' + +## Specify what command to use to invoke a web +# browser when opening the notebook. If not specified, the +# default browser will be determined by the `webbrowser` +# standard library module, which allows setting of the +# BROWSER environment variable to override it. +# Default: '' +# c.NotebookApp.browser = '' + +## The full path to an SSL/TLS certificate file. +# Default: '' +# c.NotebookApp.certfile = '' + +## The full path to a certificate authority certificate for SSL/TLS client +# authentication. +# Default: '' +# c.NotebookApp.client_ca = '' + +## Full path of a config file. +# See also: JupyterApp.config_file +# c.NotebookApp.config_file = '' + +## Specify a config file to load. +# See also: JupyterApp.config_file_name +# c.NotebookApp.config_file_name = '' + +## The config manager class to use +# Default: 'notebook.services.config.manager.ConfigManager' +# c.NotebookApp.config_manager_class = 'notebook.services.config.manager.ConfigManager' + +## The notebook manager class to use. +# Default: 'notebook.services.contents.largefilemanager.LargeFileManager' +# c.NotebookApp.contents_manager_class = 'notebook.services.contents.largefilemanager.LargeFileManager' + +## Extra keyword arguments to pass to `set_secure_cookie`. See tornado's +# set_secure_cookie docs for details. +# Default: {} +# c.NotebookApp.cookie_options = {} + +## The random bytes used to secure cookies. +# By default this is a new random number every time you start the Notebook. +# Set it to a value in a config file to enable logins to persist across server sessions. +# +# Note: Cookie secrets should be kept private, do not share config files with +# cookie_secret stored in plaintext (you can read the value from a file). +# Default: b'' +# c.NotebookApp.cookie_secret = b'' + +## The file where the cookie secret is stored. +# Default: '' +# c.NotebookApp.cookie_secret_file = '' + +## Override URL shown to users. +# +# Replace actual URL, including protocol, address, port and base URL, +# with the given value when displaying URL to the users. Do not change +# the actual connection URL. If authentication token is enabled, the +# token is added to the custom URL automatically. +# +# This option is intended to be used when the URL to display to the user +# cannot be determined reliably by the Jupyter notebook server (proxified +# or containerized setups for example). +# Default: '' +# c.NotebookApp.custom_display_url = '' + +## The default URL to redirect to from `/` +# Default: '/tree' +# c.NotebookApp.default_url = '/tree' + +## Disable cross-site-request-forgery protection +# +# Jupyter notebook 4.3.1 introduces protection from cross-site request forgeries, +# requiring API requests to either: +# +# - originate from pages served by this server (validated with XSRF cookie and token), or +# - authenticate with a token +# +# Some anonymous compute resources still desire the ability to run code, +# completely without authentication. +# These services can disable all authentication and security checks, +# with the full knowledge of what that implies. +# Default: False +# c.NotebookApp.disable_check_xsrf = False + +## Whether to enable MathJax for typesetting math/TeX +# +# MathJax is the javascript library Jupyter uses to render math/LaTeX. It is +# very large, so you may want to disable it if you have a slow internet +# connection, or for offline use of the notebook. +# +# When disabled, equations etc. will appear as their untransformed TeX +# source. +# Default: True +# c.NotebookApp.enable_mathjax = True + +## extra paths to look for Javascript notebook extensions +# Default: [] +# c.NotebookApp.extra_nbextensions_path = [] + +## handlers that should be loaded at higher priority than the default services +# Default: [] +# c.NotebookApp.extra_services = [] + +## Extra paths to search for serving static files. +# +# This allows adding javascript/css to be available from the notebook server machine, +# or overriding individual files in the IPython +# Default: [] +# c.NotebookApp.extra_static_paths = [] + +## Extra paths to search for serving jinja templates. +# +# Can be used to override templates from notebook.templates. +# Default: [] +# c.NotebookApp.extra_template_paths = [] + +# Default: '' +# c.NotebookApp.file_to_run = '' + +## Generate default config file. +# See also: JupyterApp.generate_config +# c.NotebookApp.generate_config = False + +## Extra keyword arguments to pass to `get_secure_cookie`. See tornado's +# get_secure_cookie docs for details. +# Default: {} +# c.NotebookApp.get_secure_cookie_kwargs = {} + +## Deprecated: Use minified JS file or not, mainly use during dev to avoid JS +# recompilation +# Default: False +# c.NotebookApp.ignore_minified_js = False + +## (bytes/sec) +# Maximum rate at which stream output can be sent on iopub before they are +# limited. +# Default: 1000000 +# c.NotebookApp.iopub_data_rate_limit = 1000000 + +## (msgs/sec) +# Maximum rate at which messages can be sent on iopub before they are +# limited. +# Default: 1000 +# c.NotebookApp.iopub_msg_rate_limit = 1000 + +## The IP address the notebook server will listen on. +# Default: 'localhost' +# c.NotebookApp.ip = 'localhost' + +## Supply extra arguments that will be passed to Jinja environment. +# Default: {} +# c.NotebookApp.jinja_environment_options = {} + +## Extra variables to supply to jinja templates when rendering. +# Default: {} +# c.NotebookApp.jinja_template_vars = {} + +## The kernel manager class to use. +# Default: 'notebook.services.kernels.kernelmanager.MappingKernelManager' +# c.NotebookApp.kernel_manager_class = 'notebook.services.kernels.kernelmanager.MappingKernelManager' + +## The kernel spec manager class to use. Should be a subclass of +# `jupyter_client.kernelspec.KernelSpecManager`. +# +# The Api of KernelSpecManager is provisional and might change without warning +# between this version of Jupyter and the next stable one. +# Default: 'jupyter_client.kernelspec.KernelSpecManager' +# c.NotebookApp.kernel_spec_manager_class = 'jupyter_client.kernelspec.KernelSpecManager' + +## The full path to a private key file for usage with SSL/TLS. +# Default: '' +# c.NotebookApp.keyfile = '' + +## Hostnames to allow as local when allow_remote_access is False. +# +# Local IP addresses (such as 127.0.0.1 and ::1) are automatically accepted +# as local as well. +# Default: ['localhost'] +# c.NotebookApp.local_hostnames = ['localhost'] + +## The date format used by logging formatters for %(asctime)s +# See also: Application.log_datefmt +# c.NotebookApp.log_datefmt = '%Y-%m-%d %H:%M:%S' + +## The Logging format template +# See also: Application.log_format +# c.NotebookApp.log_format = '[%(name)s]%(highlevel)s %(message)s' + +## Set to True to enable JSON formatted logs. Run "pip install notebook[json- +# logging]" to install the required dependent packages. Can also be set using +# the environment variable JUPYTER_ENABLE_JSON_LOGGING=true. +# Default: False +# c.NotebookApp.log_json = False + +## Set the log level by value or name. +# See also: Application.log_level +# c.NotebookApp.log_level = 30 + +## +# See also: Application.logging_config +# c.NotebookApp.logging_config = {} + +## The login handler class to use. +# Default: 'notebook.auth.login.LoginHandler' +# c.NotebookApp.login_handler_class = 'notebook.auth.login.LoginHandler' + +## The logout handler class to use. +# Default: 'notebook.auth.logout.LogoutHandler' +# c.NotebookApp.logout_handler_class = 'notebook.auth.logout.LogoutHandler' + +## The MathJax.js configuration file that is to be used. +# Default: 'TeX-AMS-MML_HTMLorMML-full,Safe' +# c.NotebookApp.mathjax_config = 'TeX-AMS-MML_HTMLorMML-full,Safe' + +## A custom url for MathJax.js. +# Should be in the form of a case-sensitive url to MathJax, +# for example: /static/components/MathJax/MathJax.js +# Default: '' +# c.NotebookApp.mathjax_url = '' + +## Sets the maximum allowed size of the client request body, specified in the +# Content-Length request header field. If the size in a request exceeds the +# configured value, a malformed HTTP message is returned to the client. +# +# Note: max_body_size is applied even in streaming mode. +# Default: 536870912 +# c.NotebookApp.max_body_size = 536870912 + +## Gets or sets the maximum amount of memory, in bytes, that is allocated for use +# by the buffer manager. +# Default: 536870912 +# c.NotebookApp.max_buffer_size = 536870912 + +## Gets or sets a lower bound on the open file handles process resource limit. +# This may need to be increased if you run into an OSError: [Errno 24] Too many +# open files. This is not applicable when running on Windows. +# Default: 0 +# c.NotebookApp.min_open_files_limit = 0 + +## Dict of Python modules to load as notebook server extensions. Entry values can +# be used to enable and disable the loading of the extensions. The extensions +# will be loaded in alphabetical order. +# Default: {} +# c.NotebookApp.nbserver_extensions = {} + +## The directory to use for notebooks and kernels. +# Default: '' +# c.NotebookApp.notebook_dir = '' + +## Whether to open in a browser after starting. +# The specific browser used is platform dependent and +# determined by the python standard library `webbrowser` +# module, unless it is overridden using the --browser +# (NotebookApp.browser) configuration option. +# Default: True +# c.NotebookApp.open_browser = True + +## Hashed password to use for web authentication. +# +# To generate, type in a python/IPython shell: +# +# from notebook.auth import passwd; passwd() +# +# The string should be of the form type:salt:hashed- +# password. +# Default: '' +# c.NotebookApp.password = '' + +## Forces users to use a password for the Notebook server. +# This is useful in a multi user environment, for instance when +# everybody in the LAN can access each other's machine through ssh. +# +# In such a case, serving the notebook server on localhost is not secure +# since any user can connect to the notebook server via ssh. +# Default: False +# c.NotebookApp.password_required = False + +## The port the notebook server will listen on (env: JUPYTER_PORT). +# Default: 8888 +# c.NotebookApp.port = 8888 + +## The number of additional ports to try if the specified port is not available +# (env: JUPYTER_PORT_RETRIES). +# Default: 50 +# c.NotebookApp.port_retries = 50 + +## DISABLED: use %pylab or %matplotlib in the notebook to enable matplotlib. +# Default: 'disabled' +# c.NotebookApp.pylab = 'disabled' + +## If True, display a button in the dashboard to quit +# (shutdown the notebook server). +# Default: True +# c.NotebookApp.quit_button = True + +## (sec) Time window used to +# check the message and data rate limits. +# Default: 3 +# c.NotebookApp.rate_limit_window = 3 + +## Reraise exceptions encountered loading server extensions? +# Default: False +# c.NotebookApp.reraise_server_extension_failures = False + +## DEPRECATED use the nbserver_extensions dict instead +# Default: [] +# c.NotebookApp.server_extensions = [] + +## The session manager class to use. +# Default: 'notebook.services.sessions.sessionmanager.SessionManager' +# c.NotebookApp.session_manager_class = 'notebook.services.sessions.sessionmanager.SessionManager' + +## Instead of starting the Application, dump configuration to stdout +# See also: Application.show_config +# c.NotebookApp.show_config = False + +## Instead of starting the Application, dump configuration to stdout (as JSON) +# See also: Application.show_config_json +# c.NotebookApp.show_config_json = False + +## Shut down the server after N seconds with no kernels or terminals running and +# no activity. This can be used together with culling idle kernels +# (MappingKernelManager.cull_idle_timeout) to shutdown the notebook server when +# it's not in use. This is not precisely timed: it may shut down up to a minute +# later. 0 (the default) disables this automatic shutdown. +# Default: 0 +# c.NotebookApp.shutdown_no_activity_timeout = 0 + +## The UNIX socket the notebook server will listen on. +# Default: '' +# c.NotebookApp.sock = '' + +## The permissions mode for UNIX socket creation (default: 0600). +# Default: '0600' +# c.NotebookApp.sock_mode = '0600' + +## Supply SSL options for the tornado HTTPServer. +# See the tornado docs for details. +# Default: {} +# c.NotebookApp.ssl_options = {} + +## Supply overrides for terminado. Currently only supports "shell_command". On +# Unix, if "shell_command" is not provided, a non-login shell is launched by +# default when the notebook server is connected to a terminal, a login shell +# otherwise. +# Default: {} +# c.NotebookApp.terminado_settings = {} + +## Set to False to disable terminals. +# +# This does *not* make the notebook server more secure by itself. +# Anything the user can in a terminal, they can also do in a notebook. +# +# Terminals may also be automatically disabled if the terminado package +# is not available. +# Default: True +# c.NotebookApp.terminals_enabled = True + +## Token used for authenticating first-time connections to the server. +# +# The token can be read from the file referenced by JUPYTER_TOKEN_FILE or set directly +# with the JUPYTER_TOKEN environment variable. +# +# When no password is enabled, +# the default is to generate a new, random token. +# +# Setting to an empty string disables authentication altogether, which +# is NOT RECOMMENDED. +# Default: '' +# c.NotebookApp.token = '' + +## Supply overrides for the tornado.web.Application that the Jupyter notebook +# uses. +# Default: {} +# c.NotebookApp.tornado_settings = {} + +## Whether to trust or not X-Scheme/X-Forwarded-Proto and X-Real-Ip/X-Forwarded- +# For headers sent by the upstream reverse proxy. Necessary if the proxy handles +# SSL +# Default: False +# c.NotebookApp.trust_xheaders = False + +## Disable launching browser by redirect file +# +# For versions of notebook > 5.7.2, a security feature measure was added that +# prevented the authentication token used to launch the browser from being visible. +# This feature makes it difficult for other users on a multi-user system from +# running code in your Jupyter session as you. +# +# However, some environments (like Windows Subsystem for Linux (WSL) and Chromebooks), +# launching a browser using a redirect file can lead the browser failing to load. +# This is because of the difference in file structures/paths between the runtime and +# the browser. +# +# Disabling this setting to False will disable this behavior, allowing the browser +# to launch by using a URL and visible token (as before). +# Default: True +# c.NotebookApp.use_redirect_file = True + +## DEPRECATED, use tornado_settings +# Default: {} +# c.NotebookApp.webapp_settings = {} + +## Specify Where to open the notebook on startup. This is the +# `new` argument passed to the standard library method `webbrowser.open`. +# The behaviour is not guaranteed, but depends on browser support. Valid +# values are: +# +# - 2 opens a new tab, +# - 1 opens a new window, +# - 0 opens in an existing window. +# +# See the `webbrowser.open` documentation for details. +# Default: 2 +# c.NotebookApp.webbrowser_open_new = 2 + +## Set the tornado compression options for websocket connections. +# +# This value will be returned from +# :meth:`WebSocketHandler.get_compression_options`. None (default) will disable +# compression. A dict (even an empty one) will enable compression. +# +# See the tornado docs for WebSocketHandler.get_compression_options for details. +# Default: None +# c.NotebookApp.websocket_compression_options = None + +## The base URL for websockets, +# if it differs from the HTTP server (hint: it almost certainly doesn't). +# +# Should be in the form of an HTTP origin: ws[s]://hostname[:port] +# Default: '' +# c.NotebookApp.websocket_url = '' + +#------------------------------------------------------------------------------ +# ConnectionFileMixin(LoggingConfigurable) configuration +#------------------------------------------------------------------------------ +## Mixin for configurable classes that work with connection files + +## JSON file in which to store connection info [default: kernel-.json] +# +# This file will contain the IP, ports, and authentication key needed to connect +# clients to this kernel. By default, this file will be created in the security dir +# of the current profile, but can be specified by absolute path. +# Default: '' +# c.ConnectionFileMixin.connection_file = '' + +## set the control (ROUTER) port [default: random] +# Default: 0 +# c.ConnectionFileMixin.control_port = 0 + +## set the heartbeat port [default: random] +# Default: 0 +# c.ConnectionFileMixin.hb_port = 0 + +## set the iopub (PUB) port [default: random] +# Default: 0 +# c.ConnectionFileMixin.iopub_port = 0 + +## Set the kernel's IP address [default localhost]. +# If the IP address is something other than localhost, then +# Consoles on other machines will be able to connect +# to the Kernel, so be careful! +# Default: '' +# c.ConnectionFileMixin.ip = '' + +## set the shell (ROUTER) port [default: random] +# Default: 0 +# c.ConnectionFileMixin.shell_port = 0 + +## set the stdin (ROUTER) port [default: random] +# Default: 0 +# c.ConnectionFileMixin.stdin_port = 0 + +# Choices: any of ['tcp', 'ipc'] (case-insensitive) +# Default: 'tcp' +# c.ConnectionFileMixin.transport = 'tcp' + +#------------------------------------------------------------------------------ +# KernelManager(ConnectionFileMixin) configuration +#------------------------------------------------------------------------------ +## Manages a single kernel in a subprocess on this host. +# +# This version starts kernels with Popen. + +## Should we autorestart the kernel if it dies. +# Default: True +# c.KernelManager.autorestart = True + +## JSON file in which to store connection info [default: kernel-.json] +# See also: ConnectionFileMixin.connection_file +# c.KernelManager.connection_file = '' + +## set the control (ROUTER) port [default: random] +# See also: ConnectionFileMixin.control_port +# c.KernelManager.control_port = 0 + +## set the heartbeat port [default: random] +# See also: ConnectionFileMixin.hb_port +# c.KernelManager.hb_port = 0 + +## set the iopub (PUB) port [default: random] +# See also: ConnectionFileMixin.iopub_port +# c.KernelManager.iopub_port = 0 + +## Set the kernel's IP address [default localhost]. +# See also: ConnectionFileMixin.ip +# c.KernelManager.ip = '' + +## set the shell (ROUTER) port [default: random] +# See also: ConnectionFileMixin.shell_port +# c.KernelManager.shell_port = 0 + +## Time to wait for a kernel to terminate before killing it, in seconds. When a +# shutdown request is initiated, the kernel will be immediately sent an +# interrupt (SIGINT), followedby a shutdown_request message, after 1/2 of +# `shutdown_wait_time`it will be sent a terminate (SIGTERM) request, and finally +# at the end of `shutdown_wait_time` will be killed (SIGKILL). terminate and +# kill may be equivalent on windows. Note that this value can beoverridden by +# the in-use kernel provisioner since shutdown times mayvary by provisioned +# environment. +# Default: 5.0 +# c.KernelManager.shutdown_wait_time = 5.0 + +## set the stdin (ROUTER) port [default: random] +# See also: ConnectionFileMixin.stdin_port +# c.KernelManager.stdin_port = 0 + +# See also: ConnectionFileMixin.transport +# c.KernelManager.transport = 'tcp' + +#------------------------------------------------------------------------------ +# Session(Configurable) configuration +#------------------------------------------------------------------------------ +## Object for handling serialization and sending of messages. +# +# The Session object handles building messages and sending them +# with ZMQ sockets or ZMQStream objects. Objects can communicate with each +# other over the network via Session objects, and only need to work with the +# dict-based IPython message spec. The Session will handle +# serialization/deserialization, security, and metadata. +# +# Sessions support configurable serialization via packer/unpacker traits, +# and signing with HMAC digests via the key/keyfile traits. +# +# Parameters +# ---------- +# +# debug : bool +# whether to trigger extra debugging statements +# packer/unpacker : str : 'json', 'pickle' or import_string +# importstrings for methods to serialize message parts. If just +# 'json' or 'pickle', predefined JSON and pickle packers will be used. +# Otherwise, the entire importstring must be used. +# +# The functions must accept at least valid JSON input, and output +# *bytes*. +# +# For example, to use msgpack: +# packer = 'msgpack.packb', unpacker='msgpack.unpackb' +# pack/unpack : callables +# You can also set the pack/unpack callables for serialization directly. +# session : bytes +# the ID of this Session object. The default is to generate a new UUID. +# username : unicode +# username added to message headers. The default is to ask the OS. +# key : bytes +# The key used to initialize an HMAC signature. If unset, messages +# will not be signed or checked. +# keyfile : filepath +# The file containing a key. If this is set, `key` will be initialized +# to the contents of the file. + +## Threshold (in bytes) beyond which an object's buffer should be extracted to +# avoid pickling. +# Default: 1024 +# c.Session.buffer_threshold = 1024 + +## Whether to check PID to protect against calls after fork. +# +# This check can be disabled if fork-safety is handled elsewhere. +# Default: True +# c.Session.check_pid = True + +## Threshold (in bytes) beyond which a buffer should be sent without copying. +# Default: 65536 +# c.Session.copy_threshold = 65536 + +## Debug output in the Session +# Default: False +# c.Session.debug = False + +## The maximum number of digests to remember. +# +# The digest history will be culled when it exceeds this value. +# Default: 65536 +# c.Session.digest_history_size = 65536 + +## The maximum number of items for a container to be introspected for custom serialization. +# Containers larger than this are pickled outright. +# Default: 64 +# c.Session.item_threshold = 64 + +## execution key, for signing messages. +# Default: b'' +# c.Session.key = b'' + +## path to file containing execution key. +# Default: '' +# c.Session.keyfile = '' + +## Metadata dictionary, which serves as the default top-level metadata dict for +# each message. +# Default: {} +# c.Session.metadata = {} + +## The name of the packer for serializing messages. +# Should be one of 'json', 'pickle', or an import name +# for a custom callable serializer. +# Default: 'json' +# c.Session.packer = 'json' + +## The UUID identifying this session. +# Default: '' +# c.Session.session = '' + +## The digest scheme used to construct the message signatures. +# Must have the form 'hmac-HASH'. +# Default: 'hmac-sha256' +# c.Session.signature_scheme = 'hmac-sha256' + +## The name of the unpacker for unserializing messages. +# Only used with custom functions for `packer`. +# Default: 'json' +# c.Session.unpacker = 'json' + +## Username for the Session. Default is your system username. +# Default: 'builder' +# c.Session.username = 'builder' + +#------------------------------------------------------------------------------ +# MultiKernelManager(LoggingConfigurable) configuration +#------------------------------------------------------------------------------ +## A class for managing multiple kernels. + +## The name of the default kernel to start +# Default: 'python3' +# c.MultiKernelManager.default_kernel_name = 'python3' + +## The kernel manager class. This is configurable to allow +# subclassing of the KernelManager for customized behavior. +# Default: 'jupyter_client.ioloop.IOLoopKernelManager' +# c.MultiKernelManager.kernel_manager_class = 'jupyter_client.ioloop.IOLoopKernelManager' + +## Share a single zmq.Context to talk to all my kernels +# Default: True +# c.MultiKernelManager.shared_context = True + +#------------------------------------------------------------------------------ +# MappingKernelManager(MultiKernelManager) configuration +#------------------------------------------------------------------------------ +## A KernelManager that handles notebook mapping and HTTP error handling + +## White list of allowed kernel message types. +# When the list is empty, all message types are allowed. +# Default: [] +# c.MappingKernelManager.allowed_message_types = [] + +## Whether messages from kernels whose frontends have disconnected should be buffered in-memory. +# When True (default), messages are buffered and replayed on reconnect, +# avoiding lost messages due to interrupted connectivity. +# Disable if long-running kernels will produce too much output while +# no frontends are connected. +# Default: True +# c.MappingKernelManager.buffer_offline_messages = True + +## Whether to consider culling kernels which are busy. +# Only effective if cull_idle_timeout > 0. +# Default: False +# c.MappingKernelManager.cull_busy = False + +## Whether to consider culling kernels which have one or more connections. +# Only effective if cull_idle_timeout > 0. +# Default: False +# c.MappingKernelManager.cull_connected = False + +## Timeout (in seconds) after which a kernel is considered idle and ready to be culled. +# Values of 0 or lower disable culling. Very short timeouts may result in kernels being culled +# for users with poor network connections. +# Default: 0 +# c.MappingKernelManager.cull_idle_timeout = 0 + +## The interval (in seconds) on which to check for idle kernels exceeding the +# cull timeout value. +# Default: 300 +# c.MappingKernelManager.cull_interval = 300 + +## The name of the default kernel to start +# See also: MultiKernelManager.default_kernel_name +# c.MappingKernelManager.default_kernel_name = 'python3' + +## Timeout for giving up on a kernel (in seconds). +# On starting and restarting kernels, we check whether the +# kernel is running and responsive by sending kernel_info_requests. +# This sets the timeout in seconds for how long the kernel can take +# before being presumed dead. +# This affects the MappingKernelManager (which handles kernel restarts) +# and the ZMQChannelsHandler (which handles the startup). +# Default: 60 +# c.MappingKernelManager.kernel_info_timeout = 60 + +## The kernel manager class. This is configurable to allow +# See also: MultiKernelManager.kernel_manager_class +# c.MappingKernelManager.kernel_manager_class = 'jupyter_client.ioloop.IOLoopKernelManager' + +# Default: '' +# c.MappingKernelManager.root_dir = '' + +## Share a single zmq.Context to talk to all my kernels +# See also: MultiKernelManager.shared_context +# c.MappingKernelManager.shared_context = True + +#------------------------------------------------------------------------------ +# KernelSpecManager(LoggingConfigurable) configuration +#------------------------------------------------------------------------------ +## List of allowed kernel names. +# +# By default, all installed kernels are allowed. +# Default: set() +# c.KernelSpecManager.allowed_kernelspecs = set() + +## If there is no Python kernelspec registered and the IPython +# kernel is available, ensure it is added to the spec list. +# Default: True +# c.KernelSpecManager.ensure_native_kernel = True + +## The kernel spec class. This is configurable to allow +# subclassing of the KernelSpecManager for customized behavior. +# Default: 'jupyter_client.kernelspec.KernelSpec' +# c.KernelSpecManager.kernel_spec_class = 'jupyter_client.kernelspec.KernelSpec' + +## Deprecated, use `KernelSpecManager.allowed_kernelspecs` +# Default: set() +# c.KernelSpecManager.whitelist = set() + +#------------------------------------------------------------------------------ +# ContentsManager(LoggingConfigurable) configuration +#------------------------------------------------------------------------------ +## Base class for serving files and directories. +# +# This serves any text or binary file, +# as well as directories, +# with special handling for JSON notebook documents. +# +# Most APIs take a path argument, +# which is always an API-style unicode path, +# and always refers to a directory. +# +# - unicode, not url-escaped +# - '/'-separated +# - leading and trailing '/' will be stripped +# - if unspecified, path defaults to '', +# indicating the root path. + +## Allow access to hidden files +# Default: False +# c.ContentsManager.allow_hidden = False + +# Default: None +# c.ContentsManager.checkpoints = None + +# Default: 'notebook.services.contents.checkpoints.Checkpoints' +# c.ContentsManager.checkpoints_class = 'notebook.services.contents.checkpoints.Checkpoints' + +# Default: {} +# c.ContentsManager.checkpoints_kwargs = {} + +## handler class to use when serving raw file requests. +# +# Default is a fallback that talks to the ContentsManager API, +# which may be inefficient, especially for large files. +# +# Local files-based ContentsManagers can use a StaticFileHandler subclass, +# which will be much more efficient. +# +# Access to these files should be Authenticated. +# Default: 'notebook.files.handlers.FilesHandler' +# c.ContentsManager.files_handler_class = 'notebook.files.handlers.FilesHandler' + +## Extra parameters to pass to files_handler_class. +# +# For example, StaticFileHandlers generally expect a `path` argument +# specifying the root directory from which to serve files. +# Default: {} +# c.ContentsManager.files_handler_params = {} + +## Glob patterns to hide in file and directory listings. +# Default: ['__pycache__', '*.pyc', '*.pyo', '.DS_Store', '*.so', '*.dylib', '*~'] +# c.ContentsManager.hide_globs = ['__pycache__', '*.pyc', '*.pyo', '.DS_Store', '*.so', '*.dylib', '*~'] + +## Python callable or importstring thereof +# +# To be called on a contents model prior to save. +# +# This can be used to process the structure, +# such as removing notebook outputs or other side effects that +# should not be saved. +# +# It will be called as (all arguments passed by keyword):: +# +# hook(path=path, model=model, contents_manager=self) +# +# - model: the model to be saved. Includes file contents. +# Modifying this dict will affect the file that is stored. +# - path: the API path of the save destination +# - contents_manager: this ContentsManager instance +# Default: None +# c.ContentsManager.pre_save_hook = None + +# Default: '/' +# c.ContentsManager.root_dir = '/' + +## The base name used when creating untitled directories. +# Default: 'Untitled Folder' +# c.ContentsManager.untitled_directory = 'Untitled Folder' + +## The base name used when creating untitled files. +# Default: 'untitled' +# c.ContentsManager.untitled_file = 'untitled' + +## The base name used when creating untitled notebooks. +# Default: 'Untitled' +# c.ContentsManager.untitled_notebook = 'Untitled' + +#------------------------------------------------------------------------------ +# FileManagerMixin(Configurable) configuration +#------------------------------------------------------------------------------ +## Mixin for ContentsAPI classes that interact with the filesystem. +# +# Provides facilities for reading, writing, and copying both notebooks and +# generic files. +# +# Shared by FileContentsManager and FileCheckpoints. +# +# Note ---- Classes using this mixin must provide the following attributes: +# +# root_dir : unicode +# A directory against which API-style paths are to be resolved. +# +# log : logging.Logger + +## By default notebooks are saved on disk on a temporary file and then if successfully written, it replaces the old ones. +# This procedure, namely 'atomic_writing', causes some bugs on file system without operation order enforcement (like some networked fs). +# If set to False, the new notebook is written directly on the old one which could fail (eg: full filesystem or quota ) +# Default: True +# c.FileManagerMixin.use_atomic_writing = True + +#------------------------------------------------------------------------------ +# FileContentsManager(FileManagerMixin, ContentsManager) configuration +#------------------------------------------------------------------------------ +## Allow access to hidden files +# See also: ContentsManager.allow_hidden +# c.FileContentsManager.allow_hidden = False + +# See also: ContentsManager.checkpoints +# c.FileContentsManager.checkpoints = None + +# See also: ContentsManager.checkpoints_class +# c.FileContentsManager.checkpoints_class = 'notebook.services.contents.checkpoints.Checkpoints' + +# See also: ContentsManager.checkpoints_kwargs +# c.FileContentsManager.checkpoints_kwargs = {} + +## If True (default), deleting files will send them to the +# platform's trash/recycle bin, where they can be recovered. If False, +# deleting files really deletes them. +# Default: True +# c.FileContentsManager.delete_to_trash = True + +## handler class to use when serving raw file requests. +# See also: ContentsManager.files_handler_class +# c.FileContentsManager.files_handler_class = 'notebook.files.handlers.FilesHandler' + +## Extra parameters to pass to files_handler_class. +# See also: ContentsManager.files_handler_params +# c.FileContentsManager.files_handler_params = {} + +## +# See also: ContentsManager.hide_globs +# c.FileContentsManager.hide_globs = ['__pycache__', '*.pyc', '*.pyo', '.DS_Store', '*.so', '*.dylib', '*~'] + +## Python callable or importstring thereof +# +# to be called on the path of a file just saved. +# +# This can be used to process the file on disk, +# such as converting the notebook to a script or HTML via nbconvert. +# +# It will be called as (all arguments passed by keyword):: +# +# hook(os_path=os_path, model=model, contents_manager=instance) +# +# - path: the filesystem path to the file just written +# - model: the model representing the file +# - contents_manager: this ContentsManager instance +# Default: None +# c.FileContentsManager.post_save_hook = None + +## Python callable or importstring thereof +# See also: ContentsManager.pre_save_hook +# c.FileContentsManager.pre_save_hook = None + +# Default: '' +# c.FileContentsManager.root_dir = '' + +## DEPRECATED, use post_save_hook. Will be removed in Notebook 5.0 +# Default: False +# c.FileContentsManager.save_script = False + +## The base name used when creating untitled directories. +# See also: ContentsManager.untitled_directory +# c.FileContentsManager.untitled_directory = 'Untitled Folder' + +## The base name used when creating untitled files. +# See also: ContentsManager.untitled_file +# c.FileContentsManager.untitled_file = 'untitled' + +## The base name used when creating untitled notebooks. +# See also: ContentsManager.untitled_notebook +# c.FileContentsManager.untitled_notebook = 'Untitled' + +## By default notebooks are saved on disk on a temporary file and then if +# successfully written, it replaces the old ones. +# See also: FileManagerMixin.use_atomic_writing +# c.FileContentsManager.use_atomic_writing = True + +#------------------------------------------------------------------------------ +# NotebookNotary(LoggingConfigurable) configuration +#------------------------------------------------------------------------------ +## A class for computing and verifying notebook signatures. + +## The hashing algorithm used to sign notebooks. +# Choices: any of ['sha3_384', 'blake2b', 'sha1', 'md5', 'sha3_224', 'sha3_256', 'sha3_512', 'sha224', 'sha384', 'sha256', 'blake2s', 'sha512'] +# Default: 'sha256' +# c.NotebookNotary.algorithm = 'sha256' + +## The storage directory for notary secret and database. +# Default: '' +# c.NotebookNotary.data_dir = '' + +## The sqlite file in which to store notebook signatures. +# By default, this will be in your Jupyter data directory. +# You can set it to ':memory:' to disable sqlite writing to the filesystem. +# Default: '' +# c.NotebookNotary.db_file = '' + +## The secret key with which notebooks are signed. +# Default: b'' +# c.NotebookNotary.secret = b'' + +## The file where the secret key is stored. +# Default: '' +# c.NotebookNotary.secret_file = '' + +## A callable returning the storage backend for notebook signatures. +# The default uses an SQLite database. +# Default: traitlets.Undefined +# c.NotebookNotary.store_factory = traitlets.Undefined + +#------------------------------------------------------------------------------ +# AsyncMultiKernelManager(MultiKernelManager) configuration +#------------------------------------------------------------------------------ +## The name of the default kernel to start +# See also: MultiKernelManager.default_kernel_name +# c.AsyncMultiKernelManager.default_kernel_name = 'python3' + +## The kernel manager class. This is configurable to allow +# subclassing of the AsyncKernelManager for customized behavior. +# Default: 'jupyter_client.ioloop.AsyncIOLoopKernelManager' +# c.AsyncMultiKernelManager.kernel_manager_class = 'jupyter_client.ioloop.AsyncIOLoopKernelManager' + +## Share a single zmq.Context to talk to all my kernels +# See also: MultiKernelManager.shared_context +# c.AsyncMultiKernelManager.shared_context = True + +## Whether to make kernels available before the process has started. The +# kernel has a `.ready` future which can be awaited before connecting +# Default: False +# c.AsyncMultiKernelManager.use_pending_kernels = False + +#------------------------------------------------------------------------------ +# AsyncMappingKernelManager(MappingKernelManager, AsyncMultiKernelManager) configuration +#------------------------------------------------------------------------------ +## White list of allowed kernel message types. +# See also: MappingKernelManager.allowed_message_types +# c.AsyncMappingKernelManager.allowed_message_types = [] + +## Whether messages from kernels whose frontends have disconnected should be +# buffered in-memory. +# See also: MappingKernelManager.buffer_offline_messages +# c.AsyncMappingKernelManager.buffer_offline_messages = True + +## Whether to consider culling kernels which are busy. +# See also: MappingKernelManager.cull_busy +# c.AsyncMappingKernelManager.cull_busy = False + +## Whether to consider culling kernels which have one or more connections. +# See also: MappingKernelManager.cull_connected +# c.AsyncMappingKernelManager.cull_connected = False + +## Timeout (in seconds) after which a kernel is considered idle and ready to be +# culled. +# See also: MappingKernelManager.cull_idle_timeout +# c.AsyncMappingKernelManager.cull_idle_timeout = 0 + +## The interval (in seconds) on which to check for idle kernels exceeding the +# cull timeout value. +# See also: MappingKernelManager.cull_interval +# c.AsyncMappingKernelManager.cull_interval = 300 + +## The name of the default kernel to start +# See also: MultiKernelManager.default_kernel_name +# c.AsyncMappingKernelManager.default_kernel_name = 'python3' + +## Timeout for giving up on a kernel (in seconds). +# See also: MappingKernelManager.kernel_info_timeout +# c.AsyncMappingKernelManager.kernel_info_timeout = 60 + +## The kernel manager class. This is configurable to allow +# See also: AsyncMultiKernelManager.kernel_manager_class +# c.AsyncMappingKernelManager.kernel_manager_class = 'jupyter_client.ioloop.AsyncIOLoopKernelManager' + +# See also: MappingKernelManager.root_dir +# c.AsyncMappingKernelManager.root_dir = '' + +## Share a single zmq.Context to talk to all my kernels +# See also: MultiKernelManager.shared_context +# c.AsyncMappingKernelManager.shared_context = True + +## Whether to make kernels available before the process has started. The +# See also: AsyncMultiKernelManager.use_pending_kernels +# c.AsyncMappingKernelManager.use_pending_kernels = False + +#------------------------------------------------------------------------------ +# GatewayKernelManager(AsyncMappingKernelManager) configuration +#------------------------------------------------------------------------------ +## Kernel manager that supports remote kernels hosted by Jupyter Kernel or +# Enterprise Gateway. + +## White list of allowed kernel message types. +# See also: MappingKernelManager.allowed_message_types +# c.GatewayKernelManager.allowed_message_types = [] + +## Whether messages from kernels whose frontends have disconnected should be +# buffered in-memory. +# See also: MappingKernelManager.buffer_offline_messages +# c.GatewayKernelManager.buffer_offline_messages = True + +## Whether to consider culling kernels which are busy. +# See also: MappingKernelManager.cull_busy +# c.GatewayKernelManager.cull_busy = False + +## Whether to consider culling kernels which have one or more connections. +# See also: MappingKernelManager.cull_connected +# c.GatewayKernelManager.cull_connected = False + +## Timeout (in seconds) after which a kernel is considered idle and ready to be +# culled. +# See also: MappingKernelManager.cull_idle_timeout +# c.GatewayKernelManager.cull_idle_timeout = 0 + +## The interval (in seconds) on which to check for idle kernels exceeding the +# cull timeout value. +# See also: MappingKernelManager.cull_interval +# c.GatewayKernelManager.cull_interval = 300 + +## The name of the default kernel to start +# See also: MultiKernelManager.default_kernel_name +# c.GatewayKernelManager.default_kernel_name = 'python3' + +## Timeout for giving up on a kernel (in seconds). +# See also: MappingKernelManager.kernel_info_timeout +# c.GatewayKernelManager.kernel_info_timeout = 60 + +## The kernel manager class. This is configurable to allow +# See also: AsyncMultiKernelManager.kernel_manager_class +# c.GatewayKernelManager.kernel_manager_class = 'jupyter_client.ioloop.AsyncIOLoopKernelManager' + +# See also: MappingKernelManager.root_dir +# c.GatewayKernelManager.root_dir = '' + +## Share a single zmq.Context to talk to all my kernels +# See also: MultiKernelManager.shared_context +# c.GatewayKernelManager.shared_context = True + +## Whether to make kernels available before the process has started. The +# See also: AsyncMultiKernelManager.use_pending_kernels +# c.GatewayKernelManager.use_pending_kernels = False + +#------------------------------------------------------------------------------ +# GatewayKernelSpecManager(KernelSpecManager) configuration +#------------------------------------------------------------------------------ +## List of allowed kernel names. +# See also: KernelSpecManager.allowed_kernelspecs +# c.GatewayKernelSpecManager.allowed_kernelspecs = set() + +## If there is no Python kernelspec registered and the IPython +# See also: KernelSpecManager.ensure_native_kernel +# c.GatewayKernelSpecManager.ensure_native_kernel = True + +## The kernel spec class. This is configurable to allow +# See also: KernelSpecManager.kernel_spec_class +# c.GatewayKernelSpecManager.kernel_spec_class = 'jupyter_client.kernelspec.KernelSpec' + +## Deprecated, use `KernelSpecManager.allowed_kernelspecs` +# See also: KernelSpecManager.whitelist +# c.GatewayKernelSpecManager.whitelist = set() + +#------------------------------------------------------------------------------ +# GatewayClient(SingletonConfigurable) configuration +#------------------------------------------------------------------------------ +## This class manages the configuration. It's its own singleton class so that we +# can share these values across all objects. It also contains some helper methods +# to build request arguments out of the various config options. + +## The authorization token used in the HTTP headers. (JUPYTER_GATEWAY_AUTH_TOKEN +# env var) +# Default: None +# c.GatewayClient.auth_token = None + +## The filename of CA certificates or None to use defaults. +# (JUPYTER_GATEWAY_CA_CERTS env var) +# Default: None +# c.GatewayClient.ca_certs = None + +## The filename for client SSL certificate, if any. (JUPYTER_GATEWAY_CLIENT_CERT +# env var) +# Default: None +# c.GatewayClient.client_cert = None + +## The filename for client SSL key, if any. (JUPYTER_GATEWAY_CLIENT_KEY env var) +# Default: None +# c.GatewayClient.client_key = None + +## The time allowed for HTTP connection establishment with the Gateway server. +# (JUPYTER_GATEWAY_CONNECT_TIMEOUT env var) +# Default: 40.0 +# c.GatewayClient.connect_timeout = 40.0 + +## A comma-separated list of environment variable names that will be included, along with +# their values, in the kernel startup request. The corresponding `env_whitelist` configuration +# value must also be set on the Gateway server - since that configuration value indicates which +# environmental values to make available to the kernel. (JUPYTER_GATEWAY_ENV_WHITELIST env var) +# Default: '' +# c.GatewayClient.env_whitelist = '' + +## The time allowed for HTTP reconnection with the Gateway server for the first time. +# Next will be JUPYTER_GATEWAY_RETRY_INTERVAL multiplied by two in factor of numbers of retries +# but less than JUPYTER_GATEWAY_RETRY_INTERVAL_MAX. +# (JUPYTER_GATEWAY_RETRY_INTERVAL env var) +# Default: 1.0 +# c.GatewayClient.gateway_retry_interval = 1.0 + +## The maximum time allowed for HTTP reconnection retry with the Gateway server. +# (JUPYTER_GATEWAY_RETRY_INTERVAL_MAX env var) +# Default: 30.0 +# c.GatewayClient.gateway_retry_interval_max = 30.0 + +## The maximum retries allowed for HTTP reconnection with the Gateway server. +# (JUPYTER_GATEWAY_RETRY_MAX env var) +# Default: 5 +# c.GatewayClient.gateway_retry_max = 5 + +## Additional HTTP headers to pass on the request. This value will be converted to a dict. +# (JUPYTER_GATEWAY_HEADERS env var) +# Default: '{}' +# c.GatewayClient.headers = '{}' + +## The password for HTTP authentication. (JUPYTER_GATEWAY_HTTP_PWD env var) +# Default: None +# c.GatewayClient.http_pwd = None + +## The username for HTTP authentication. (JUPYTER_GATEWAY_HTTP_USER env var) +# Default: None +# c.GatewayClient.http_user = None + +## The gateway API endpoint for accessing kernel resources +# (JUPYTER_GATEWAY_KERNELS_ENDPOINT env var) +# Default: '/api/kernels' +# c.GatewayClient.kernels_endpoint = '/api/kernels' + +## The gateway API endpoint for accessing kernelspecs +# (JUPYTER_GATEWAY_KERNELSPECS_ENDPOINT env var) +# Default: '/api/kernelspecs' +# c.GatewayClient.kernelspecs_endpoint = '/api/kernelspecs' + +## The gateway endpoint for accessing kernelspecs resources +# (JUPYTER_GATEWAY_KERNELSPECS_RESOURCE_ENDPOINT env var) +# Default: '/kernelspecs' +# c.GatewayClient.kernelspecs_resource_endpoint = '/kernelspecs' + +## The time allowed for HTTP request completion. (JUPYTER_GATEWAY_REQUEST_TIMEOUT +# env var) +# Default: 40.0 +# c.GatewayClient.request_timeout = 40.0 + +## The url of the Kernel or Enterprise Gateway server where +# kernel specifications are defined and kernel management takes place. +# If defined, this Notebook server acts as a proxy for all kernel +# management and kernel specification retrieval. (JUPYTER_GATEWAY_URL env var) +# Default: None +# c.GatewayClient.url = None + +## For HTTPS requests, determines if server's certificate should be validated or not. +# (JUPYTER_GATEWAY_VALIDATE_CERT env var) +# Default: True +# c.GatewayClient.validate_cert = True + +## The websocket url of the Kernel or Enterprise Gateway server. If not provided, this value +# will correspond to the value of the Gateway url with 'ws' in place of 'http'. (JUPYTER_GATEWAY_WS_URL env var) +# Default: None +# c.GatewayClient.ws_url = None + +#------------------------------------------------------------------------------ +# TerminalManager(LoggingConfigurable) configuration +#------------------------------------------------------------------------------ +## + +## Timeout (in seconds) in which a terminal has been inactive and ready to be culled. +# Values of 0 or lower disable culling. +# Default: 0 +# c.TerminalManager.cull_inactive_timeout = 0 + +## The interval (in seconds) on which to check for terminals exceeding the +# inactive timeout value. +# Default: 300 +# c.TerminalManager.cull_interval = 300 diff --git a/.jupyter/migrated b/.jupyter/migrated new file mode 100644 index 00000000..5161bba8 --- /dev/null +++ b/.jupyter/migrated @@ -0,0 +1 @@ +2022-12-09T11:41:56.383203 \ No newline at end of file diff --git a/Dockerfile-builder b/Dockerfile-builder index 86aa7db6..3263ff3f 100644 --- a/Dockerfile-builder +++ b/Dockerfile-builder @@ -17,18 +17,28 @@ RUN curl -fsSL https://deb.nodesource.com/setup_18.x | bash - RUN apt-get update \ && apt-get upgrade -y --no-install-recommends \ - && apt-get install -y --fix-missing nodejs libenchant-2-2 \ + && apt-get install -y --fix-missing \ + nodejs \ + libenchant-2-2 \ + pandoc \ + zip \ && apt-get autoremove \ && apt-get autoclean \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* COPY requirements.txt requirements-dev.txt /tmp/ +RUN mkdir -p /tmp/docs +COPY docs/requirements.txt /tmp/docs/ +RUN find /tmp -type f +COPY docs/notebooks/requirements.txt /tmp/docs/notebooks/ +RUN find /tmp -type f RUN python3 -m pip install --upgrade pip \ && python3 -m pip install -U -r /tmp/requirements-dev.txt \ && rm -f /tmp/requirements-dev.txt \ - && rm -f /tmp/requirements.txt + && rm -f /tmp/requirements.txt \ + && rm -rf /tmp/docs ENV USER=builder ENV HOME=/home/${USER} diff --git a/Taskfile.yml b/Taskfile.yml index 28cf7428..5adf7698 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -61,7 +61,7 @@ tasks: docs: desc: Create sphinx documentation - deps: [about, sbom] + deps: [about, zipnotebooks] cmds: - ./scripts/builder.sh /bin/bash -c "cd docs && make clean && make html" @@ -71,12 +71,6 @@ tasks: cmds: - ./scripts/builder.sh black archivist examples functests unittests - type-check: - desc: Runs the pyright type checker against the core archivst files - deps: [about] - cmds: - - ./scripts/builder.sh pyright archivist - functests: desc: Run functests - requires an archivist instance and a authtoken deps: [about] @@ -106,14 +100,30 @@ tasks: cmds: - ./scripts/builder.sh ./scripts/sbom.sh + type-check: + desc: Runs the pyright type checker against the core archivist files + deps: [about] + cmds: + - ./scripts/builder.sh python3 -m pyright archivist + unittests: desc: Run unittests deps: [about] cmds: - ./scripts/builder.sh ./scripts/unittests.sh + venv: + desc: Builds the virtual environment + cmds: + - ./scripts/venv.sh + wheel: desc: Builds python wheel package deps: [about] cmds: - ./scripts/builder.sh ./scripts/wheel.sh + + zipnotebooks: + desc: Zips notebooks so they can be downloaded + cmds: + - ./scripts/builder.sh ./scripts/zipnotebooks.sh diff --git a/notebooks/Check Asset Compliance using CURRENT OUTSTANDING Policy.ipynb b/archivist/notebooks/Check Asset Compliance using CURRENT OUTSTANDING Policy.ipynb similarity index 92% rename from notebooks/Check Asset Compliance using CURRENT OUTSTANDING Policy.ipynb rename to archivist/notebooks/Check Asset Compliance using CURRENT OUTSTANDING Policy.ipynb index d1f4d7ce..6fba266e 100644 --- a/notebooks/Check Asset Compliance using CURRENT OUTSTANDING Policy.ipynb +++ b/archivist/notebooks/Check Asset Compliance using CURRENT OUTSTANDING Policy.ipynb @@ -1,5 +1,14 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "d89c5225", + "metadata": {}, + "source": [ + "Create Asset Compliance: CURRENT_OUTSTANDING policy\n", + "-------------------------------------------------------------------------------------" + ] + }, { "cell_type": "code", "execution_count": null, @@ -44,9 +53,9 @@ "source": [ "# Connection parameters. Fill in with client ID and secret from an appropriately\n", "# permissioned Application Registration\n", - "RKVST_URL=\"https://app.rkvst.io\"\n", - "APPREG_CLIENT=\"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n", - "APPREG_SECRET=\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"" + "RKVST_URL = \"https://app.rkvst.io\"\n", + "APPREG_CLIENT = \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n", + "APPREG_SECRET = \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"" ] }, { @@ -135,7 +144,7 @@ " {\n", " \"arc_description\": \"Open the door for Lucius Malfoy\",\n", " \"arc_display_type\": \"Open\",\n", - " \"arc_correlation_value\": f\"{tag}\"\n", + " \"arc_correlation_value\": f\"{tag}\",\n", " },\n", " confirm=True,\n", " )\n", @@ -162,7 +171,7 @@ " {\n", " \"arc_description\": \"Closed the door after Lucius Malfoy exited the vault\",\n", " \"arc_display_type\": \"Close\",\n", - " \"arc_correlation_value\": f\"{tag}\"\n", + " \"arc_correlation_value\": f\"{tag}\",\n", " },\n", " confirm=True,\n", " )\n", @@ -190,10 +199,7 @@ "\n", "# Initialize connection to RKVST\n", "print(\"Connecting to RKVST\")\n", - "arch = Archivist(\n", - " RKVST_URL,\n", - " (APPREG_CLIENT, APPREG_SECRET)\n", - ")" + "arch = Archivist(RKVST_URL, (APPREG_CLIENT, APPREG_SECRET))" ] }, { @@ -207,7 +213,7 @@ "source": [ "# Compliance policies with related events (eg open/close, order/ship/deliver\n", "# type situations) require events to be linked through a correlation value.\n", - "# In many cases this will be obvious (a CVE tag for vulnerability management,\n", + "# In many cases this will be obvious (a CVE tag for vulnerability management,\n", "# or a works ticket number for maintenance, or even a timestamp) but here\n", "# we'll just make a UUID to make sure it's unique and this test is repeatable\n", "tag = uuid4()\n", @@ -291,8 +297,7 @@ "# arbitrary time in a real forensic process\n", "time_of_suspicion = compliance_nok[\"compliant_at\"]\n", "compliance_nok = arch.compliance.compliant_at(\n", - " gringotts_vault[\"identity\"],\n", - " compliant_at=time_of_suspicion\n", + " gringotts_vault[\"identity\"], compliant_at=time_of_suspicion\n", ")\n", "print(\"HISTORICAL COMPLIANCE (should be false):\", json_dumps(compliance_nok, indent=4))" ] @@ -327,7 +332,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.13" + "version": "3.7.15" } }, "nbformat": 4, diff --git a/notebooks/Check Asset Compliance using SINCE Policy.ipynb b/archivist/notebooks/Check Asset Compliance using SINCE Policy.ipynb similarity index 96% rename from notebooks/Check Asset Compliance using SINCE Policy.ipynb rename to archivist/notebooks/Check Asset Compliance using SINCE Policy.ipynb index 38b0eb22..7bf09e90 100644 --- a/notebooks/Check Asset Compliance using SINCE Policy.ipynb +++ b/archivist/notebooks/Check Asset Compliance using SINCE Policy.ipynb @@ -1,5 +1,14 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "8b5e7251", + "metadata": {}, + "source": [ + "Check Asset Compliance: SINCE policy\n", + "================================\n" + ] + }, { "cell_type": "code", "execution_count": null, @@ -44,8 +53,8 @@ "metadata": {}, "outputs": [], "source": [ - "URL=\"https://app.rkvst.io\"\n", - "URL=\"https://app.dev-paul-0.wild.jitsuin.io\"" + "URL = \"https://app.rkvst.io\"\n", + "URL = \"https://app.dev-paul-0.wild.jitsuin.io\"" ] }, { @@ -260,7 +269,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.13" + "version": "3.7.15" } }, "nbformat": 4, diff --git a/notebooks/Create Event with Verified Domain.ipynb b/archivist/notebooks/Create Event with Verified Domain.ipynb similarity index 97% rename from notebooks/Create Event with Verified Domain.ipynb rename to archivist/notebooks/Create Event with Verified Domain.ipynb index e4246c2c..be6d3217 100644 --- a/notebooks/Create Event with Verified Domain.ipynb +++ b/archivist/notebooks/Create Event with Verified Domain.ipynb @@ -1,5 +1,14 @@ { "cells": [ + { + "cell_type": "markdown", + "id": "5950c6ba", + "metadata": {}, + "source": [ + "Create Event With Verified Domain\n", + "============================\n" + ] + }, { "cell_type": "code", "execution_count": null, @@ -11,7 +20,7 @@ "#\n", "# The module contains four functions: main, create_asset, create_event and\n", "# get_verified_domain.\n", - "# \n", + "#\n", "# The main function would initialize an archivist connection using the url and\n", "# the credentials, called \"arch\".\n", "\n", @@ -46,7 +55,7 @@ "metadata": {}, "outputs": [], "source": [ - "URL=\"https://app.rkvst.io\"" + "URL = \"https://app.rkvst.io\"" ] }, { @@ -269,7 +278,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.13" + "version": "3.7.15" } }, "nbformat": 4, diff --git a/archivist/notebooks/Manage_Credentials.ipynb b/archivist/notebooks/Manage_Credentials.ipynb new file mode 100644 index 00000000..622c07e2 --- /dev/null +++ b/archivist/notebooks/Manage_Credentials.ipynb @@ -0,0 +1,206 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "350e6df8", + "metadata": {}, + "source": [ + "Manage Credentials\n", + "================\n" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "79ec6439", + "metadata": {}, + "outputs": [], + "source": [ + "# Management of authorization credentials\n", + "#\n", + "# Demonstrating the use of the JWT or application credentials.\n", + "# All variables are retrieved from the environment for demonstration purposes.\n", + "#\n", + "# Part 1 - creating an Archivist Instance using a JWT\n", + "# Part 2 - creating an Archivist Instance using an application id and secret\n", + "\n", + "from os import getenv\n", + "\n", + "from archivist.archivist import Archivist" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "id": "05b3c08d", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "URL https://app.rkvst.io\n" + ] + } + ], + "source": [ + "# Retrieve the URL\n", + "\n", + "URL = getenv(\"TEST_ARCHIVIST\")\n", + "print(\"URL\", URL)" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "id": "e07100c6", + "metadata": {}, + "outputs": [], + "source": [ + "# Part 1. Using a JWT token\n", + "#\n", + "# The following steps detail how to use a full JWT bearer token." + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "id": "0bcf6c82", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "auth_token xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n" + ] + } + ], + "source": [ + "# extract JWT from environment\n", + "\n", + "auth_token = getenv(\"TEST_AUTHTOKEN\")\n", + "print(\"auth_token\", auth_token)" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "id": "ceefc550", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Archivist(https://app.rkvst.io)\n" + ] + } + ], + "source": [ + "# Using the JWT to create an Archivist instance\n", + "\n", + "with Archivist(URL, auth_token) as arch:\n", + " print(arch)" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "id": "097756e3", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "client_id yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy\n", + "client_secret zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz\n" + ] + } + ], + "source": [ + "# Part 2 Usng an application client id and secret\n", + "#\n", + "# To create a new application refer to https://app.rkvst.io/developers and scroll down to the\n", + "# AppRegistrations POST /archivist/iam/v1/application. Click on 'Try It Out', fill in the request body with a\n", + "# required display name. Custom claims can be deleted from the example in most cases.\n", + "\n", + "client_id = getenv(\"TEST_CLIENT_ID\")\n", + "print(\"client_id\", client_id)\n", + "\n", + "client_secret = getenv(\"TEST_CLIENT_SECRET\")\n", + "print(\"client_secret\", client_secret)" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "id": "f328d435", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Archivist(https://app.rkvst.io)\n" + ] + } + ], + "source": [ + "# Using the application id and secret to create an Archivist instance\n", + "\n", + "with Archivist(URL, (client_id, client_secret)) as arch:\n", + " print(arch)" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "id": "cfb47ff4", + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Archivist(https://app.rkvst.io)\n" + ] + } + ], + "source": [ + "# For convenience all this functionality has been emcapsulated in a convenience function\n", + "from archivist.utils import get_auth\n", + "\n", + "auth = get_auth(\n", + " auth_token=getenv(\"TEST_AUTHTOKEN\"),\n", + " client_id=getenv(\"TEST_CLIENT_ID\"),\n", + " client_secret=getenv(\"TEST_CLIENT_SECRET\"),\n", + ")\n", + "with Archivist(URL, auth) as arch:\n", + " print(arch)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.7.15" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/notebooks/Share_Asset.ipynb b/archivist/notebooks/Share_Asset.ipynb similarity index 94% rename from notebooks/Share_Asset.ipynb rename to archivist/notebooks/Share_Asset.ipynb index 5969d76a..3066db12 100644 --- a/notebooks/Share_Asset.ipynb +++ b/archivist/notebooks/Share_Asset.ipynb @@ -38,7 +38,7 @@ "metadata": {}, "outputs": [], "source": [ - "URL=\"https://app.rkvst.io\"" + "URL = \"https://app.rkvst.io\"" ] }, { @@ -98,7 +98,9 @@ " # The token can represent the root principal or user in an organization. Different tokens\n", " # could indicate different users in the same organization or membership of different\n", " # organiastions.\n", - " with open(f\"/home/builder/credentials/{label}_token\", mode=\"r\", encoding=\"utf-8\") as tokenfile:\n", + " with open(\n", + " f\"/home/builder/credentials/{label}_token\", mode=\"r\", encoding=\"utf-8\"\n", + " ) as tokenfile:\n", " auth_token = tokenfile.read().strip()\n", "\n", " # Initialize connection to Archivist. max_time is the time to wait for confirmation\n", @@ -175,7 +177,7 @@ " ],\n", " },\n", " ]\n", - " \n", + "\n", " return arch.access_policies.create(\n", " props,\n", " filters,\n", @@ -231,7 +233,9 @@ "source": [ "# set a subject for weyland in acme's environment. The identity will be used as a\n", "# filter in the access permissions of the access_policy.\n", - "weyland_subject_on_acme, acme_subject_on_weyland = share_subjects(\"weyland on acme\", acme, \"acme_on_weyland\", weyland)\n", + "weyland_subject_on_acme, acme_subject_on_weyland = share_subjects(\n", + " \"weyland on acme\", acme, \"acme_on_weyland\", weyland\n", + ")\n", "print(\"weyland_subject on acme\", json_dumps(weyland_subject_on_acme, indent=4))\n", "print(\"acme_subject on acme\", json_dumps(acme_subject_on_weyland, indent=4))" ] @@ -269,7 +273,9 @@ "outputs": [], "source": [ "# list matching access policies\n", - "access_policies = list(acme.access_policies.list_matching_access_policies(acme_asset[\"identity\"]))\n", + "access_policies = list(\n", + " acme.access_policies.list_matching_access_policies(acme_asset[\"identity\"])\n", + ")\n", "print(\"access policies read from acme\", json_dumps(access_policies, indent=4))" ] }, @@ -295,7 +301,9 @@ "outputs": [], "source": [ "# list matching access policies\n", - "access_policies = list(acme.access_policies.list_matching_access_policies(acme_asset[\"identity\"]))\n", + "access_policies = list(\n", + " acme.access_policies.list_matching_access_policies(acme_asset[\"identity\"])\n", + ")\n", "print(\"access policies read from acme\", json_dumps(access_policies, indent=4))" ] }, @@ -329,7 +337,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.7.13" + "version": "3.7.15" } }, "nbformat": 4, diff --git a/archivist/parser.py b/archivist/parser.py index be77d027..b402b4bd 100644 --- a/archivist/parser.py +++ b/archivist/parser.py @@ -54,11 +54,17 @@ def __call__(self, parser, namespace, values, option_string=None): setattr(namespace, self.dest, value) -def common_parser(description: str): - """Construct parser with security option for token/auth authentication""" +def simple_parser(description: str): + """Construct parser with bare minimum features""" parser = argparse.ArgumentParser( description=description, ) + return parser + + +def common_parser(description: str): + """Construct parser with security option for token/auth authentication""" + parser = simple_parser(description) parser.add_argument( "-v", "--verbose", diff --git a/docs/conf.py b/docs/conf.py index 094e5524..0cd50876 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,6 +32,8 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "nbsphinx", + "sphinx_gallery.load_style", "sphinx_rtd_theme", "sphinxcontrib.spelling", "sphinx.ext.autodoc", @@ -48,8 +50,17 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'scripts', 'unittests', 'functests'] +exclude_patterns = [ + '_build', + 'Thumbs.db', + '.DS_Store', + 'scripts', + 'unittests', + 'functests', + '**.ipynb_checkpoints', +] +source_suffix = [ '.md', '.rst'] # -- Options for HTML output ------------------------------------------------- @@ -57,31 +68,33 @@ # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' -html_theme_options = { - 'analytics_id': 'G-7K46H3KK7N', # Provided by Google in your dashboard - 'logo_only': True, -} -html_logo = '_static/RKVST_WhtLogo_RGB.png' +# These paths are either relative to html_static_path +# or fully qualified paths (eg. https://...) +html_css_files = [ + 'css/rkvst_theme.css', +] html_favicon = "_static/favicon.ico" +html_logo = '_static/RKVST_WhtLogo_RGB.png' html_show_sourcelink = False html_show_sphinx = False - - -spelling_lang='en_US' -spelling_word_list_filename='spelling_wordlist.txt' -spelling_show_suggestions=True -spelling_verbose=True - -source_suffix = [ '.md', '.rst'] # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -# These paths are either relative to html_static_path -# or fully qualified paths (eg. https://...) +html_theme = 'sphinx_rtd_theme' +html_theme_options = { + 'analytics_id': 'G-7K46H3KK7N', # Provided by Google in your dashboard + 'logo_only': True, +} + + +# -- Notebooks ------------------------------------------------- +nbsphinx_execute = 'never' + +# -- Spelling ------------------------------------------------- +spelling_lang = 'en_US' +spelling_word_list_filename ='spelling_wordlist.txt' +spelling_show_suggestions = True +spelling_verbose = True -html_css_files = [ - 'css/rkvst_theme.css', -] diff --git a/docs/index.rst b/docs/index.rst index 0adc785b..d39e611e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ features getting_started + notebooks fixtures code/index diff --git a/docs/notebooks.rst b/docs/notebooks.rst new file mode 100644 index 00000000..4e4efcab --- /dev/null +++ b/docs/notebooks.rst @@ -0,0 +1,86 @@ +.. _notebooksref: + +Note Books (BETA) +================= + +.. note:: + + This feature is a Work-In-Progress + +These are a collection of jupyter notebooks that demonstrate typical use cases of the RKVST +system. + +They can be downloaded and executed on a Linux, Mac or Windows machines. The only requirement +is that python3.7 to python3.11 and pip command-line too have been installed. + +Installing the RKVST python SDK +............................... + +The bare requirement is that a version of python3 (3.7 to 3.11) is installed together with +the pip command-line tool. + +Linux +~~~~~ + +Most Linux distros come with a suitable version of python3 already installed. The only extra requirement +is to install the pip command-line utility. + +.. code:: bash + + python3 -m ensurepip --upgrade + +MacOS +~~~~~ + +Python installation instructions for MacOS are `pythonmac installation instructions`_ + +.. _pythonmac installation instructions: https://www.python.org/downloads/macos/ + +Open a terminal and ensure that python and pip are available: + +.. code:: bash + + python --version + pip --version + +Windows +~~~~~~~ + +Python installation instructions for Windows are `pythonwindows installation instructions`_ + +.. _pythonwindows installation instructions: https://www.python.org/downloads/windows/ + +Execute the installer. Ensure the following: + +* Installation of pip is enabled +* py launcher is enabled +* Associate file with python is enabled +* Create shortcuts for installed applications +* Add Python to Path + +Open a 'cmd' terminal and ensure that python and pip are available: + +.. code:: bash + + python --version + pip --version + +Download Notebooks +.................. + +.. only:: builder_html or readthedocs + + See :download:`Notebooks `. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + :name: Gallery + + notebooks/Manage_Credentials + notebooks/Check Asset Compliance using CURRENT OUTSTANDING Policy + notebooks/Check Asset Compliance using SINCE Policy + notebooks/Create Event with Verified Domain + notebooks/Share_Asset + + diff --git a/docs/notebooks/.gitignore b/docs/notebooks/.gitignore new file mode 100644 index 00000000..f16ecac7 --- /dev/null +++ b/docs/notebooks/.gitignore @@ -0,0 +1,3 @@ +.ipynb_checkpoints/ +notebooks.zip +*.ipynb diff --git a/docs/notebooks/requirements.txt b/docs/notebooks/requirements.txt new file mode 100644 index 00000000..b1d4c92b --- /dev/null +++ b/docs/notebooks/requirements.txt @@ -0,0 +1,9 @@ +# +# jupyter notebooks +ipython~=7.34 +jupyter~=1.0 +jupyterlab~=3.5 +jupyter-console~=6.4 +jupyter-contrib-nbextensions~=0.7 + +wheel diff --git a/docs/requirements.txt b/docs/requirements.txt index ff573822..6a8781e5 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,21 +1,10 @@ # # this is used for pushing to github pages # -# Duplicate of stanza in ~/requirements-dev.txt. -# Make changes in both places -sphinx~=4.4 -sphinx-rtd-theme~=1.0 -sphinxcontrib-spelling~=7.3 +sphinx~=5.3 +sphinx-rtd-theme~=1.1 +sphinxcontrib-spelling~=7.7 +sphinx-gallery~=0.11 +nbsphinx~=0.8 -# Duplicate of stanza in ~/requirements.txt. -# Make changes in both places -backoff~=1.11 -certifi -flatten-dict~=0.4 -iso8601~=1.0 -Jinja2~=3.0 -pyaml-env~=1.1 -requests~=2.27 -requests-toolbelt~=0.9 -rfc3339~=6.2 -xmltodict~=0.12.0 +-r notebooks/requirements.txt diff --git a/docs/sbom.xml b/docs/sbom.xml index a17e9a22..bca0d336 100644 --- a/docs/sbom.xml +++ b/docs/sbom.xml @@ -1,11 +1,11 @@ - + - 2022-10-31T16:54:42.744172+00:00 + 2022-12-16T16:29:00.460158+00:00 CycloneDX cyclonedx-python-lib - 3.1.0 + 3.1.1 https://github.com/CycloneDX/cyclonedx-python-lib/actions @@ -36,87 +36,102 @@ - + backoff 1.11.1 - + certifi - 2022.9.24 + 2022.12.7 - + charset-normalizer 2.1.1 - + flatten-dict 0.4.2 - + idna 3.4 - + + importlib-metadata + 5.1.0 + + iso8601 1.1.0 - + jinja2 3.1.2 - + markupsafe 2.1.1 - + pyaml-env - 1.1.5 + 1.2.1 - + pyyaml - 5.4.1 + 6.0 - + requests 2.28.1 - + requests-toolbelt 0.10.1 - + rfc3339 6.2 - + six 1.16.0 - + + typing-extensions + 4.4.0 + + urllib3 - 1.26.12 + 1.26.13 - + xmltodict 0.13.0 + + zipp + 3.11.0 + - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index 33a7ad0f..811b847a 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -9,6 +9,7 @@ dataclass dataclasses dialogs dicts +distros ef fd fda @@ -21,6 +22,7 @@ jinja jitsuin jpg json +jupyter Khipus kwargs macclesfield @@ -28,6 +30,7 @@ mimetype onwards params publicurl +py sbom sboms sbomType diff --git a/notebooks/.gitignore b/notebooks/.gitignore deleted file mode 100644 index 87620ac7..00000000 --- a/notebooks/.gitignore +++ /dev/null @@ -1 +0,0 @@ -.ipynb_checkpoints/ diff --git a/requirements-dev.txt b/requirements-dev.txt index 4ff23a3f..ecd9a0ec 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -2,33 +2,23 @@ # code quality autopep8~=1.6 -black~=22.6 +black[jupyter]~=22.6 coverage[toml]~=6.4 pip-audit~=2.4 pycodestyle~=2.9 pylint~=2.14 pyright~=1.1.271 unittest-xml-reporting~=3.2.0 +testbook~=0.4 + +# analyze dependencies +pipdeptree~=2.2 # uploading to pypi build~=0.8 twine~=4.0 -# documentation -# the file docs/requirements.txt -# must be kept in sync with this file. -sphinx~=5.1 -sphinx-rtd-theme~=1.0 -sphinxcontrib-spelling~=7.6 +# for sbom.xml file xq~=0.0 -# analyze dependencies -pipdeptree~=2.2 - -# for jupyter notebooks -ipython~=7.34 -jupyter~=1.0 -jupyterlab~=3.4 -jupyter-console~=6.4 - - +-r docs/requirements.txt diff --git a/scripts/build.sh b/scripts/build.sh index 680752da..2c827c02 100755 --- a/scripts/build.sh +++ b/scripts/build.sh @@ -13,7 +13,6 @@ then fi docker build \ - --no-cache \ --build-arg VERSION="$1" \ -f Dockerfile-builder \ - -t jitsuin-archivist-python-builder . + -t archivist-python-builder . diff --git a/scripts/builder.sh b/scripts/builder.sh index 9fcfce99..4da0c185 100755 --- a/scripts/builder.sh +++ b/scripts/builder.sh @@ -31,5 +31,5 @@ docker run \ -e TEST_DEBUG \ -e TEST_REFRESH_TOKEN \ -e GITHUB_REF \ - jitsuin-archivist-python-builder \ + archivist-python-builder \ "$@" diff --git a/scripts/notebooks.sh b/scripts/notebooks.sh index 43f656c9..78557b03 100755 --- a/scripts/notebooks.sh +++ b/scripts/notebooks.sh @@ -1,7 +1,9 @@ -#!/bin/sh +#!/bin/bash # -# run jupyter notebooks +# run jupyter notebooks in a virtual environment # +# requires the rkvst-venv virtual environment to be present +# ('task venv') if [ "$USER" = "builder" -o "$USER" = "vscode" ] then @@ -9,11 +11,13 @@ then exit 0 fi -docker run --rm -it \ - -v $(pwd):/home/builder \ - -u $(id -u):$(id -g) \ - -p 8888:8888 \ - -e PYTHONPATH=/home/builder \ - jitsuin-archivist-python-builder \ - jupyter notebook --ip 0.0.0.0 --no-browser --notebook-dir=/home/builder/notebooks +NOTEBOOKDIR=rkvst-venv/notebooks +source rkvst-venv/bin/activate +mkdir -p "${NOTEBOOKDIR}" + +# The customer will download the notebooks from python.rkvst.com but +# we will copy locally +cp archivist/notebooks/*.ipynb "${NOTEBOOKDIR}"/ +jupyter notebook --ip 0.0.0.0 --notebook-dir="${NOTEBOOKDIR}" +deactivate diff --git a/scripts/shell.sh b/scripts/shell.sh new file mode 100755 index 00000000..8f7e4e28 --- /dev/null +++ b/scripts/shell.sh @@ -0,0 +1,19 @@ +#!/bin/sh +# +# Shells into the builder container +# + +if [ "$USER" = "builder" -o "$USER" = "vscode" ] +then + "$@" + exit 0 +fi + +set -x +# If no arguments simply shell into builder image +docker run \ + --rm -it \ + -v $(pwd):/home/builder \ + -u $(id -u):$(id -g) \ + archivist-python-builder \ + "/bin/bash" diff --git a/scripts/venv.sh b/scripts/venv.sh new file mode 100755 index 00000000..529ab069 --- /dev/null +++ b/scripts/venv.sh @@ -0,0 +1,19 @@ +#!/bin/bash +# +# recreate virtual environment +# +# requires the wheel to be present in dist/ (execute 'task wheel') + +if [ "$USER" = "builder" -o "$USER" = "vscode" ] +then + echo "Cannot run notebooks.sh inside container" + exit 0 +fi + +rm -rf rkvst-venv +python3 -m venv rkvst-venv +source rkvst-venv/bin/activate +python3 -m pip install --force-reinstall wheel +python3 -m pip install --force-reinstall dist/jitsuin_archivist-*.whl +python3 -m pip install --force-reinstall -r docs/notebooks/requirements.txt +deactivate diff --git a/scripts/zipnotebooks.sh b/scripts/zipnotebooks.sh new file mode 100755 index 00000000..0fec0e75 --- /dev/null +++ b/scripts/zipnotebooks.sh @@ -0,0 +1,21 @@ +#!/bin/sh +# +# Zips all notebooks so they can be downloaded from Sphinx-generated +# documentation. +# +INDIR=archivist/notebooks +if [ ! -d "${INDIR}" ] +then + echo "${INDIR} does not exist" + exit 1 +fi +OUTDIR=docs/notebooks +if [ ! -d "${OUTDIR}" ] +then + echo "${OUTDIR} does not exist" + exit 1 +fi +cp "${INDIR}"/*.ipynb "${OUTDIR}" +cd "${OUTDIR}" +rm -f notebooks.zip +zip notebooks.zip *.ipynb diff --git a/setup.cfg b/setup.cfg index 860bc59d..5a20f905 100644 --- a/setup.cfg +++ b/setup.cfg @@ -15,7 +15,7 @@ license = MIT license_files = LICENSE classifiers = - Development Status :: 3 - Alpha + Development Status :: 4 - Beta Environment :: Console Intended Audience :: Developers License :: OSI Approved :: MIT License @@ -36,6 +36,7 @@ packages = archivist.cmds.runner archivist.cmds.template +include_package_data = True platforms = any python_requires = >=3.7 setup_requires = setuptools-git-versioning diff --git a/unittests/testnotebooks.py b/unittests/testnotebooks.py new file mode 100644 index 00000000..97755bb7 --- /dev/null +++ b/unittests/testnotebooks.py @@ -0,0 +1,83 @@ +""" +Test notebooks +""" +import os +from unittest import TestCase + +from testbook import testbook + +from archivist.archivist import Archivist + +# pylint: disable=missing-function-docstring + + +def setenv(key, newvalue): + val = os.getenv(key) + os.environ[key] = newvalue + return val + + +def unsetenv(key, oldvalue): + if oldvalue is not None: + os.environ[key] = oldvalue + else: + del os.environ[key] + + +class TestNotebooks(TestCase): + """ + Test notebooks + """ + + def setUp(self): + self.archivist = setenv("TEST_ARCHIVIST", "https://app.rkvst.io") + self.authtoken = setenv("TEST_AUTHTOKEN", "xxxxxxxxxxxxxxxxxxxx") + self.client_id = setenv("TEST_CLIENT_ID", "yyyyyyyyyyyyyyyyyyyy") + self.client_secret = setenv("TEST_CLIENT_SECRET", "zzzzzzzzzzzzzzzzzzzz") + + def tearDown(self): + unsetenv("TEST_ARCHIVIST", self.archivist) + unsetenv("TEST_AUTHTOKEN", self.authtoken) + unsetenv("TEST_CLIENT_ID", self.client_id) + unsetenv("TEST_CLIENT_SECRET", self.client_secret) + + def test_manage_credentials(self): + """ + Test manage_credentials + """ + with testbook( + "archivist/notebooks/Manage_Credentials.ipynb", execute=True + ) as notebook: + self.assertEqual( + notebook.ref("URL"), + os.getenv("TEST_ARCHIVIST"), + msg="Incorrect URL", + ) + self.assertEqual( + notebook.ref("auth_token"), + os.getenv("TEST_AUTHTOKEN"), + msg="Incorrect AUTHTOKEN", + ) + self.assertEqual( + notebook.cell_output_text(5), + str( + Archivist(os.getenv("TEST_ARCHIVIST"), os.getenv("TEST_AUTHTOKEN")) + ), + msg="Incorrect Archivist", + ) + self.assertEqual( + notebook.cell_output_text(6), + """client_id yyyyyyyyyyyyyyyyyyyy +client_secret zzzzzzzzzzzzzzzzzzzz""", + msg="Incorrect client id and secret", + ) + self.assertEqual( + notebook.cell_output_text(7), + "Archivist(https://app.rkvst.io)", + msg="Incorrect Archivist", + ) + self.assertEqual( + notebook.cell_output_text(8), + "Archivist(https://app.rkvst.io)", + msg="Incorrect Archivist", + )