PYPI.ECLASS

Section: eclass-manpages (5)
Updated: Sep 2025
Index Return to Main Contents

NAME

pypi.eclass - A helper eclass to generate PyPI source URIs

DESCRIPTION

The pypi.eclass can be used to easily obtain URLs for artifacts uploaded to PyPI.org. When inherited, the eclass defaults SRC_URI and S to fetch .tar.gz sdist. The eclass defaults to using ${PN} as PyPI project name; PYPI_PN can be set prior to inheriting it to override that. The source distribution filename is assumed to be normalized by default; PYPI_NO_NORMALIZE can be set prior to inherit to override that. The version is translated using pypi_translate_version.

If PYPI_VERIFY_REPO is set to a non-empty value, verify-provenance flag is added along with necessary BDEPEND. The provenance file for the default source distribution is added to SRC_URI, and a default src_unpack() is exported to verify its provenance.

If necessary, SRC_URI and S can be overridden by the ebuild. Three helper functions, pypi_sdist_url, pypi_wheel_url and pypi_provenance_url are provided to generate URLs to artifacts of specified type, with customizable URL components. Additionally, pypi_wheel_name can be used to generate the wheel filename.

pypi_normalize_name can be used to normalize an arbitrary project name according to sdist/wheel normalization rules. pypi_translate_version can be used to translate a Gentoo version string into its PEP 440 equivalent.

pypi_verify_provenance can be used to verify the provenance directly.

SUPPORTED EAPIS

7 8

EXAMPLE

inherit pypi

SRC_URI="$(pypi_sdist_url "${PN^}" "${PV}")"
S=${WORKDIR}/${P^}

FUNCTIONS

pypi_normalize_name <name>

Normalize the project name according to sdist/wheel normalization rules. That is, convert to lowercase and replace runs of [._-] with a single underscore.

Based on the spec, as of 2023-02-10: https://packaging.python.org/en/latest/specifications/#package-distribution-file-formats

_pypi_translate_version <version>

Internal version translation function, returns the result via _PYPI_TRANSLATED_VERSION variable.

pypi_translate_version <version>

Translate the specified Gentoo version into the usual Python counterpart. Assumes PEP 440 versions.

Note that we do not have clear counterparts for the epoch segment, nor for development release segment.

pypi_sdist_url [--no-normalize] [<project> [<version> [<suffix>]]]

Output the URL to PyPI sdist for specified project/version tuple.

The `--no-normalize` option disables project name normalization for sdist filename. This may be necessary when dealing with distfiles generated using build systems that did not follow PEP 625 (i.e. the sdist name contains uppercase letters, hyphens or dots).

If <project> is unspecified, it defaults to ${PYPI_PN}. The package name is normalized according to the specification unless `--no-normalize` is passed.

If <version> is unspecified, it defaults to ${PV} translated via pypi_translate_version. If it is specified, then it is used verbatim (the function can be called explicitly to translate custom version number).

If <format> is unspecified, it defaults to ".tar.gz". Another valid value is ".zip" (please remember to add a BDEPEND on app-arch/unzip).

pypi_wheel_name [<project> [<version> [<python-tag> [<abi-platform-tag>]]]]

Output the wheel filename for the specified project/version tuple.

If <project> is unspecified, it defaults to ${PYPI_PN}. The package name is normalized according to the wheel specification.

If <python-tag> is unspecified, it defaults to "py3". It can also be "py2.py3", or a specific version in case of non-pure wheels.

If <abi-platform-tag> is unspecified, it defaults to "none-any". You need to specify the correct value for non-pure wheels, e.g. "abi3-linux_x86_64".

pypi_wheel_url [--unpack] [<project> [<version> [<python-tag> [<abi-platform-tag>]]]]

Output the URL to PyPI wheel for specified project/version tuple.

The `--unpack` option causes a SRC_URI with an arrow operator to be generated, that adds a .zip suffix to the fetched distfile, so that it is unpacked in default src_unpack(). Note that the wheel contents will be unpacked straight into ${WORKDIR}. You need to add a BDEPEND on app-arch/unzip.

If <project> is unspecified, it defaults to ${PYPI_PN}.

If <python-tag> is unspecified, it defaults to "py3". It can also be "py2.py3", or a specific version in case of non-pure wheels.

If <abi-platform-tag> is unspecified, it defaults to "none-any". You need to specify the correct value for non-pure wheels, e.g. "abi3-linux_x86_64".

pypi_provenance_url <dist> [<project> [<version>]]

Output the URL to PyPI provenance for the specified artifact.

pypi_verify_provenance <dist> <provenance> [<repo>]

Verify the specified artifact's provenance. <dist> is the path to the artifact to verify, while <provenance> is the provenance file.

The function defaults to using PYPI_VERIFY_REPO as the expected repository URL. This can be overridden by specfying <repo>.

The function dies on verification failure.

pypi_src_unpack

A src_unpack implementation that verifies provenances. Exported only with PYPI_VERIFY_REPO.

ECLASS VARIABLES

PYPI_NO_NORMALIZE (SET BEFORE INHERIT)

When set to a non-empty value, disables project name normalization for the default SRC_URI and S values.

PYPI_PN ?= ${PN} (SET BEFORE INHERIT)

The PyPI project name. This should be overridden scarcely, generally when upstream project name does not conform to Gentoo naming rules, e.g. when it contains dots or uppercase letters.

Example use:

PYPI_PN=${PN/-/.}

PYPI_VERIFY_REPO (SET BEFORE INHERIT)

The repository to verify provenance against. If set to a non-empty value, the eclass will add a "verify-provenance" flag that can be used to download the provenance for the distribution, and verify it against the provenance and the specified repository.

AUTHORS

Michał Górny <mgorny@gentoo.org>

MAINTAINERS

Michał Górny <mgorny@gentoo.org>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

pypi.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:01 GMT, September 18, 2025