Use poetry for project tooling. Deprecate module metadata.

.github/actions/build-project/action.yml

@@ -17,11 +17,9 @@ runs:
     - name: Install host python dependencies
       shell: bash
       run: |
-        python -m pip install --upgrade setuptools build
-        python -m pip install . .[dev] .[docs] .[test]
-        pip freeze \
-          --exclude rule34Py \
-          >build/requirements.txt
+        pipx install poetry
+        poetry self update
+        poetry install
 
     - name: Build wheel and dist
       shell: bash

.github/workflows/ci-develop.yml

@@ -32,5 +32,4 @@ jobs:
       - name: Run unit tests
         shell: bash
         run: |
-          python -m pip install .[test]
           make check

.github/workflows/pr-checks.yml

@@ -41,5 +41,7 @@ jobs:
       - name: Lint sources
         shell: bash
         run: |
-          python -m pip install .[dev]
+          pipx install poetry
+          poetry self update
+          poetry install
           make lint

Makefile

@@ -3,12 +3,14 @@ PROJECT = $(shell $(PYTHON3) scripts/read_pyproject.py project/name | tr 'A-Z' '
 VERSION = $(shell $(PYTHON3) scripts/read_pyproject.py project/version)
 
 # Binaries
-PYTHON3 ?= python3
-PYTEST = $(PYTHON3) -m pytest
-PYTHON_BUILD = $(PYTHON3) -m build
-RUFF = $(PYTHON3) -m ruff
-SPHINX = $(PYTHON3) -m sphinx
-TWINE = $(PYTHON3) -m twine
+POETRY ?= poetry $(POETRY_ARGS)
+POETRY_ARGS ?=
+PYTHON3 ?= $(POETRY) run python3
+
+PYTEST = $(POETRY) run pytest $(PYTEST_ARGS)
+PYTEST_ARGS ?=
+RUFF = $(POETRY) run ruff
+SPHINX_BUILD = $(POETRY) run sphinx-build
 
 # Source files
 builddir ?= build
@@ -38,11 +40,11 @@ htmldir ?= $(docdir)/html
 ################
 
 $(wheels) &: $(dist_files)
-	$(PYTHON_BUILD) --outdir $(builddir) --wheel
+	$(POETRY) build --output $(builddir) --format=wheel
 
 
 $(sdist) : $(dist_files)
-	$(PYTHON_BUILD) --outdir $(builddir) --sdist
+	$(POETRY) --output $(builddir) --format=sdist
 
 
 # PHONY TARGETS #
@@ -56,7 +58,7 @@ all : $(wheels)
 
 # Run pre-installation tests on the built artifacts.
 check : all
-	PYTHONPATH=$(builddir)/lib $(PYTEST) tests/unit/
+	PYTHONPATH=. $(PYTEST) tests/unit/
 .PHONY : check
 
 
@@ -75,19 +77,24 @@ dist : $(sdist)
 
 # Check and publish the python package index artifacts.
 publish : $(sdist) $(wheels)
-	$(TWINE) check $(^)
-	$(TWINE) upload $(^)
+	$(POETRY) publish --dist-dir=$(builddir)
 .PHONY : publish
 
 
 # Build the project's HTML documentation.
 html :
-	$(SPHINX) --builder html docs $(builddir)/html
+	$(SPHINX_BUILD) --builder html docs $(builddir)/html
 .PHONY : html
 
 
+linkcheck :
+	$(SPHINX_BUILD) --builder linkcheck docs $(builddir)/linkcheck
+.PHONY : linkcheck
+
+
 # Lint the project source for quality.
-lint :
+lint : linkcheck
+	$(POETRY) check --strict
 	$(RUFF) check $(srcdir)
 .PHONY : lint
 

docs/conf.py

@@ -53,6 +53,13 @@
     "requests": ("https://requests.readthedocs.io/en/latest/", None),
 }
 
+## Sphinx linkcheck options
+linkcheck_ignore = [
+    r"https?://.*gnu.org(:\d+)?[/$]?.*",  # GNU.org is heavily rate limited
+    r"https?://localhost(:\d+)?[/$]?.*",  # Broken unless the dev is hosting a server.
+    r"https?://rule34.xxx(:\d+)?[/$]?.*",  # Interactive site will always 403
+]
+
 
 
 # -- Options for HTML output -------------------------------------------------

