path: root/python-guidelines.rst
diff options
authorFlorian Dold <>2020-11-09 17:39:08 +0100
committerFlorian Dold <>2020-11-09 17:42:11 +0100
commit1a0b90a645752152da6ffd1fe8279acdcb26a01e (patch)
treec6b654263127e3498e90a5418f5a6509a72fc88f /python-guidelines.rst
parent32e8e736f6707761ace157f515a55063a8814b07 (diff)
python guidelines
Diffstat (limited to 'python-guidelines.rst')
1 files changed, 56 insertions, 0 deletions
diff --git a/python-guidelines.rst b/python-guidelines.rst
new file mode 100644
index 0000000..f08b563
--- /dev/null
+++ b/python-guidelines.rst
@@ -0,0 +1,56 @@
+Guidelines for Python Packages
+This document describes conventions used for Python repos in the Taler project.
+* We use `poetry <>`__ for managing dependencies and dev-dependencies.
+* The ``poetry.lock`` file must be committed to repo.
+* 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.
+GNU Compatibility Layer
+In addition to the Python-native tooling, we provide a GNU-style interface for the build system.
+The commands supported by every Python repo should be:
+* ``./bootstrap``: Only necessary when the repo is checked out via git.
+ Initializes the build system and checks out git submodules if applicable.
+* ``./configure``: Should check for build-time dependencies, **including** Python tooling.
+* ``make``: Invoking make without a target should create the Python wheel for the project.
+* ``make install``: Installation should **only** install the Python package
+ based on the wheel via ``pip``. Note that we can't do dependency tracking
+ properly, so the ``install`` target will always re-build the wheel and
+ install it.
+* ``make pretty``: Should invoke the pretty-printer (``black`` for Python projects).
+* ``make dist``: This should create the source tarball.
+* ``make clean``: Should delete generated files.
+The `build-common.git <>`__ repository contains helpers
+to make the GNU compatibility easier. Here are some hints for using it:
+* The ``build-common.git`` repo should added as a submodule in the path ``build-system/taler-build-scripts``
+ of the repository.
+* The `bootstrap template <>`__ should
+ be copied as ``./bootstrap`` to the root of the repository.
+* The configure script is automatically created by ``./bootstrap``.
+* Dependencies for the configure file are defined in ``build-system/``.
+ There is no documentation yet, but adjusting the `example file <>`__ is a good starting point.
+* The source distribution (``make dist``) should either be created via ``poetry build -f sdist``
+ or using the `git-archive-all <>`__.
+* We follow `pep8 <>`__.
+* Code should be auto-formatted wich `black <>`__.
+Distro Packaging
+For Debian, we should try to use `wheel2deb <>`__.