kwandl
developer documentation
If you’re looking for user documentation, go here.
Development install
# Create a virtual environment, e.g. with
python3 -m venv env
# activate virtual environment
source env/bin/activate
# make sure to have a recent version of pip and setuptools
python3 -m pip install --upgrade pip setuptools
# (from the project root directory)
# install kwandl as an editable package
python3 -m pip install --no-cache-dir --editable .
# install development dependencies
python3 -m pip install --no-cache-dir --editable .[dev]
Afterwards check that the install directory is present in the PATH
environment variable.
Running the tests
Running the tests requires an activated virtual environment with the development tools installed.
pytest -v
Running linters locally
For linting we will use prospector and to sort imports we will use isort. Running the linters requires an activated virtual environment with the development tools installed.
# linter
prospector
# recursively check import style for the kwandl module only
isort --recursive --check-only kwandl
# recursively check import style for the kwandl module only and show
# any proposed changes as a diff
isort --recursive --check-only --diff kwandl
# recursively fix import style for the kwandl module only
isort --recursive kwandl
To fix readability of your code style you can use yapf.
You can enable automatic linting with prospector
and isort
on commit by enabling the git hook from .githooks/pre-commit
, like so:
git config --local core.hooksPath .githooks
Generating the API docs
cd docs
make html
The documentation will be in docs/_build/html
If you do not have make
use
sphinx-build -b html docs docs/_build/html
To find undocumented Python objects run
cd docs
make coverage
cat _build/coverage/python.txt
To test snippets in documentation run
cd docs
make doctest
Versioning
Bumping the version across all files is done with bumpversion, e.g.
bumpversion major
bumpversion minor
bumpversion patch
Making a release
This section describes how to make a release in 3 parts:
preparation
making a release on PyPI
making a release on GitHub
(1/3) Preparation
Update the <CHANGELOG.md> (don’t forget to update links at bottom of page)
Verify that the information in
CITATION.cff
is correct, and that.zenodo.json
contains equivalent dataMake sure the version has been updated.
Run the unit tests with
pytest -v
(2/3) PyPI
In a new terminal, without an activated virtual environment or an env directory:
# create the source distribution and the wheel
python3 -m build
# upload to test pypi instance (requires credentials)
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
Visit https://test.pypi.org/project/kwandl and verify that your package was uploaded successfully. Keep the terminal open, we’ll need it later.
In a new terminal, without an activated virtual environment or an env directory:
cd $(mktemp -d kwandl-test.XXXXXX)
# prepare a clean virtual environment and activate it
python3 -m venv env
source env/bin/activate
# make sure to have a recent version of pip and setuptools
pip install --upgrade pip setuptools
# install from test pypi instance:
python3 -m pip -v install --no-cache-dir \
--index-url https://test.pypi.org/simple/ \
--extra-index-url https://pypi.org/simple kwandl
Check that the package works as it should when installed from pypitest.
Then upload to pypi.org with:
# Back to the first terminal,
# FINAL STEP: upload to PyPI (requires credentials)
twine upload dist/*
(3/3) GitHub
Don’t forget to also make a release on GitHub. If your repository uses the GitHub-Zenodo integration this will also trigger Zenodo into making a snapshot of your repository and sticking a DOI on it.