docs/dev/contributing.rst

@@ -6,7 +6,7 @@ Thanks for taking an interest in contributing to the rule34Py project!
 
 * This project's **canonical upstream** is at https://github.com/b3yc0d3/rule34Py.
 * File **bugs**, **enhancement requests**, and other **issues** to the GH issue tracker at https://github.com/b3yc0d3/rule34Py/issues.
-* See the `Developer Guide <./developer-guide.html>`_ for information about how to **build** this project from source and run tests.
+* See the :doc:`Developer Guide <./developer-guide>` for information about how to **build** this project from source and run tests.
 
 
 Submitting Changes
@@ -18,7 +18,7 @@ Submitting Changes
 
     .. code-block:: bash
 
-        pip install .[dev]
+        poetry install  # Optional, if you have not done it previously.
         make lint
 
     Fix or respond to any findings in the linter.
@@ -27,7 +27,7 @@ Submitting Changes
 
     .. code-block:: bash
 
-        pip install .[test]
+        poetry install  # Optional, if you have not done it previously.
         make check
 
 #. Write a good commit message. If you are unsure of how, `this cbeams article <https://cbea.ms/git-commit/>`_ gives reasonable suggestions. Commit your changes.

docs/dev/developer-guide.rst

@@ -8,7 +8,7 @@ tl;dr
 
 .. code-block:: bash
 
-    pip install . .[docs] .[dev] .[test]
+    poetry install
     make all    # build wheel
     make check  # run unit tests
     make dist   # build sdist
@@ -34,6 +34,12 @@ Building the project from source
 ================================
 
 This project can be built directly from source using a few host tools.
+At a minimum you will require:
+
+- `git <https://git-scm.com/downloads>`_
+- `GNU Make <https://www.gnu.org/software/make/>`_
+- `poetry <https://python-poetry.org/>`_
+
 Supported development environments include:
 
 - Ubuntu 24.04
@@ -48,28 +54,15 @@ The following instructions are written on the assumption that you are building i
         git clone https://github.com/b3yc0d3/rule34Py.git
         cd rule34Py
 
-#. (Optional. Recommended.) Setup a python virtual environment.
+#. Use poetry to install project python dependencies from the ``pyproject.toml`` file. Use ``GNU Make`` to build the project. The ``all`` make target (the default) builds the project's wheels.
 
     .. code-block:: bash
 
-        python -m venv .venv
-        echo "/.venv" >>.git/info/exclude  # excludes your venv from git tracking
-        source .venv/bin/activate
-
-#. Install project python dependencies from the ``pyproject.toml`` file. Use ``GNU Make`` to build the project. The ``all`` make target (the default) builds the project's wheels.
-
-    .. code-block:: bash
-
-        pip install . .[dev]
+        poetry install
         make all
 
     Build output will be placed in the ``:build/`` directory in your workspace.
 
-.. Note::
-
-    If you are using a very old python environment, your installed version of setuptools and python may not be aware of how to process pyproject.toml files.
-    If this seems to be the case, try upgrading your build tools by calling ``python -m pip install --upgrade setuptools build``.
-
 Other ``make`` targets are supported to ``clean`` the project and build other artifacts.
 Generally, the project ``Makefile`` honors the `GNU Standard Targets <https://www.gnu.org/software/make/manual/html_node/Standard-Targets.html>`_ specification.
 
@@ -79,13 +72,20 @@ Running the project test suite
 
 #. Setup your build environment as in the "Building the project from source" section.
 
-#. Install the optional test dependencies and invoke their ``make`` target.
+#. Use poetry to run the unit tests, by invoking the ``check`` target.
 
     .. code-block:: bash
 
-        pip install .[test]
         make test
 
+.. tip::
+
+    You can invoke a single test by passing appropriate arguments to the ``PYTEST_ARGS`` variable during invocation. eg.
+
+    .. code-block:: bash
+
+        PYTEST_ARGS="-k package" make check
+
 For more information, reference the ``:tests/README.md`` file.
 
 
@@ -94,11 +94,10 @@ Building the project documentation
 
 #. Setup your build environment as in the "Building the project from source" section.
 
