36 lines
2.9 KiB
Markdown
36 lines
2.9 KiB
Markdown
# Repository Template for Python 3.11 Projects with Cython Modules
|
|
|
|
## Tools for Project and Package Management
|
|
|
|
[](https://pdm-project.org)
|
|
[](https://github.com/astral-sh/ruff)
|
|
|
|
Python projects are managed with **PDM** ([link to GitHub Source](https://github.com/pdm-project/pdm)), a PEP-compliant project and dependency management tool.
|
|
The applicable settings are contained within the PyProject-TOML file. In order to use a repo which was created with this template is to tell PDM which Python interpreter to use and then to install the whole project into the created virtual environment. If the interpreter is not available you will need to install it via PDM.
|
|
|
|
```console
|
|
pdm use 3.11.11 # example of a given version
|
|
pdm install
|
|
```
|
|
|
|
This installs all mandatory development dependencies such as:
|
|
- Ruff (formatting and linting)
|
|
- pytest (unittest framework)
|
|
- coverage.py (measuring test coverage)
|
|
- pytest-cov (integration of coverage into pytest)
|
|
- pytest-xdist (allows to execute the tests on multiple CPU cores)
|
|
- bump-my-version (CLI tool to manage version bumping)
|
|
- Nox (Python runner, e.g. to run test suite on multiple Python versions)
|
|
- pdoc (to auto-generate documentation from docstrings)
|
|
- Jupyterlab and widgets (to perform fast prototyping and enable exploratory data analysis)
|
|
|
|
## Cython
|
|
|
|
This template repository assumes the need of [Cython](https://cython.org/) modules. Usually this is the case if the default Python performance is not sufficient or the code shall be obfuscated because of possible theft by a customer to whom it is shipped. Cython is convenient way to build C-Extensions for Python without the hustle of directly using Python's clumsy C-API. It is even possible to directly compile Python modules which have no Cython-specific code in them. Sometimes this alone yields performance gains. To achieve better results Cython's type annotation must be used and the interaction with the Python interpreter should be avoided, so that as much work as possible is done in the compiled C code.
|
|
|
|
Cython also supports C++ language compilation, even though it is not as well supported as C.
|
|
|
|
### Compilation
|
|
|
|
This repo still uses PDM to manage the project. Since PDM does not support building C extensions it is configured to call [setuptools](https://setuptools.pypa.io/en/latest/index.html). The invoked build script is defined in the file `setup.py` in the project's root directory. All Cython modules have to be defined in this file. Cython provides a convenience function `cythonize` to construct a list of `setuptools.Extension` instances which are handed over to the build process. Depending on the project the script needs adaptation to meet specific requirements.
|