python-guidelines.rst (2764B)
1 Guidelines for Python Packages 2 ============================== 3 4 This document describes conventions used for Python repos in the Taler project. 5 6 7 Packaging 8 --------- 9 10 * We use `poetry <https://github.com/python-poetry/poetry>`__ for managing dependencies and dev-dependencies. 11 * The ``poetry.lock`` file must be committed to repo. 12 * Entry points **must not** be defined as shell scripts. Instead, use poetry's script facility to define entry points. This makes the package work on different platforms properly. 13 14 15 GNU Compatibility Layer 16 ----------------------- 17 18 In addition to the Python-native tooling, we provide a GNU-style interface for the build system. 19 The commands supported by every Python repo should be: 20 21 * ``./bootstrap``: Only necessary when the repo is checked out via git. 22 Initializes the build system and checks out git submodules if applicable. 23 * ``./configure``: Should check for build-time dependencies, **including** Python tooling. 24 * ``make``: Invoking make without a target should create the Python wheel for the project. 25 * ``make install``: Installation should **only** install the Python package 26 based on the wheel via ``pip``. Note that we can't do dependency tracking 27 properly, so the ``install`` target will always re-build the wheel and 28 install it. 29 * ``make pretty``: Should invoke the pretty-printer (``black`` for Python projects). 30 * ``make dist``: This should create the source tarball. 31 * ``make clean``: Should delete generated files. 32 33 The `build-common.git <https://git.taler.net/build-common.git/>`__ repository contains helpers 34 to make the GNU compatibility easier. Here are some hints for using it: 35 36 * The ``build-common.git`` repo should added as a submodule in the path ``build-system/taler-build-scripts`` 37 of the repository. 38 * The `bootstrap template <https://git.taler.net/build-common.git/tree/bootstrap.template>`__ should 39 be copied as ``./bootstrap`` to the root of the repository. 40 * The configure script is automatically created by ``./bootstrap``. 41 * Dependencies for the configure file are defined in ``build-system/configure.py``. 42 There is no documentation yet, but adjusting the `example file <https://git.taler.net/build-common.git/tree/testconfigure.py>`__ is a good starting point. 43 * The source distribution (``make dist``) should either be created via ``poetry build -f sdist`` 44 or using the `git-archive-all <https://git.taler.net/build-common.git/tree/archive-with-submodules/git_archive_all.py>`__. 45 46 Formatting 47 ---------- 48 49 * We follow `pep8 <https://www.python.org/dev/peps/pep-0008/>`__. 50 * Code should be auto-formatted with `black <https://github.com/psf/black>`__. 51 52 53 Distro Packaging 54 ---------------- 55 56 For Debian, we should try to use `wheel2deb <https://github.com/upciti/wheel2deb>`__.