pynitrokey Developer Guide ========================== Setting Up The Environment -------------------------- Use ``make init`` to install ``pynitrokey``, its dependencies and the development tools inside a virtual environment in the ``venv`` folder. This virtual environment is also used by other targets in the Makefile like ``make check``. ``pynitrokey`` is installed in editable mode so that all changes to the source code also apply to the ``nitropy`` executable in the virtual environment. If dependencies are changed, run ``make update-venv`` to update the virtual environment. By default the development environment is isolated using venv, when set up using ``make init``. To run the ``nitropy`` from there call ``./venv/bin/nitropy``. This can be used as a shortcut ``make run ARGS="nk3 list"``, where ``ARGS`` is an optional argument to pass to ``nitropy``. Containerized Environment -------------------- Setting up a proper environment, matching the exact Python version, or having a newer one than it is supported, might be problematic for the development. For such cases it is handy to have development/test environment containerized, so it does not affect nor need changes in the host OS internals. For that Earthly tool is used, but any Docker-like tool will work. The common targets are listed in the main Makefile with the ``e`` suffix: - ``make builde`` - executes Earthly build process for the pynitrokey container image; - ``make rune`` - runs Docker container based on the pynitrokey image for a quick tests. Use ``DOCKER=podman`` to call ``podman`` binary instead of the default Docker. See https://earthly.dev/ for the Earthly setup instructions. Mind, that their binaries currently are not signed and cannot be verified, thus installation to the root directory of the host OS is not advised (on contrary to the claims on their main page). Use Dockerfile directly instead if in doubt. Linters ------- We use `flake8`_ for style checks, `black`_ for code formatting, `isort`_ for import sorting and `mypy`_ for static type analysis. To run all checks, execute ``make check``. Before using it for the first time, you have to call ``make init`` to setup a virtual environment and install the required dependencies. .. _flake8: https://flake8.pycqa.org/en/latest/ .. _black: https://github.com/psf/black .. _isort: https://github.com/PyCQA/isort .. _mypy: https://github.com/python/mypy mypy is configured to only check annotated code. If you add new code, please consider adding type annotations and enabling strict checks for your modules in ``pyproject.toml``. Please make sure that all checks pass for your code before opening a PR. Signed Commits -------------- If you have an OpenPGP key, please sign all your commits with it. We require all commits on the master branch to be signed. If you don’t have an OpenPGP key, a developer that reviewed your commits will sign them for you. Supported Python Versions ------------------------- The current minimum required Python version is documented in the readme. Make sure that your code works with this Python version. The minimum required Python version is selected to be compatible with the latest Ubuntu LTS and regular releases and with the latest Debian stable release. If there has not been a point release for the latest Ubuntu LTS release yet, we also support the second-latest Ubuntu LTS release. Raising the required Python version requires adapting the CI to this new minimum too. Commit Hooks -------------- For local quick checks of the formatting you can use `pre-commit`_. .. _pre-commit: https://pre-commit.com/ Setup:: $ pip install pre-commit -U $ pre-commit install Usage: - https://pre-commit.com/#usage Checks configured in ``.pre-commit-config.yaml`` will be executed before each commit, and on-demand when calling ``pre-commit`` from the command line. Patching the Nitrokey SDK ------------------------- To use an unreleased version of the Nitrokey Python SDK, replace the ``nitrokey`` dependency in ``pyproject.toml`` with:: "nitrokey @ git+https://github.com/Nitrokey/nitrokey-sdk-py.git@rev", ``rev`` can be a branch name, a tag or a commit hash. It is also possible to use a local path:: "nitrokey @ file:../nitrokey-sdk-py", Installing a Development Version -------------------------------- It is possible to install a development version of ``pynitrokey`` from the latest ``master`` branch using ``pipx``, for example:: $ pipx install git+https://github.com/Nitrokey/pynitrokey.git --suffix=-git The installed binary will be available as ``nitropy-git`` so that it can be used in parallel with a normal installation:: $ nitropy-git --help $ which nitropy-git $ which nitropy It is also possible to upgrade the development version to the latest ``master`` branch or to remove it:: $ pipx upgrade pynitrokey-git $ pipx uninstall pynitrokey-git Alternatively, you can install a development version from an open pull request, for example for PR #123:: $ export PULL_REQUEST=123 $ pipx install git+https://github.com/Nitrokey/pynitrokey.git@refs/pull/${PULL_REQUEST}/head --suffix=-pr${PULL_REQUEST} $ nitropy-pr123 --help $ pipx uninstall pynitrokey-pr123 Design Patterns --------------- Output and Error Handling ~~~~~~~~~~~~~~~~~~~~~~~~~ Use ``pynitrokey.helpers.local_print`` for printing messages to the user. This helper method also adds the output to the log file. To report an error, use ``pynitrokey.helpers.local_critical`` or raise a ``pynitrokey.cli.exceptions.CliException`` (that uses ``local_critical`` internally). Per default, this adds a support hint to the output that points the user to the log file. Password Input ~~~~~~~~~~~~~~ Commands that require a password should first try to read the password from an environment variable. If the environment variable is not set, they should prompt the user to enter the password. Passwords must not be passed as a command-line argument. Updating the NetHSM client -------------------------- The NetHSM client is now managed in a `separate repo `__ Error Message for Dependencies Updates ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When updating the dependencies, an error message appears in which the updated tool is more current than the registered version.