Documentation for pyproject-patcher

Usage

Description

This Python package is an attempt to make it a little easier to patch pyproject.toml in place.

It is mainly useful for maintainers of system packages.
If you’re not a maintainer of system packages, or if you don’t know what that means, then pyproject-patcher is probably not for you.

Examples

Recommended import statement

The following examples all assume the following import statement:

from pyproject_patcher import patch_in_place

Set a static project version

with patch_in_place('pyproject.toml') as toml:
    toml.set_project_version('1.2.3')

Strip the version constraint of a dependency

with patch_in_place('pyproject.toml') as toml:
    toml.strip_build_system_dependency_constraint('setuptools-git-versioning')
    # or, equivalently:
    # toml.build_system_requires.strip_constraint('setuptools-git-versioning')

Remove an entry from a dependency list

with patch_in_place('pyproject.toml') as toml:
    toml.remove_build_system_dependency('setuptools-git-versioning')
    # or, equivalently:
    # toml.build_system_requires.remove_dependency('setuptools-git-versioning')

Remove `setuptools-git-versioning` from `pyproject.toml` entirely

with patch_in_place('pyproject.toml') as toml:
    toml.set_project_version('1.2.3')
    toml.tools.setuptools_git_versioning.remove()

Configure a version template without a `.dirty` suffix

with patch_in_place('pyproject.toml') as toml:
    toml.tools.setuptools_git_versioning.template_ignore_dirty_git()

Environment

pyproject-patcher supports the following environment variable:

PYPROJECT_PATCHER_DEBUG: If set to a non-zero value, causes pyproject-patcher to enable debug-level; logging.

API Reference

This page contains auto-generated API reference documentation [1].

pyproject_patcher

Usage example:

from pyproject_patcher import patch_in_place

with patch_in_place('pyproject.toml') as toml:
    toml.set_project_version('1.2.3')

Submodules

pyproject_patcher.logging

Customized logging.

Functions

get_logger(name)

Instantiate a custom logger.

Module Contents

pyproject_patcher.logging.get_logger(name)

Instantiate a custom logger.

Parameters:: name (str)
Return type:: logging.Logger

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

logger

Classes

PyprojectPatcher

This class accepts a pyproject.toml model, allows to inject

Functions

patch_in_place(path)

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:: pyproject_patcher.requirements.RequirementsSection

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:: pyproject_patcher.tools.Tools

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]

pyproject_patcher.requirements

Manage requirements expressions, with or without version constraints.

Classes

RequirementsSection

A list of requirements expressions.

Module Contents

class pyproject_patcher.requirements.RequirementsSection(array)

A list of requirements expressions.

For example:

`py ["setuptools", "wheel", "setuptools-git-versioning<2"] `

Parameters:: array (tomlkit.items.Array)

array: tomlkit.items.Array

remove_dependency(module_name)

Removes a Python module dependency from this section.

Parameters:: module_name (str) – The name of a module that is declared in this section.
Return type:: None

strip_constraint(module_name)

For a Python module dependency in this section, remove its version constraint.

Parameters:: module_name (str) – The name of a module that is declared in this section.
Return type:: None

pyproject_patcher.tools

Tools (as in the tool section of a pyproject.toml file).

Submodules

pyproject_patcher.tools.setuptools_git_versioning

Manage the setuptools_git_versioning tool in a pyproject.toml.

Attributes

TOOL_NAME

Classes

SetuptoolsGitVersioning

This class wraps a pyproject.toml model and provides

Module Contents

pyproject_patcher.tools.setuptools_git_versioning.TOOL_NAME = 'setuptools-git-versioning'

class pyproject_patcher.tools.setuptools_git_versioning.SetuptoolsGitVersioning

This class wraps a pyproject.toml model and provides methods to interact with the tools.setuptools_git_versioning part and other entries related to it.

patcher: pyproject_patcher.patcher.PyprojectPatcher

remove()

Removes all references to setuptools-git-versioning from this model. This includes removal of the dynamic = [“version”] entry and the entry in the build-system.requires section that requires the setuptools-git-versioning module.

