Python package policies

2020-03-07T08:12:15Z

Sascha: Add quotes around builddir value in Python3 package template

Python packages in Alpine Linux should follow a general set of standards for their APKBUILDs.

{{Draft|Pending consensus on this approach, some discussion is taking place on the [[Talk:Python_package_policies|talk page]]}}

== Guidelines ==

* Prefix Python 3 libraries with py3-. Do not prefix programs (distinct from libraries) at all.

== General Template ==

Be sure to make the following changes:

* Update maintainer to yourself
* Set the pkgname to the Alpine package name (prefixed with "py-")
* Set _pyname to the name of the package on PyPI
* Update the version number, pkgdesc, url, and license
* Build it and address any issues that come up
* Read the build output and be vigilant for issues listed in the following sections - the build may complete successfully even though these issues are present

=== Package template ===

Note that if you are removing python2 support from a package which previously had it, you should add <pre>replaces="py2-example"</pre> as well. If the old package was a split package, also add <pre>replaces="py-example"
provides="py-example=$pkgver-r$pkgrel"</pre>.

<pre># Maintainer: Joe Bloe <joe@example.org>
pkgname=py3-alpine-name
_pyname=pypi-name
pkgver=1.2.3
pkgrel=0
pkgdesc="Example Python package"
url="https://example.org"
arch="noarch"
license="MIT"
depends="python3"
makedepends="py3-setuptools"
_pypiprefix="${_pyname%${_pyname#?}}"
source="https://files.pythonhosted.org/packages/source/$_pypiprefix/$_pyname/$_pyname-$pkgver.tar.gz"
builddir="$srcdir/$_pyname-$pkgver"

build() {
python3 setup.py build
}

check() {
python3 setup.py test
}

package() {
python3 setup.py install --prefix=/usr --root="$pkgdir"
}</pre>

== Common issues ==

=== No source package available (only the wheel is on PyPI) ===

Seek out the upstream source (e.g. GitHub) and swap out the URL.

=== No tests in PyPI package "(0 tests run)" ===

Seek out the upstream source (e.g. GitHub) and swap out the URL.

=== setup.py test downloads a lot of dependencies ===

Watch out for this and be sure to add any of these packages to checkdepends so that setuptools isn't downloading and testing against packages/versions which aren't in aports.

=== You need to use the 'tox' utility to run tests ===

tox (knows as py3-tox on Alpine Linux) downloads all dependencies into a virtual environment by default, which bypasses the system tooling, making
testing somewhat less useful.

Remember to use *--sitepackages* on your invocation of tox in the check() phase so it uses the system packages instead of downloading ones into
a virtual environment.

== Alpine+Python projects ==

=== aports normalization project ===

Many Python packages in aports (if not most) do not follow these guidelines.

TODO: obtain consensus and organize this work.

=== Python 2 deprecation ===

{{Draft|Pending consensus on this approach}}

The general approach to Python 2 deprecation and removal requires three broad steps:

# Do not add new python 2 packages to aports, effective immediately.
# In the course of the aports normalization project, drop Python 2 support if it's easy or triage it and make a note for later if not.
# Making judgement calls for difficult packages on a case-by-case basis, based on the upstream's progress/amicability towards a Python 3 port. Upstreams which are unwilling to port to Python 3 should be removed from aports.

TODO: Prepare some discussion place, git repos, scripts, etc, to organize this work.

[[category: python]]

Alpine Linux - User contributions [en]

Python package policies