pyproject.toml (for more details, see specification
and tutorial)
is the configuration file that packaging tools can use to build a Python package.
The file includes the package's name, description,
dependencies,
among other relevant info. A minimal package directory with a module and
corresponding unit test should resemble:
.
├── pyproject.toml
├── src
│ └── python_pkg_tmpl
│ ├── __init__.py
│ └── tmpl_module.py
└── tests
└── test_tmpl_module.pyCommon installation patterns:
- Regular installl within package repo:
pip install . - Editable
install:
pip install -e . - Install with optional dependencies (as specified in
pyproject.toml, heretest):pip install ".[test]"
NOTE: double quote is needed in
zshto avoid "no matches" error.
The package uses ruff for linting,
with both a pre-commit hook
and a checking step in the package build GitHub action.
Checks should use ruff's default rules
except from line length (specified in pyproject.toml).
A plugin is also available for VSCode.
API documentation is generated with mkdocstrings.
Following the recipe for Python,
the gen_api_pages.py script
is executed during mkdocs execution to generate Markdown pages for all source files.
For the Python docstrings to be handled correctly by mkdocstrings, they must
be either in Google, Numpy, or Sphinx style (see docs).
If not specified, the default style is Google.
The package should be built and tested with latest stable Python version, as well as versions shipped with supported Linux distributions, e.g. 3.10 for Ubuntu 22.04 and 3.12 for Ubuntu 24.04.
For Python packages, a file/data-based license like MPL v2.0
would be preferred. This requires adding to each source file a comment with the corresponding
SPDX Identifier, e.g. SPDX-License-Identifier: MPL-2.0.