Merge pull request #91 from twisted/90-pyproject.toml

Support pyproject.toml

.coveragerc

@@ -4,6 +4,10 @@ source_pkgs = incremental
 # List of directory names.
 source = tests
 branch = True
+parallel = True
+# This must be an absolute path because the example tests
+# run Python processes with alternative working directories.
+data_file = ${TOX_INI_DIR-.}/.coverage
 
 [paths]
 source =

.github/workflows/tests.yaml

@@ -86,13 +86,13 @@ jobs:
       run: |
         # Assign the coverage file a name unique to this job so that the
         # uploads don't collide.
-        mv .coverage ".coverage-job-${{ matrix.python-version }}-${{ matrix.job-name }}"
+        mv .coverage ".coverage-job-${{ matrix.python-version }}-${{ matrix.tox-env }}"
 
     - name: Store coverage file
       if: ${{ !cancelled() && !matrix.skip-coverage }}
       uses: actions/upload-artifact@v4
       with:
-        name: coverage-${{ matrix.python-version }}-${{ matrix.job-name }}
+        name: coverage-${{ matrix.python-version }}-${{ matrix.tox-env }}
         path: .coverage-job-*
 
   coverage-report:

MANIFEST.in

@@ -1,17 +1,20 @@
-include .coveragerc
 include LICENSE
 include NEWS.rst
-include towncrier.ini
+include SECURITY.md
 include tox.ini
-exclude mypy.ini
-include src/incremental/py.typed
+include _build_meta.py
 
 recursive-include src/incremental *.py
+include src/incremental/py.typed
+prune src/incremental/newsfragments
 
-prune .travis
-prune tests
+global-exclude .coverage*
+include .coveragerc
 
-exclude examplesetup.py
-prune src/exampleproj
+graft tests
+prune tests/example_*/src/*.egg-info
+prune tests/example_*/build
+prune tests/example_*/dist
+
+global-exclude __pycache__ *.py[cod] *~
 
-prune src/incremental/newsfragments

README.rst

@@ -7,46 +7,75 @@ Incremental
 
 Incremental is a small library that versions your Python projects.
 
-API documentation can be found `here <https://twisted.github.io/incremental/docs/>`_.
+API documentation can be found `here <https://twisted.org/incremental/docs/>`_.
 
 
 Quick Start
 -----------
 
-Add this to your ``setup.py``\ 's ``setup()`` call, removing any other versioning arguments:
+In your ``pyproject.toml``, add Incremental to your build requirements:
 
-.. code::
+.. code-block:: toml
 
-   setup(
-       use_incremental=True,
-       setup_requires=['incremental'],
-       install_requires=['incremental'], # along with any other install dependencies
-       ...
-   }
+    [build-system]
+    requires = ["setuptools", "incremental>=NEXT"]
+    build-backend = "setuptools.build_meta"
+
+Specify the project's version as dynamic:
+
+.. code-block:: toml
+
+    [project]
+    name = "<projectname>"
+    dynamic = ["version"]
+
+Remove any ``version`` line and any ``[tool.setuptools.dynamic] version = `` entry.
+
+Add this empty block to activate Incremental's setuptools plugin:
+
+.. code-block:: toml
 
+    [tool.incremental]
 
 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:
 
-.. code::
+.. code:: python
 
    from incremental import Version
 
-   __version__ = Version("widgetbox", 17, 1, 0)
+   __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::
+.. code:: python
 
    from ._version import __version__
 
 
 Subsequent installations of your project will then use Incremental for versioning.
 
 
+Using ``setup.py``
+~~~~~~~~~~~~~~~~~~
+
+Incremental may be used from ``setup.py`` instead of ``pyproject.toml``.
+Add this to your ``setup()`` call, removing any other versioning arguments:
+
+.. code:: python
+
+   setup(
+       use_incremental=True,
+       setup_requires=['incremental'],
+       install_requires=['incremental'], # along with any other install dependencies
+       ...
+   }
+
+Then proceed with the ``incremental.update`` command above.
+
 Incremental Versions
 --------------------
 

