pyproject_patcher.patcher
=========================

.. py:module:: pyproject_patcher.patcher

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   pyproject_patcher.patcher.logger


Classes
-------

.. autoapisummary::

   pyproject_patcher.patcher.PyprojectPatcher


Functions
---------

.. autoapisummary::

   pyproject_patcher.patcher.patch_in_place


Module Contents
---------------

.. py:data:: logger

.. py:class:: 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


   .. py:attribute:: document
      :type:  tomlkit.TOMLDocument


   .. py:property:: build_system
      :type: collections.abc.MutableMapping[str, str | tomlkit.items.Item]


      Low-level access to the `build-system` section of
      `pyproject.toml`.



   .. py:property:: build_system_requires
      :type: pyproject_patcher.requirements.RequirementsSection


      High-level access to the `requires` subsection of the `build-system`
      section.



   .. py:property:: dynamic
      :type: collections.abc.MutableSequence[str]


      Low-level access to the `project.dynamic` subsection of
      the `build-system` section.



   .. py:property:: project
      :type: collections.abc.MutableMapping[str, str | tomlkit.items.Item]


      Low-level access to the `project` section of `pyproject.toml`.



   .. py:property:: tool
      :type: collections.abc.MutableMapping[str, str | tomlkit.items.Item]


      Low-level access to the `tool` section of `pyproject.toml`.



   .. py:method:: tools()

      High-level convenience methods for manipulating tool
      settings, e.g. settings for the `setuptools_git_versioning`
      tool.



   .. py:method:: set_project_version(version)

      Sets `project.version` to the given value.

      :param version:
          The version to set.



   .. py:method:: set_project_version_from_env(key)

      Sets `project.version` from the given environment variable.

      :param key:
          The name of the environment variable to whose value the
          `project.version` property is to be set.



   .. py:method:: remove_build_system_dependency(module_name)

      Removes a Python module dependency from `build-system.requires`.



   .. py:method:: strip_build_system_dependency_constraint(module_name)

      Modifies an entry in `build-system.requires` to strip its
      version constraint.



   .. py:method:: 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.



.. py:function:: patch_in_place(path)

   Patches a given `pyproject.toml` file in place.