Merge branch 'trunk' into trusted-publishing

README.rst

@@ -9,54 +9,73 @@ Incremental is a small library that versions your Python projects.
 
 API documentation can be found `here <https://twisted.org/incremental/docs/>`_.
 
+.. contents::
 
 Quick Start
 -----------
 
-In your ``pyproject.toml``, add Incremental to your build requirements:
+Using setuptools
+~~~~~~~~~~~~~~~~
+
+Add Incremental to your ``pyproject.toml``:
 
 .. code-block:: toml
 
     [build-system]
-    requires = ["setuptools", "incremental>=NEXT"]
+    requires = [
+        "setuptools",
+        "incremental>=NEXT",  # ← Add incremental as a build dependency
+    ]
     build-backend = "setuptools.build_meta"
 
-Specify the project's version as dynamic:
-
-.. code-block:: toml
-
     [project]
     name = "<projectname>"
-    dynamic = ["version"]
+    dynamic = ["version"]     # ← Mark the version dynamic
+    dependencies = [
+        "incremental>=NEXT",  # ← Depend on incremental at runtime
+    ]
+    # ...
 
-Remove any ``version`` line and any ``[tool.setuptools.dynamic] version =`` entry.
+    [tool.incremental]        # ← Activate Incremental's setuptools plugin
 
-Add this empty block to activate Incremental's setuptools plugin:
+It's fine if the ``[tool.incremental]`` table is empty, but it must be present.
 
-.. code-block:: toml
+Remove any ``[project] version =`` entry and any ``[tool.setuptools.dynamic] version =`` entry.
 
-    [tool.incremental]
+Next, `initialize the project`_.
 
-Install Incremental to your local environment with ``pip install incremental[scripts]``.
-Then run ``python -m incremental.update <projectname> --create``.
-It will create a file in your package named ``_version.py`` and look like this:
+Using Hatchling
+~~~~~~~~~~~~~~~
 
-.. code:: python
+If you're using `Hatchling <https://hatch.pypa.io/>`_ to package your project,
+activate Incremental's Hatchling plugin by altering your ``pyproject.toml``:
 
-   from incremental import Version
-
-   __version__ = Version("<projectname>", 24, 1, 0)
-   __all__ = ["__version__"]
+.. code:: toml
 
+    [build-system]
+    requires = [
+        "hatchling",
+        "incremental>=NEXT",  # ← Add incremental as a build dependency
+    ]
+    build-backend = "hatchling.build"
 
-Then, so users of your project can find your version, in your root package's ``__init__.py`` add:
+    [project]
+    name = "<projectname>"
+    dynamic = ["version"]     # ← Mark the version dynamic
+    dependencies = [
+        "incremental>=NEXT",  # ← Depend on incremental at runtime
+    ]
+    # ...
 
-.. code:: python
+    [tool.hatch.version]
+    source = "incremental"    # ← Activate Incremental's Hatchling plugin
 
-   from ._version import __version__
+Incremental can be configured as usual in an optional ``[tool.incremental]`` table.
 
+The ``hatch version`` command will report the Incremental-managed version.
+Use the ``python -m incremental.update`` command to change the version (setting it with ``hatch version`` is not supported).
 
-Subsequent installations of your project will then use Incremental for versioning.
+Next, `initialize the project`_.
 
 
 Using ``setup.py``
@@ -74,7 +93,34 @@ Add this to your ``setup()`` call, removing any other versioning arguments:
        ...
    }
 
-Then proceed with the ``incremental.update`` command above.
+Then `initialize the project`_.
+
+
+Initialize the project
+~~~~~~~~~~~~~~~~~~~~~~
+
+Install Incremental to your local environment with ``pip install incremental[scripts]``.
+Then run ``python -m incremental.update <projectname> --create``.
+It will create a file in your package named ``_version.py`` like this:
+
+.. code:: python
+
+   from incremental import Version
+
+   __version__ = Version("<projectname>", 24, 1, 0)
+   __all__ = ["__version__"]
+
+
+Then, so users of your project can find your version, in your root package's ``__init__.py`` add:
+
+.. code:: python
+
+   from ._version import __version__
+
+
+Subsequent installations of your project will then use Incremental for versioning.
+
+
 
 Incremental Versions
 --------------------
@@ -90,7 +136,7 @@ It is made up of the following elements (which are given during instantiation):
 
 You can extract a PEP-440 compatible version string by using the ``.public()`` method, which returns a ``str`` containing the full version. This is the version you should provide to users, or publicly use. An example output would be ``"13.2.0"``, ``"17.1.2dev1"``, or ``"18.8.0rc2"``.
 
-Calling ``repr()`` with a ``Version`` will give a Python-source-code representation of it, and calling ``str()`` with a ``Version`` will provide a string similar to ``'[Incremental, version 16.10.1]'``.
+Calling ``repr()`` with a ``Version`` will give a Python-source-code representation of it, and calling ``str()`` on a ``Version`` produces a string like ``'[Incremental, version 16.10.1]'``.
 
 
 Updating

pyproject.toml