_build_meta.py

@@ -0,0 +1,18 @@
+"""
+Comply with PEP 517's restictions on in-tree backends.
+
+We use setuptools to package Incremental and want to activate
+the in-tree Incremental plugin to manage its own version. To do
+this we specify ``backend-path`` in our ``pyproject.toml``,
+but PEP 517 requires that when ``backend-path`` is specified:
+
+> The backend code MUST be loaded from one of the directories
+> specified in backend-path (i.e., it is not permitted to
+> specify backend-path and not have in-tree backend code).
+
+We comply by re-publishing setuptools' ``build_meta``.
+"""
+
+from setuptools import build_meta
+
+__all__ = ["build_meta"]

pyproject.toml

@@ -1,9 +1,57 @@
 [build-system]
 requires = [
-    "setuptools >= 44.1.1",
-    "wheel >= 0.36.2",
+    # Keep this aligned with the project dependencies.
+    "setuptools >= 61.0",
+    "tomli; python_version < '3.11'",
 ]
-build-backend = "setuptools.build_meta"
+backend-path = [".", "./src"]  # See _build_meta.py
+build-backend = "_build_meta:build_meta"
+
+[project]
+name = "incremental"
+dynamic = ["version"]
+maintainers = [
+    {name = "Amber Brown", email = "[email protected]"},
+]
+classifiers = [
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Framework :: Setuptools Plugin",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">=3.8"
+description = "A small library that versions your Python projects."
+readme = "README.rst"
+dependencies = [
+    "setuptools >= 61.0",
+    "tomli; python_version < '3.11'",
+]
+
+[project.optional-dependencies]
+scripts = [
+    "click>=6.0",
+]
+mypy = [
+    "mypy==0.812",
+]
+
+[project.urls]
+Homepage = "https://github.com/twisted/incremental"
+Documentation = "https://twisted.org/incremental/docs/"
+Issues = "https://github.com/twisted/incremental/issues"
+Changelog = "https://github.com/twisted/incremental/blob/trunk/NEWS.rst"
+
+[project.entry-points."distutils.setup_keywords"]
+use_incremental = "incremental:_get_distutils_version"
+[project.entry-points."setuptools.finalize_distribution_options"]
+incremental = "incremental:_get_setuptools_version"
+
+[tool.incremental]
 
 [tool.black]
 target-version = ['py36', 'py37', 'py38']
@@ -12,3 +60,4 @@ target-version = ['py36', 'py37', 'py38']
 filename = "NEWS.rst"
 package_dir = "src/"
 package = "incremental"
+issue_format = "`#{issue} <https://github.com/twisted/incremental/issues/{issue}>`__"

setup.cfg

@@ -1,48 +1,3 @@
-[metadata]
-name = incremental
-version = attr: incremental._setuptools_version
-maintainer = Amber Brown
-maintainer_email = [email protected]
-url = https://github.com/twisted/incremental
-classifiers =
-    Intended Audience :: Developers
-    License :: OSI Approved :: MIT License
-    Programming Language :: Python :: 3
-    Programming Language :: Python :: 3.8
-    Programming Language :: Python :: 3.9
-    Programming Language :: Python :: 3.10
-    Programming Language :: Python :: 3.11
-    Programming Language :: Python :: 3.12
-license = MIT
-description = "A small library that versions your Python projects."
-long_description = file: README.rst
-install_requires =
-    setuptools
-
-[options]
-packages = find:
-package_dir = =src
-zip_safe = False
-
-[options.packages.find]
-where = src
-exclude = exampleproj
-
-[options.package_data]
-incremental = py.typed
-
-[options.entry_points]
-distutils.setup_keywords =
-    use_incremental = incremental:_get_version
-
-[options.extras_require]
-scripts =
-    click>=6.0
-    twisted>=16.4.0
-mypy =
-    %(scripts)s
-    mypy==0.812
-
 [flake8]
 max-line-length = 88
 extend-ignore =