summaryrefslogtreecommitdiff
path: root/python-guidelines.rst
diff options
context:
space:
mode:
authorFlorian Dold <florian@dold.me>2020-11-09 17:39:08 +0100
committerFlorian Dold <florian@dold.me>2020-11-09 17:42:11 +0100
commit1a0b90a645752152da6ffd1fe8279acdcb26a01e (patch)
treec6b654263127e3498e90a5418f5a6509a72fc88f /python-guidelines.rst
parent32e8e736f6707761ace157f515a55063a8814b07 (diff)
downloaddocs-1a0b90a645752152da6ffd1fe8279acdcb26a01e.tar.gz
docs-1a0b90a645752152da6ffd1fe8279acdcb26a01e.tar.bz2
docs-1a0b90a645752152da6ffd1fe8279acdcb26a01e.zip
python guidelines
Diffstat (limited to 'python-guidelines.rst')
-rw-r--r--python-guidelines.rst56
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.
+
+
+Packaging
+---------
+
+* We use `poetry <https://github.com/python-poetry/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 <https://git.taler.net/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 <https://git.taler.net/build-common.git/tree/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/configure.py``.
+ 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.
+* The source distribution (``make dist``) should either be created via ``poetry build -f sdist``
+ or using the `git-archive-all <https://git.taler.net/build-common.git/tree/archive-with-submodules/git_archive_all.py>`__.
+
+Formatting
+----------
+
+* We follow `pep8 <https://www.python.org/dev/peps/pep-0008/>`__.
+* Code should be auto-formatted wich `black <https://github.com/psf/black>`__.
+
+
+Distro Packaging
+----------------
+
+For Debian, we should try to use `wheel2deb <https://github.com/upciti/wheel2deb>`__.