@@ -16,6 +16,7 @@ maintainers = [
 classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
+    "Framework :: Hatch",
     "Framework :: Setuptools Plugin",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.8",
@@ -36,9 +37,6 @@ dependencies = [
 scripts = [
     "click>=6.0",
 ]
-mypy = [
-    "mypy==0.812",
-]
 
 [project.urls]
 Homepage = "https://github.com/twisted/incremental"
@@ -50,6 +48,8 @@ Changelog = "https://github.com/twisted/incremental/blob/trunk/NEWS.rst"
 use_incremental = "incremental:_get_distutils_version"
 [project.entry-points."setuptools.finalize_distribution_options"]
 incremental = "incremental:_get_setuptools_version"
+[project.entry-points.hatch]
+incremental = "incremental._hatch"
 
 [tool.setuptools.dynamic]
 version = {attr = "incremental._setuptools_version"}

requirements_mypy.in

@@ -0,0 +1,3 @@
+mypy==0.812
+twisted
+hatchling  # for types

requirements_mypy.txt

@@ -0,0 +1,51 @@
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile --output-file=requirements_mypy.txt requirements_mypy.in
+#
+attrs==23.2.0
+    # via
+    #   automat
+    #   twisted
+automat==22.10.0
+    # via twisted
+constantly==23.10.4
+    # via twisted
+hatchling==1.25.0
+    # via -r requirements_mypy.in
+hyperlink==21.0.0
+    # via twisted
+idna==3.7
+    # via hyperlink
+incremental==22.10.0
+    # via twisted
+mypy==0.812
+    # via -r requirements_mypy.in
+mypy-extensions==0.4.4
+    # via mypy
+packaging==24.1
+    # via hatchling
+pathspec==0.12.1
+    # via hatchling
+pluggy==1.5.0
+    # via hatchling
+six==1.16.0
+    # via automat
+tomli==2.0.1
+    # via hatchling
+trove-classifiers==2024.7.2
+    # via hatchling
+twisted==24.3.0
+    # via -r requirements_mypy.in
+typed-ast==1.4.3
+    # via mypy
+typing-extensions==4.12.2
+    # via
+    #   mypy
+    #   twisted
+zope-interface==6.4.post2
+    # via twisted
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools

requirements_tests.in

@@ -0,0 +1,5 @@
+build
+coverage
+coverage-p
+twisted
+hatch

requirements_tests.txt

@@ -0,0 +1,153 @@
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile --output-file=requirements_tests.txt requirements_tests.in
+#
+anyio==4.4.0
+    # via httpx
+attrs==23.2.0
+    # via
+    #   automat
+    #   twisted
+automat==22.10.0
+    # via twisted
+backports-tarfile==1.2.0
+    # via jaraco-context
+build==1.2.1
+    # via -r requirements_tests.in
+certifi==2024.7.4
+    # via
+    #   httpcore
+    #   httpx
+cffi==1.16.0
+    # via cryptography
+click==8.1.7
+    # via
+    #   hatch
+    #   userpath
+constantly==23.10.4
+    # via twisted
+coverage==7.5.4
+    # via
+    #   -r requirements_tests.in
+    #   coverage-p
+coverage-p==24.7.0
+    # via -r requirements_tests.in
+cryptography==42.0.8
+    # via secretstorage
+distlib==0.3.8
+    # via virtualenv
+exceptiongroup==1.2.1
+    # via anyio
+filelock==3.15.4
+    # via virtualenv
+h11==0.14.0
+    # via httpcore
+hatch==1.12.0
+    # via -r requirements_tests.in
+hatchling==1.25.0
+    # via hatch
+httpcore==1.0.5
+    # via httpx
+httpx==0.27.0
+    # via hatch
+hyperlink==21.0.0
+    # via
+    #   hatch
+    #   twisted
+idna==3.7
+    # via
+    #   anyio
+    #   httpx
+    #   hyperlink
+importlib-metadata==8.0.0
+    # via keyring
+incremental==22.10.0
+    # via twisted
+jaraco-classes==3.4.0
+    # via keyring
+jaraco-context==5.3.0
+    # via keyring
+jaraco-functools==4.0.1
+    # via keyring
+jeepney==0.8.0
+    # via
+    #   keyring
+    #   secretstorage
+keyring==25.2.1
+    # via hatch
+markdown-it-py==3.0.0
+    # via rich
+mdurl==0.1.2
+    # via markdown-it-py
+more-itertools==10.3.0
+    # via
+    #   jaraco-classes
+    #   jaraco-functools
+packaging==24.1
+    # via
+    #   build
+    #   hatch
+    #   hatchling
+pathspec==0.12.1
+    # via hatchling
+pexpect==4.9.0
+    # via hatch
+platformdirs==4.2.2
+    # via
+    #   hatch
+    #   virtualenv
+pluggy==1.5.0
+    # via hatchling
+ptyprocess==0.7.0
+    # via pexpect
+pycparser==2.22
+    # via cffi
+pygments==2.18.0
+    # via rich
+pyproject-hooks==1.1.0
+    # via build
+rich==13.7.1
+    # via hatch
+secretstorage==3.3.3
+    # via keyring
+shellingham==1.5.4
+    # via hatch
+six==1.16.0
+    # via automat
+sniffio==1.3.1
+    # via
+    #   anyio
+    #   httpx
+tomli==2.0.1
+    # via
+    #   build
+    #   hatchling
+tomli-w==1.0.0
+    # via hatch
+tomlkit==0.13.0
+    # via hatch
+trove-classifiers==2024.7.2
+    # via hatchling
+twisted==24.3.0
+    # via -r requirements_tests.in
+typing-extensions==4.12.2
+    # via
+    #   anyio
+    #   twisted
+userpath==1.9.2
+    # via hatch
+uv==0.2.24
+    # via hatch
+virtualenv==20.26.3
+    # via hatch
+zipp==3.19.2
+    # via importlib-metadata
+zope-interface==6.4.post2
+    # via twisted
+zstandard==0.22.0
+    # via hatch
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools