Add importable setuptools command classes for use in setup.cfg

CHANGELOG.md

@@ -1,3 +1,9 @@
+v2.2.0 (in development)
+-----------------------
+- The custom setuptools command classes can now be imported directly from the
+  `versioningit.cmdclass` module as an alternative to calling
+  `get_cmdclasses()`
+
 v2.1.0 (2022-10-25)
 -------------------
 - Drop support for Python 3.6

docs/api.rst

@@ -10,6 +10,45 @@ High-Level Functions
 .. autofunction:: get_next_version
 .. autofunction:: get_cmdclasses
 
+.. class:: versioningit.cmdclass.sdist
+
+    .. versionadded:: 2.2.0
+
+    A custom subclass of `setuptools.command.sdist.sdist` that runs the
+    ``onbuild`` step when building an sdist.  This class is equivalent to
+    ``get_cmdclasses()["sdist"]``, except that it can also be used in the
+    ``[options]cmdclass`` field in :file:`setup.cfg`.
+
+.. class:: versioningit.cmdclass.build_py
+
+    .. versionadded:: 2.2.0
+
+    A custom subclass of `setuptools.command.build_py.build_py` that runs the
+    ``onbuild`` step when building a wheel.  This class is equivalent to
+    ``get_cmdclasses()["build_py"]``, except that it can also be used in the
+    ``[options]cmdclass`` field in :file:`setup.cfg`.
+
+.. note::
+
+    When importing or referring to the ``sdist`` and ``build_py`` command
+    classes, the ``.cmdclass`` submodule needs to be specified; unlike the rest
+    of the library API, they are not importable directly from ``versioningit``.
+
+    .. code:: ini
+
+        [options]
+        cmdclass =
+            # Right!
+            sdist = versioningit.cmdclass.sdist
+            build_py = versioningit.cmdclass.build_py
+
+        [options]
+        cmdclass =
+            # Wrong!
+            sdist = versioningit.sdist
+            build_py = versioningit.build_py
+
+
 Low-Level Class
 ---------------
 

docs/changelog.rst

@@ -3,6 +3,13 @@
 Changelog
 =========
 
+v2.2.0 (in development)
+-----------------------
+- The custom setuptools command classes can now be imported directly from the
+  ``versioningit.cmdclass`` module as an alternative to calling
+  `get_cmdclasses()`
+
+
 v2.1.0 (2022-10-25)
 -------------------
 - Drop support for Python 3.6

docs/configuration.rst

@@ -542,7 +542,7 @@ which some file has been modified to contain the line ``__version__ = "<project
 version>"`` or similar while leaving your repository alone.
 
 In order to use this feature, in addition to filling out the subtable, your
-project must include a ``setup.py`` file that passes
+project must include a :file:`setup.py` file that passes
 `versioningit.get_cmdclasses()` as the ``cmdclass`` argument to `setup()`,
 e.g.:
 
@@ -556,6 +556,20 @@ e.g.:
         # Other arguments go here
     )
 
+If you don't need to further customize the build process, this configuration
+can be specified via :file:`setup.cfg` instead, like so:
+
+.. code:: ini
+
+    [options]
+    cmdclass =
+        sdist = versioningit.cmdclass.sdist
+        build_py = versioningit.cmdclass.build_py
+
+.. versionadded:: 2.2.0
+
+    ``sdist`` and ``build_py`` classes added for use in :file:`setup.cfg`
+
 ``versioningit`` provides one ``onbuild`` method, ``"replace-version"`` (the
 default).  It scans a given file for a line matching a given regex and inserts
 the project version (or other templated string) into the first line that

docs/runtime-version.rst

@@ -67,11 +67,12 @@ usually also want to expose that version at runtime, usually via a
        __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 your :file:`setup.py` to
-   use ``versioningit``'s custom setuptools commands.  This will allow you to
-   create sdists & wheels in which some file has been modified to contain the
-   line ``__version__ = "<project version>"`` or similar while leaving your
-   repository alone.  See ":ref:`onbuild`" for more information.
+   subtable in :file:`pyproject.toml` and configure your :file:`setup.py` or
+   :file:`setup.cfg` to use ``versioningit``'s custom setuptools commands.
+   This will allow you to create sdists & wheels in which some file has been
+   modified to contain the line ``__version__ = "<project version>"`` or
+   similar while leaving your repository alone.  See ":ref:`onbuild`" for more
+   information.
 
 .. tip::
 

src/versioningit/__init__.py

@@ -38,13 +38,12 @@
 <https://versioningit.rtfd.io> for more information.
 """
 
-__version__ = "2.1.0"
+__version__ = "2.2.0.dev1"
 __author__ = "John Thorvald Wodder II"
 __author_email__ = "[email protected]"
 __license__ = "MIT"
 __url__ = "https://github.com/jwodder/versioningit"
 
-from .cmdclasses import get_cmdclasses
 from .core import (
     FallbackReport,
     Report,
@@ -67,6 +66,7 @@
     NotVCSError,
     NotVersioningitError,
 )
+from .get_cmdclasses import get_cmdclasses
 
 __all__ = [
     "ConfigError",

src/versioningit/cmdclass.py

@@ -0,0 +1,9 @@
+# Note: The classes in this module are not to be re-exported by `__init__.py`,
+# as that would mean unconditionally importing setuptools whenever versioningit
+# is imported, slowing things down.
+
+from .get_cmdclasses import get_cmdclasses
+
+_cmdclasses = get_cmdclasses()
+sdist = _cmdclasses["sdist"]
+build_py = _cmdclasses["build_py"]

test/data/repos/git/onbuild-cfg.json

@@ -0,0 +1,12 @@
+{
+    "version": "0.1.0.post2+g5213162",
+    "next_version": "0.2.0",
+    "files": [
+        {
+            "sdist_path": "src/mypackage/__init__.py",
+            "wheel_path": "mypackage/__init__.py",
+            "in_project": false,
+            "contents": "\"\"\" A test package \"\"\"\n\n__version__ = \"0.1.0.post2+g5213162\"\n__author__ = \"John Thorvald Wodder II\"\n__author_email__ = \"[email protected]\"\n__license__ = \"MIT\"\n"
+        }
+    ]
+}