Return type:: None

template_ignore_dirty_git()

Changes dirty_template so that it no longer contains a .dirty suffix.

Useful for building system packages based on a VCS revision checked out with Git in cases where pyproject.toml has been modified before setuptools_git_versioning is run. In that case, having a .dirty suffix would be misleading.

Return type:: None

Classes

`SetuptoolsGitVersioning`	This class wraps a pyproject.toml model and provides
`Tools`	Accessor for tools, such as setuptools_git_versioning.

Package Contents

class pyproject_patcher.tools.SetuptoolsGitVersioning

This class wraps a pyproject.toml model and provides methods to interact with the tools.setuptools_git_versioning part and other entries related to it.

patcher: pyproject_patcher.patcher.PyprojectPatcher

remove()

Removes all references to setuptools-git-versioning from this model. This includes removal of the dynamic = [“version”] entry and the entry in the build-system.requires section that requires the setuptools-git-versioning module.

Return type:: None

template_ignore_dirty_git()

Changes dirty_template so that it no longer contains a .dirty suffix.

Useful for building system packages based on a VCS revision checked out with Git in cases where pyproject.toml has been modified before setuptools_git_versioning is run. In that case, having a .dirty suffix would be misleading.

Return type:: None

class pyproject_patcher.tools.Tools

Accessor for tools, such as setuptools_git_versioning.

patcher: pyproject_patcher.patcher.PyprojectPatcher

setuptools_git_versioning()

An object that provides methods to interact with the tools.setuptools_git_versioning part of pyproject.toml and other entries related to it.

Return type:: setuptools_git_versioning.SetuptoolsGitVersioning

pyproject_patcher.types

Classes

`MarkerExpression`	See also:
`RequirementsContainer`	See also:

Module Contents

class pyproject_patcher.types.MarkerExpression

Bases: TypedDict

op: str

lhs: MarkerExpression | str

rhs: MarkerExpression | str

class pyproject_patcher.types.RequirementsContainer

Bases: NamedTuple

name: str

extras: list[str] | None

constraints: list[tuple[str, str]] | None

marker: MarkerExpression | None

url: str | None

requirement: str

pyproject-patcher

This Python package is an attempt to make it a little easier to patch pyproject.toml in place.

It is mainly useful for maintainers of system packages.
If you’re not a maintainer of system packages, or if you don’t know what that means, then pyproject-patcher is probably not for you.

Features

Hard code a version number into project.version
Disable all invocations of the dynamic version generator setuptools-git-versioning
Remove dependency to setuptools-git-versioning from build-system.requires
Configure setuptools-git-versioning to use a version template without a .dirty suffix

Installation

Installing from PyPI

To install pyproject-patcher from PyPI, open a shell and run:

pip install pyproject-patcher

If that doesn’t work, try:

python3 -m pip install pyproject-patcher

Installing from the AUR

Direct your favorite AUR helper to the python-pyproject-patcher package.

Usage

See USAGE.md for details.

Contributing to pyproject-patcher

See CONTRIBUTING.md.

License

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. For a copy of the License, see LICENSE.

Documentation for pyproject-patcher

Usage

Description

Examples

Recommended import statement

Set a static project version

Strip the version constraint of a dependency

Remove an entry from a dependency list

Remove setuptools-git-versioning from pyproject.toml entirely

Configure a version template without a .dirty suffix

Environment

API Reference

pyproject_patcher

Submodules

pyproject_patcher.logging

Functions

Module Contents

pyproject_patcher.patcher

Attributes

Classes

Functions

Module Contents

pyproject_patcher.requirements

Classes

Module Contents

pyproject_patcher.tools

Submodules

pyproject_patcher.tools.setuptools_git_versioning

Attributes

Classes

Module Contents

Classes

Package Contents

pyproject_patcher.types

Classes

Module Contents

pyproject-patcher

Features

Installation

Installing from PyPI

Installing from the AUR

Usage

Contributing to pyproject-patcher

License

Remove `setuptools-git-versioning` from `pyproject.toml` entirely

Configure a version template without a `.dirty` suffix