pyproject_patcher.patcher
This module parses a pyproject.toml file, hard codes a given version number into its project.version, and disables all invocations of dynamic version generators (or removes those invocations from the model altogether.)
This is useful for system packages, which are typically built from source tarballs, where Git tags or commits aren’t available.
Attributes
Classes
This class accepts a pyproject.toml model, allows to inject |
Functions
|
Patches a given pyproject.toml file in place. |
Module Contents
- pyproject_patcher.patcher.logger
- class pyproject_patcher.patcher.PyprojectPatcher
This class accepts a pyproject.toml model, allows to inject a static version number as its project.version, disables all invocations of dynamic version generators, and removes those invocations and references from the model altogether.
Some upstream projects use setuptools add-ons that allow their build pipeline to dynamically obtain the package version number from Git tags or commits. That’s a good thing in principle, because it helps the project to have a single point of truth for the version number. Typical add-ons are setuptools-scm and setuptools-git-versioning.
For that to work, these add-ons generally expect a Git repository to be present so they can dynamically obtain the version number. However, a system package is typically built from a source tarball, which usually includes no Git tags and commits.
To facilitate the needs of system-level package maintainers, setuptools-scm supports a SETUPTOOLS_SCM_PRETEND_VERSION environment variable, and uses its value as the version number if set. The setuptools-git-versioning plugin, however, doesn’t offer such an environment variable. Instead, it supports reading a version number from a file [1]. In contrast to SETUPTOOLS_SCM_PRETEND_VERSION, the version file requires a version_file property to be added to pyproject.toml. Upstream projects usually don’t do that, so a system package maintainer would need to patch that into pyproject.toml.
Instead of adding a version_file configuration property, this class removes all references to setuptools-git-versioning from pyproject.toml. This technique has the same effect as adding version_file but is slightly easier to use, and also guards against failing dependency checks caused by e.g. <2 version constraints in the build-system.requires field.
[1]: https://setuptools-git-versioning.readthedocs.io/en/stable/schemas/file/index.html
- document: tomlkit.TOMLDocument
- property build_system: collections.abc.MutableMapping[str, str | tomlkit.items.Item]
Low-level access to the build-system section of pyproject.toml.
- Return type:
collections.abc.MutableMapping[str, str | tomlkit.items.Item]
- property build_system_requires: pyproject_patcher.requirements.RequirementsSection
High-level access to the requires subsection of the build-system section.
- Return type:
- property dynamic: collections.abc.MutableSequence[str]
Low-level access to the project.dynamic subsection of the build-system section.
- Return type:
collections.abc.MutableSequence[str]
- property project: collections.abc.MutableMapping[str, str | tomlkit.items.Item]
Low-level access to the project section of pyproject.toml.
- Return type:
collections.abc.MutableMapping[str, str | tomlkit.items.Item]
- property tool: collections.abc.MutableMapping[str, str | tomlkit.items.Item]
Low-level access to the tool section of pyproject.toml.
- Return type:
collections.abc.MutableMapping[str, str | tomlkit.items.Item]
- tools()
High-level convenience methods for manipulating tool settings, e.g. settings for the setuptools_git_versioning tool.
- Return type:
- set_project_version(version)
Sets project.version to the given value.
- Parameters:
version (str) – The version to set.
- Return type:
None
- set_project_version_from_env(key)
Sets project.version from the given environment variable.
- Parameters:
key (str) – The name of the environment variable to whose value the project.version property is to be set.
- Return type:
None
- remove_build_system_dependency(module_name)
Removes a Python module dependency from build-system.requires.
- Parameters:
module_name (str)
- Return type:
None
- strip_build_system_dependency_constraint(module_name)
Modifies an entry in build-system.requires to strip its version constraint.
- Parameters:
module_name (str)
- Return type:
None
- remove_setuptools_git_versioning_section()
Removes the tool section for the setuptools-git-versioning Python model so it no longer attempts to set project.version dynamically. Additionally removes its import declaration from build-system so that the module doesn’t even have to be installed.
- Return type:
None
- pyproject_patcher.patcher.patch_in_place(path)
Patches a given pyproject.toml file in place.
- Parameters:
path (str | os.PathLike[Any])
- Return type:
collections.abc.Iterator[PyprojectPatcher]