diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c53802..3e4f12f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,7 +3,8 @@ v3.0.0 (in development) - Migrated from setuptools to hatch - Support using the `onbuild` step with Hatch - **Breaking**: The `build_dir` argument passed to `Versioningit.do_onbuild()` - and `onbuild` method callables has been changed to a `FileProvider` ABC + and `onbuild` method callables has been changed to an `OnbuildFileProvider` + ABC v2.3.0 (2023-11-19) ------------------- diff --git a/README.rst b/README.rst index 92d21f3..7805ec8 100644 --- a/README.rst +++ b/README.rst @@ -52,8 +52,8 @@ extraction & calculation. - Can optionally write the final version and other details to a file for loading at runtime -- Provides custom setuptools commands for inserting the final version and other - details into a source file at build time +- Provides custom hooks for inserting the final version and other details into + a source file at build time - The individual methods for VCS querying, tag-to-version calculation, version bumping, version formatting, and writing the version to a file can all be diff --git a/docs/changelog.rst b/docs/changelog.rst index 984df37..c5d44ae 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -9,7 +9,7 @@ v3.0.0 (in development) - Support using the ``onbuild`` step with Hatch - **Breaking**: The ``build_dir`` argument passed to `Versioningit.do_onbuild()` and ``onbuild`` method callables has been changed - to a `FileProvider` ABC + to an `OnbuildFileProvider` ABC v2.3.0 (2023-11-19) diff --git a/docs/configuration.rst b/docs/configuration.rst index a84b6da..73557c7 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -538,36 +538,30 @@ which takes the following parameters: .. _onbuild: -The ``[tool.versioningit.onbuild]`` Subtable --------------------------------------------- - -.. attention:: - - Currently, the ``onbuild`` step is not supported when using - ``versioningit`` with Hatch. See `issue #54`__ for more information. - - __ https://github.com/jwodder/versioningit/issues/54 +Enabling & Configuring the ``onbuild`` Step +------------------------------------------- .. versionadded:: 1.1.0 -.. versionadded:: 2.2.0 - - ``sdist`` and ``build_py`` classes added for use in :file:`setup.cfg` and - :file:`pyproject.toml` +``versioningit`` provides custom setuptools and Hatch hooks for enabling an +optional feature (called the "``onbuild`` step") in which your project's +version and/or other fields are inserted into a file in sdists & wheels while +leaving your local project directory alone. -The ``onbuild`` subtable configures an optional feature, inserting the project -version and/or other fields into built project trees when building an sdist or -wheel. Specifically, this feature allows you to create sdists & wheels in -which some file has been modified to contain the line ``__version__ = ""`` or similar while leaving your repository alone. +The steps for enabling the ``onbuild`` step differ depending on whether you're +using setuptools or Hatch as your build backend. The configuration options for +the step are the same between the backends, but where you put the configuration +and how you tell the backend to enable the hooks differs. -Enabling ``onbuild`` -~~~~~~~~~~~~~~~~~~~~ +Using ``onbuild`` with setuptools +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In order to use this feature, in addition to filling out the subtable, you must -configure setuptools to use ``versioningit``'s custom command classes. How to -do this depends on what file you've placed your project's setuptools -configuration in. +There are two steps to enabling the ``onbuild`` step with setuptools. First, +add a ``[tool.versioningit.onbuild]`` table to your :file:`pyproject.toml` +containing your desired configuration for the step (`see below +`_). Secondly, you need to tell setuptools to use +``versioningit``'s custom command classes. How to do this depends on what file +you've placed your project's setuptools configuration in. - If you're configuring setuptools via :file:`setup.cfg`, you can simply add the following field to its ``[options]`` table: @@ -611,8 +605,40 @@ may have to manually modify or subclass your command classes and add a call to `run_onbuild()` at the appropriate location; see the function's documentation for more information, but you'll largely be on your own at this point. -Configuring ``onbuild`` -~~~~~~~~~~~~~~~~~~~~~~~ +.. versionadded:: 2.2.0 + + ``sdist`` and ``build_py`` classes added for use in :file:`setup.cfg` and + :file:`pyproject.toml` + +Using ``onbuild`` with Hatch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to enable & configure the ``onbuild`` step when using ``versioningit`` +with Hatch, simply place all of your desired configuration for the step under a +``[tool.hatch.build.hooks.versioningit-onbuild]`` table. Do not use the +``[tool.versioningit.onbuild]`` table with Hatch; it will be ignored, and its +presence will generate a warning. + +.. note:: + + The ``versioningit-onbuild`` build hook is only usable when also using + ``versioningit`` as a Hatch version source. Trying to use the build hook + with a different version source will result in an error. + +.. note:: + + The ``versioningit-onbuild`` build hook is only supported when building an + sdist or wheel. Using other Hatch builders (such as `the application + builder`__) with ``versioningit-onbuild`` is not supported or endorsed in + any way. + + __ https://hatch.pypa.io/latest/plugins/builder/app/ + + +.. _onbuild_opts: + +``onbuild`` Configuration Options +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ``versioningit`` provides one ``onbuild`` method, ``"replace-version"`` (the default). It scans a given file for a line matching a given regex and inserts diff --git a/docs/hatch.rst b/docs/hatch.rst index 63665f1..dde3dd4 100644 --- a/docs/hatch.rst +++ b/docs/hatch.rst @@ -37,12 +37,12 @@ way as for setuptools: [tool.hatch.version] source = "versioningit" -- Configure ``versioningit`` as normal. However, with Hatch, you have two - possible locations to put ``versioningit``'s configuration in: either a - ``[tool.versioningit]`` table as used with setuptools or under the - ``[tool.hatch.version]`` table. Moreover, unlike when using setuptools, you - don't even need the ``[tool.versioningit]`` table if it's just going to be - empty. +- Configure ``versioningit`` as normal (mostly; see the note about ``onbuild`` + below). However, with Hatch, you have two possible locations to put + ``versioningit``'s configuration in: either the ``[tool.versioningit]`` table + as used with setuptools or under the ``[tool.hatch.version]`` table. + Moreover, unlike when using setuptools, you don't even need the + ``[tool.versioningit]`` table if it's just going to be empty. For example, the following configurations are equivalent: @@ -91,12 +91,11 @@ way as for setuptools: # `write` step: artifacts = ["src/mypackage/_version.py"] -.. attention:: - - Currently, :ref:`the onbuild step ` is not supported when using - ``versioningit`` with Hatch. See `issue #54`__ for more information. - - __ https://github.com/jwodder/versioningit/issues/54 +- The configuration for the ``onbuild`` step is placed in the + ``[tool.hatch.build.hooks.versioningit-onbuild]`` table (not in + ``[tool.versioningit.onbuild]`` or ``[tool.hatch.version.onbuild]``). In + addition, filling out this table is all you need to do to enable the + ``onbuild`` step — no fiddling with command classes necessary! .. note:: diff --git a/docs/how.rst b/docs/how.rst index 7fc7eea..08b3f1d 100644 --- a/docs/how.rst +++ b/docs/how.rst @@ -57,8 +57,8 @@ creates a file at a specified path containing the project's version. ``onbuild`` Step ^^^^^^^^^^^^^^^^ -When a project is built that uses ``versioningit``'s custom setuptools -commands, the ``onbuild`` step becomes added to the build process. The default -``onbuild`` method updates one of the files in the built distribution to -contain the project version while leaving the source files in the actual -project alone. See ":ref:`onbuild`" for more information. +When a project is built that uses ``versioningit``'s custom setuptools commands +or Hatch build hook, the ``onbuild`` step becomes added to the build process. +The default ``onbuild`` method updates one of the files in the built +distribution to contain the project version while leaving the source files in +the actual project alone. See ":ref:`onbuild`" for more information. diff --git a/docs/index.rst b/docs/index.rst index dda04a1..b4b4626 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -46,8 +46,8 @@ extraction & calculation. - Can optionally write the final version and other details to a file for loading at runtime -- Provides custom setuptools commands for inserting the final version and other - details into a source file at build time +- Provides custom hooks for inserting the final version and other details into + a source file at build time - The individual methods for VCS querying, tag-to-version calculation, version bumping, version formatting, and writing the version to a file can all be diff --git a/docs/runtime-version.rst b/docs/runtime-version.rst index 73877e8..29a1114 100644 --- a/docs/runtime-version.rst +++ b/docs/runtime-version.rst @@ -5,8 +5,8 @@ Automatically setting your project's version is all well and good, but you usually also want to expose that version at runtime, usually via a ``__version__`` variable. There are three options for doing this: -1. Use the `~importlib.metadata.version()` function in `importlib.metadata` to - get your package's version, like so: +1. Use the `~importlib.metadata.version()` function from `importlib.metadata` + to get your package's version, like so: .. code:: python @@ -68,12 +68,10 @@ usually also want to expose that version at runtime, usually via a from pathlib import Path __version__ = Path(__file__).with_name("VERSION").read_text().strip() -3. *(New in version 1.1.0)* Fill out the ``[tool.versioningit.onbuild]`` - subtable in :file:`pyproject.toml` and configure setuptools to use - ``versioningit``'s custom build commands. This will allow you to create - sdists & wheels in which some file has been modified to contain the line - ``__version__ = ""`` or similar while leaving your - repository alone. See ":ref:`onbuild`" for more information. +3. *(New in version 1.1.0)* Use the :ref:`onbuild step ` and its + custom hooks to create sdists & wheels in which some file has been modified + to contain the line ``__version__ = ""`` or similar while + leaving your repository's contents alone. .. tip:: @@ -90,9 +88,7 @@ usually also want to expose that version at runtime, usually via a Should affected file be under version control? **No** **Yes** Affected file must already exist? **No** **Yes** Modifies working tree? [#f1]_ **Yes** **No** - Requires configuration in ``setup.{py,cfg}``? **No** **Yes** Run when installing in editable mode? **Yes** **No** - Usable with Hatch? **Yes** **No** ============================================== ========= =========== .. [#f1] That is, the ``write`` method causes a file to be present (though diff --git a/docs/writing-methods.rst b/docs/writing-methods.rst index 285b9ed..951b152 100644 --- a/docs/writing-methods.rst +++ b/docs/writing-methods.rst @@ -168,13 +168,13 @@ A custom ``write`` method is a callable with the following synopsis: A custom ``onbuild`` method is a callable with the following synopsis: -.. function:: funcname(*, build_dir: str | pathlib.Path, is_source: bool, template_fields: dict[str, Any], params: dict[str, Any]) -> None +.. function:: funcname(*, file_provider: OnbuildFileProvider, is_source: bool, template_fields: dict[str, Any], params: dict[str, Any]) -> None :noindex: - Modifies one or more files in ``build_dir`` + Modifies the files about to be included in an sdist or wheel - :param path build_dir: - the path to the directory where the project is being built + :param file_provider: + an object for accessing files being built into an sdist or wheel :param bool is_source: true if an sdist or other artifact that preserves source paths is being built, false if a wheel or other artifact that uses installation paths @@ -187,6 +187,17 @@ A custom ``onbuild`` method is a callable with the following synopsis: ``version`` argument replaced with ``template_fields`` +.. versionchanged:: 3.0.0 + + ``build_dir`` argument replaced with ``file_provider`` + +``onbuild`` methods are provided with instances of the following abstract base +classes for operating on: + +.. autoclass:: versioningit.OnbuildFileProvider + +.. autoclass:: versioningit.OnbuildFile + Distributing Your Methods in an Extension Package ------------------------------------------------- diff --git a/src/versioningit/__init__.py b/src/versioningit/__init__.py index efba498..7c9af19 100644 --- a/src/versioningit/__init__.py +++ b/src/versioningit/__init__.py @@ -23,8 +23,8 @@ - Can optionally write the final version to a file for loading at runtime -- Provides custom setuptools commands for inserting the final version into a - source file at build time +- Provides custom hooks for inserting the final version into a source file at + build time - The individual methods for VCS querying, tag-to-version calculation, version bumping, version formatting, and writing the version to a file can all be diff --git a/src/versioningit/core.py b/src/versioningit/core.py index fac733b..3ba39ec 100644 --- a/src/versioningit/core.py +++ b/src/versioningit/core.py @@ -562,12 +562,12 @@ def run_onbuild( """ .. versionadded:: 1.1.0 - Run the ``onbuild`` step for the given project. + Run the ``onbuild`` step for the given setuptools project. - This function is intended to be used by custom setuptools commands that are - used in place of ``versioningit``'s custom commands but still need to be - able to run the ``onbuild`` step. The ``template_fields`` value can be - obtained by passing the command's ``distribution`` attribute to + This function is intended to be used by custom setuptools command classes + that are used in place of ``versioningit``'s command classes but still need + to be able to run the ``onbuild`` step. The ``template_fields`` value can + be obtained by passing a command class's ``distribution`` attribute to `get_template_fields_from_distribution()`; if this returns `None`, then we are building from an sdist, and `run_onbuild()` should not be called. diff --git a/src/versioningit/onbuild.py b/src/versioningit/onbuild.py index cb9a870..58a5828 100644 --- a/src/versioningit/onbuild.py +++ b/src/versioningit/onbuild.py @@ -21,6 +21,8 @@ class OnbuildFileProvider(ABC): """ + .. versionadded:: 3.0.0 + An abstract base class for accessing files that are about to be included in an sdist or wheel currently being built """ @@ -48,6 +50,8 @@ def get_file( class OnbuildFile(ABC): """ + .. versionadded:: 3.0.0 + An abstract base class for opening a file in a project currently being built """ @@ -93,6 +97,8 @@ def open( @dataclass class SetuptoolsFileProvider(OnbuildFileProvider): """ + .. versionadded:: 3.0.0 + `OnbuildFileProvider` implementation for use when building sdists or wheels under setuptools. @@ -179,6 +185,8 @@ def open( @dataclass class HatchFileProvider(OnbuildFileProvider): """ + .. versionadded:: 3.0.0 + `OnbuildFileProvider` implementation for use when building sdists or wheels under Hatch.