JupyterHub Authenticator and Spawner for the BriCS JupyterHub service
The package uses a "src layout". It should be installed to run or develop the code.
It is recommended to first create a virtual environment
python -m venv --upgrade-deps /path/to/my-venvthen install the package into the virtual environment.
/path/to/my-venv/bin/python -m pip install "bricsauthenticator @ git+https://github.com/isambard-sc/bricsauthenticator.git"Clone the repository
git clone https://github.com/isambard-sc/bricsauthenticator.gitThen install into the virtual environment using the path to the cloned repository
/path/to/my-venv/bin/python -m pip install /path/to/bricsauthenticatorAn editable install is useful when developing. This adds files in the source directory to the Python import path, so edits to the source code are reflected in the installed package.
/path/to/my-venv/bin/python -m pip install -e /path/to/bricsauthenticatorNote
Edits to project metadata will still require reinstallation of the package.
Clone the repository
git clone https://github.com/isambard-sc/bricsauthenticator.gitBuild the distribution (requires build)
python -m build /path/to/bricsauthenticatorInstall from the sdist or wheel placed in the dist/ directory
/path/to/my-venv/bin/python -m pip install /path/to/bricsauthenticator/dist/bricsauthenticator-{version}.tar.gz/path/to/my-venv/bin/python -m pip install /path/to/bricsauthenticator/dist/bricsauthenticator-{version}-py3-none-any.whlUse the [dev] optional dependency to install development tools (linting, formatting, testing etc.) alongside the bricsauthenticator package.
This is useful in combination with an editable install from a local copy of the repository. The local copy can then be worked with using the development tools.
/path/to/my-venv/bin/python -m pip install -e '/path/to/bricsauthenticator[dev]'JupyterHub depends on configurable-http-proxy, an npm package. This can be installed using npm, as described in the JupyterHub Quickstart documentation. It can also be installed using conda, from conda-forge.
To set up a development Conda environment containing an editable pip installation of bricsauthenticator (with development dependencies from pip) and external dependencies met using Conda packages, use environment-dev.yml, e.g.
conda env create -f environment-dev.ymlNote
This must be run from the root of the repository, since a relative path is used to install the bricsauthenticator package.
A dev container metadata JSON file (devcontainer.json) is provided that defines a bricsauthenticator development environment with the following characteristics
- Official JupyterHub Docker image as base image
- Development tooling installed in base image via accompanying Containerfile
- Run as root inside container
- Forward port 8000 (the default listening port for JupyterHub's public proxy)
- Editable pip install of source code in local workspace
The dev environment can be launched using dev-container-compatible tooling, e.g. VSCode (with Dev Containers extension) and GitHub Codespaces.
Within the container image JupyterHub is preinstalled as a pip package. On container creation, an editable pip install of bricsauthenticator with development dependencies is performed (from the local copy of the source code bind-mounted into the container). This allows development and testing of the source code within the running dev container.
It is recommended to develop in a virtual environment, with an editable install of the package, and development tools installed. The dev container automatically performs an editable development install of the package on container creation.
Source documentation should be done using docstrings (see e.g. PEP-257) using Sphinx style convention
Check source files for issues (no modification):
make lintIn-place modification of source files to fix issues:
make formatRun tests for package:
make test