-#. Install the optional docs dependencies and invoke their ``make`` target.
+#. Use poetry to build the project documentation by invoking the ``html`` target.
 
     .. code-block:: bash
 
-        pip install .[docs]
         make html
 
     Build output will be placed in the ``:build/html/`` directory.
@@ -116,10 +115,10 @@ Building the project documentation
 Integrating this project
 ========================
 
-This project is `licensed <./license.html#license>`_ under the GPLv3 license.
+This project is :ref:`licensed <license-text>` under the GPLv3 license.
 Ensure that your project's licensing strategy is compatible with the GPL.
 For more information, reference the GNU reference guide for GPLv3 `here <https://www.gnu.org/licenses/gpl-3.0.en.html>`_.
 
 All direct dependencies of this project are either GPL licensed, or are licensed more permissively.
-But testing code does call the ``reponses`` module, which is licensed under the Apache 2.0 license.
-Reference the `:NOTICE.md <./license.html#notice>`_ file for more information.
+But testing code does call the ``responses`` module, which is licensed under the Apache 2.0 license.
+Reference the :ref:`:NOTICE.md <notice-text>` file for more information.

docs/dev/license.rst

@@ -1,9 +1,12 @@
 
+.. _license-text:
+
 LICENSE
 =======
 
 .. literalinclude:: ../../LICENSE
 
 
-.. NOTICE.md already includes an H1 header.
+.. _notice-text:
+
 .. mdinclude:: ../../NOTICE.md

docs/guides/captcha-clearance.rst

@@ -14,7 +14,7 @@ In order to enable these interactive workflows, while providing at least some re
 Note that the module will rate-limit requests to the interactive site to 1 request per second, as a further courtesy to the site owners.
 We also recommend avoiding these workflows entirely in your application design, out of respect.
 
-Reference the `rule34Py.rule34Py <../../api/rule34Py/rule34.html#rule34Py.rule34.rule34Py>`_ class documentation for an indication of which workflows have these limits.
+Reference the :doc:`rule34Py.rule34Py <../../api/rule34Py/rule34>` class documentation for an indication of which workflows have these limits.
 
 
 Clearing the defenses

docs/guides/index.rst

@@ -7,3 +7,4 @@ This section contains how-to guides and special topics of interest to module use
 	:maxdepth: 1
 
 	captcha-clearance
+	package-metadata

docs/guides/package-metadata.rst

@@ -0,0 +1,53 @@
+How to get package metadata
+===========================
+
+Rule34Py is generally a `PEP440 <https://peps.python.org/pep-0440/>`_-compliant package.
+Therefore, it provides package metadata describing critical details relevant to package integrators.
+
+This guide describes how to extract pieces of that package metadata, from your installed copy of rule34Py.
+
+
+Ownership and Maintainership
+----------------------------
+
+Extract the package's **maintainership** information by interrogating the ``Maintainer*`` fields using the ``importlib.metadata`` module.
+
+.. code-block:: python
+
+	from importlib.metadata import metadata
+	maintainer = metadata("rule34Py")["Maintainer"]
+	maintainer_email = metadata("rule34Py")["Maintainer-email"]
+
+The package's canonical **author** is the same as the maintainer.
+
+If you need detailed information about who authored a specific segment of the project code, use ``git blame`` to interrogate the code files directly.
+
+
+Project Version
+---------------
+
+Extract the project's **version** information using the ``importlib.metadata.version`` method.
+
+.. code-block:: python
+
+	from importlib.metadata import version
+	rule34Py_version = version("rule34Py")
+
+The project's version is guaranteed to be PEP440 compliant.
+
+.. tip::
+
+	You can also get the project version from the ``importlib.metadata.metadata("rule34Py")["Version"]`` field.
+
+
+License Information
+-------------------
+
+Extract the project's SPDX license identifier by interrogating the package metadata ``License`` field.
+
+.. code-block:: python
+
+	from importlib.metadata import metadata
+	license = metadata("rule34Py")["License"]
+
+The direct :ref:`license text<license-text>` and :ref:`notice text<notice-text>` can be taken from the project documentation, or from the distribution ``:LICENSE`` and ``:NOTICE.md`` files respectively.