Tooling¶
Packaging¶
If you want to package the project without its dependencies, use the following command:
$ poetry build -f wheel
Poetry will drop a wheel file in dist/.
Documentation¶
We use sphinx to build the project’s documentation. This includes all ReST
documents in docs/, plus autodocs generated from the source code’s
docstrings. It is build as static html by default in order to be easy to pick
up by servers:
$ sphinx-apidoc --no-toc --module-first -o docs/autodoc src/stenotype
$ sphinx-build docs/ public/ -b html
Type Checking¶
Since version 3.5, python supports type hinting. You can run a static type check with mypy like so:
$ mypy src/
Linting¶
This project’s code style is black. You can run a classic linter-style test
with the check flag:
$ black src/ tests/ --check
But it is recommended to use black’s auto-formatter in your editor of choice.
Security¶
Since we can’t check every dependency in-depth for security issues, we rely on safety to tell us which ones are known to deserve a closer look. You can run it on the current python environment, in case it is properly virtualized and activated:
$ safety check
Conversely, you can also use poetry 1 to generate a requirements.txt for
yor production dependencies and check that instead, which is a little safer and
more explicit:
$ poetry export -f requirements.txt > requirements.txt
$ safety check -r requirements.txt
But checking third party packages is not enough, we also need to check our own code. Or rather, we let bandit do it:
$ bandit -r src/
Once these two tools have run with zero issues, you can be reasonably confident that your code didn’t blow glaring security holes into the project.
Coverage¶
We use pytests to run the test suite, so using the coverage.py wrapper pytest-cov makes things quite simple:
$ pytest tests/ --cov
Unless it makes no sense or is difficult to achieve, we try to stick to 100% unit test coverage.
- 1
At the time of writing, the
exportcommand is only available in pre-releases 1.0.0a0 and up.