Move setup.py metadata to pyproject.toml

docs/sources/how-to/index.md

@@ -45,6 +45,13 @@ Set up CI jobs, Python version matrices, OS dependencies, and environment variab
 Set up CI pipelines for GitLab-hosted repositories, including custom Docker images and OS dependencies.
 :::
 
+:::{grid-item-card} Convert `setup.py` metadata to `pyproject.toml`
+:link: setup-to-pyproject
+:link-type: doc
+
+Convert the metadata in `setup.py` to `pyproject.toml`
+:::
+
 :::{grid-item-card} Re-enable GitHub Actions
 :link: re-enable-actions
 :link-type: doc

docs/sources/how-to/setup-to-pyproject.md

@@ -0,0 +1,71 @@
+# Convert setup.py metadata to pyproject.toml
+
+`pyproject.toml`'s `[project]` metadata is the standard place to find a project metadata.
+
+Historically this was on `setup.py`, but it had plenty of problems.
+
+Now, you can write all of a project's metadata in `pyproject.toml`,
+[see the specification](https://packaging.python.org/en/latest/specifications/pyproject-toml/).
+
+All plone and collective python distributions are using `setup.py` to keep each project's metadata.
+
+[`zope.meta`](https://pypi.org/project/zope.meta) created a script to move the metadata from `setup.py` to `pyproject.toml`.
+
+In `plone.meta` this script from `zope.meta` has been adapted to suit the needs of the Plone ecosystem.
+
+## Conversion
+
+To convert the metadata do the following:
+
+```bash
+cd $REPOSITORY
+uvx --from plone.meta setup-to-pyproject .
+```
+
+i.e. go to your repository and run the `setup-to-pyproject` script from `plone.meta`.
+
+This will automatically create a commit on your repository with the changes.
+
+:::{note}
+Please review them carefully to ensure that the conversion was done properly.
+:::
+
+Ideally `setup.py` should look like this:
+
+```python
+from setuptools import setup
+
+# See pyproject.toml for package metadata
+setup()
+```
+
+### Issues link
+
+`setup-to-pyproject` accepts an optional argument: `--issues`.
+
+This option is to customize the issues link displayed on PyPI related to the project.
+
+It accepts the following options:
+
+- `own`: use the repository itself as the issue tracker
+- _URL_: provide a custom URL that will be used verbatim
+- _None_: if no value is provided `Products.CMFPlone` issue tracker is used
+
+## Clean up
+
+Run some tooling `tox run -e test` to ensure that the conversion worked.
+
+:::{note}
+It might be that the license field in `project.license` within `pyproject.toml` is broken.
+
+Please have a look at valid [license expressions](https://packaging.python.org/en/latest/specifications/license-expression/) to solve it.
+:::
+
+Re-configure the repository with `plone.meta` to ensure that the project metadata is kept:
+
+```bash
+cd $REPOSITORY
+uvx --from plone.meta config-package branch=current .
+```
+
+Make sure to review the commit generated by `config-package`.

news/315.feature

@@ -0,0 +1 @@
+Add `setup-to-pyproject` script to move `setup.py` metadata into `pyproject.toml` @gforcada

pyproject.toml

@@ -58,6 +58,7 @@ config-package = "plone.meta.config_package:main"
 multi-call = "plone.meta.multi_call:main"
 re-enable-actions = "plone.meta.re_enable_actions:main"
 switch-to-pep420 = "plone.meta.pep_420:main"
+setup-to-pyproject = "plone.meta.setup_to_pyproject:main"
 
 [tool.towncrier]
 directory = "news/"
@@ -119,4 +120,5 @@ omit = [
     "src/plone/meta/re_enable_actions.py",
     "src/plone/meta/pep_420.py",
     "src/plone/meta/multi_call.py",
+    "src/plone/meta/setup_to_pyproject.py",
     ]

src/plone/meta/config_package.py

@@ -356,6 +356,45 @@ def _setuptools_upper_bound(self):
             return "82"
         return "83"
 
+    def _detect_setup_py_for_package_config(self):
+        """Dynamically find out if setup.py is used for package configuration.
+
+        If `pyproject.toml` contains some specific content, we assume that this
+        file is used for package configuration, and `setup.py` is basically empty.
+        Main reason: in that case `check-python-versions` fails if we ask it to
+        check `setup.py`.
+        """
+        if not (self.path / "setup.py").exists():
+            # If the file does not even exist, it is definitely not used. ;-)
+            return False
+        pyproject = self.path / "pyproject.toml"
+        if not pyproject.exists():
+            # Should not happen.  But if this file does not exist, then
+            # `setup.py` will be used.
+            return True
+        text = pyproject.read_text()
+        # If any of these markers do NOT exist in the `pyproject.toml` file,
+        # we conclude that `setup.py` is still used.
+        markers = [
+            "START-MARKER-MANUAL-CONFIG",
+            "[project]",
+            "Programming Language :: Python",
+            "requires-python",
+        ]
+        return any([marker not in text for marker in markers])
+
+    def _check_python_versions_files(self, using_setup_py):
+        """Which files should be checked by check-python-versions?
+
+        This is for inclusion in the pre-commit config:
+
+            id: check-python-versions
+            args: ['--only', 'setup.py,pyproject.toml']
+        """
+        if using_setup_py:
+            return "setup.py,tox.ini"
+        return "pyproject.toml,tox.ini"
+
     def pre_commit_config(self):
         options = self._get_options_for(
             "pre_commit",
@@ -370,6 +409,9 @@ def pre_commit_config(self):
 
         python_version = self._minimal_python_version()
         options["minimal_python_version"] = self._no_dot_python_version(python_version)
+        options["check_python_versions_files"] = self._check_python_versions_files(
+            self._detect_setup_py_for_package_config()
+        )
 
         return self.copy_with_meta(
             "pre-commit-config.yaml.j2",

src/plone/meta/default/pre-commit-config.yaml.j2

@@ -66,7 +66,7 @@ repos:
     rev: "0.24.0"
     hooks:
     -   id: check-python-versions
-        args: ['--only', 'setup.py,pyproject.toml']
+        args: ['--only', '%(check_python_versions_files)s']
 -   repo: https://github.com/collective/i18ndude
     rev: "6.3.0"
     hooks: