Lint, Test, and Build PRs using github workflows.

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

@@ -1,21 +1,42 @@
-name: Build the project
-description: Installs project dependencies and builds the project
+name: Build and test
+description: Builds and tests the project
 
 inputs:
-  latest_python:
-    default: false
+  python-version:
+    default: '3.x'
 
 runs:
   using: "composite"
   steps:
+
     - name: Set up Python
       uses: actions/setup-python@v5
       with:
-        python-version: ">=3.5"
-        check-latest: ${{ inputs.latest_python }}
+        python-version: ${{ inputs.python-version }}
 
-    - name: Build documentation
+    - 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
+
+    - name: Build wheel and dist
       shell: bash
       run: |
-        python3 -m pip install .[docs]
-        make html
+        make all
+        make dist
+
+    - name: Build documentation
+      shell: bash
+      run: make html
+
+    - name: Upload build artifacts
+      if: ${{ inputs.python-version == '3.x' }}
+      uses: actions/upload-artifact@v4
+      with:
+        name: build.${{ github.run_id }}-${{ github.run_number }}.${{ runner.os }}-py${{ inputs.python-version }}
+        path: ./build
+        retention-days: 14

.github/workflows/cd-master.yml

@@ -0,0 +1,45 @@
+name: Continuous Delivery
+# This workflow performs post-push actions on the 'master' branch.
+# It should build the final version of the branch artifacts, that might be
+# released to PyPi or GH. And it should build and deploy the GH Pages artifacts.
+
+on:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build the project
+        uses: ./.github/actions/build-project
+        with:
+          python-version: '3.x'
+
+  gh-pages:
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: ./build
+          pattern: build.*.Linux-py3.x
+          merge-multiple: true
+
+      - name: Deploy to Github Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build/html

.github/workflows/ci-develop.yml

@@ -0,0 +1,36 @@
+name: CI Testing
+# This pipeline builds and tests the project.
+# Commits that pass this workflow can be assumed to be functionally correct,
+# per the current state of the mock responses registry.
+
+on:
+  pull_request:
+    types: [opened, edited, synchronize, reopened]
+  push:
+    branches:
+      - develop
+
+jobs:
+  build-and-test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.x', '3.9']
+        os: [ubuntu-latest, windows-latest]
+
+    name: Build ${{ matrix.os }}-py${{ matrix.python-version }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Build the project
+        uses: ./.github/actions/build-project
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Run unit tests
+        shell: bash
+        run: |
+          python -m pip install .[test]
+          make check

.github/workflows/pr-checks.yml

@@ -1,44 +1,45 @@
 name: PR Checks
+# This workflow runs on PRs opened on the repo's 'develop' branch.
+# It's purpose is to check that repository policies around PR and source quality
+# and syntax are honored by developers. Commits which pass this workflow are
+# quality enough that they can be merged.
+# This workflow does not verify code correctness or run tests.
 
 on:
   pull_request:
     branches:
-      - "**"
+      - develop
+    types: [opened, edited, synchronize, reopened]
 
 jobs:
-  build-linux:
+  pr-quality:
+    name: PR Quality Checks
+    # Validates the quality of the PR and its constituent commits, against
+    # the policies of the upstream repo.
     runs-on: ubuntu-latest
+    steps:
+      - name: Check PR target branch
+        run: |
+          echo "PR is targeting branch: ${{ github.event.pull_request.base.ref }}"
+          if [ "${{ github.event.pull_request.base.ref }}" != "develop" ]; then
+            echo "❌ Pull request must target 'develop' branch!"
+            exit 1
+          fi
 
+  source-quality:
+    runs-on: ubuntu-latest
+    name: Source Quality Checks
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Build the project
-        uses: ./.github/actions/build-project
+      - name: Set up python
+        uses: actions/setup-python@v5
         with:
-          latest_python: true  # always use the latest python in PR checks
+          python-version: '3.x'
 
-      - name: Upload build artifacts
-        uses: actions/upload-artifact@v4
-        with:
-          name: build-${{ github.run_id }}-${{ github.run_number }}
-          path: ./build
-          retention-days: 14
-
-      - name: Lint the project
+      - name: Lint sources
         shell: bash
         run: |
           python -m pip install .[dev]
           make lint
-
-
-  build-windows:
-    runs-on: windows-latest
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Build the project
-        uses: ./.github/actions/build-project
-        with:
-          latest_python: true  # always use the latest python in PR checks

.gitignore

@@ -159,3 +159,5 @@ Thumbs.db
 
 
 # End of https://www.toptal.com/developers/gitignore/api/python
+
+**/.ruff_cache

CHANGELOG.md

@@ -12,19 +12,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Added captcha-compliance capabilities. You can now pass the client your captcha clearance token by completing the captcha in your browser, opening the response header, and writing your `cf_clearance` token into the client's `rule34Py.captcha_clearance` attribute and setting the client's `user_agent` attribute to match your browser.
 	- Alternatively, set your execution environment's `R34_CAPTCHA_CLEARANCE` and `R34_USER_AGENT` variables to the appropriate values. The client will read form them during initialization.
+	- See [this user guide](https://b3yc0d3.github.io/rule34Py/guides/captcha-clearance.html) for more information. (#24)
 - Added a rate limiter for requests to the rule34.xxx base site (the PHP endpoint). By default, the client will now limit API calls that use this endpoint to 1 per second.
 	- This behavior can be disabled by setting `rule34Py.set_base_site_rate_limit(False)`.
 	- There is no rate limit on the api.rule34.xxx endpoint, which is assumed to handle rate-limiting on the server-side.
 	- This new feature requires the `requests-ratelimiter` module.
+- Added project documentation via sphinx docs. See: https://b3yc0d3.github.io/rule34Py/. It can be built by calling `make html`. (#24)
 
 ### Changed
 
 - Changed the behavior of the `rule34Py.random_post()` method to function more like the website. The method now accepts no `tag` parameters, and returns a random post ID from all posts on the site. Users who want to use the old behavior of returning a random post from the first 1000 tag-search results are directed to do something like `random.choice(rule34Py.search([tags...]))`.
 - Changed the `rule34Py.get_pool()` method to return a `Pool` object containing more complete information about a Pool.
 	- The Pool's post ids can be accessed via the `Pool.posts` attribute.
+- Moved the `:examples/` python recipes into tutorial documentation in the new sphinx documentation (`:docs/tutorials`). (#24)
 
 ### Deprecated
+
+- Deprecated support for python runtimes 3.5 to 3.8, as they are EOL. The minimum supported python version is now 3.9. (#27)
+
 ### Removed
+
+- Removed the deprecated `legacy.setup.py` file. Users are instructed to upgrade their setuptools installation and use `pyproject.toml` to build the project.
+- Removed the `debug.py` file. Users are instructed to use the `make check` Makefile target to run the project's test suite. (#27)
+
 ### Fixed
 ### Security
 

Makefile

@@ -1,74 +1,99 @@
+# Extract the project name and version from the pyproject.toml file.
+PROJECT = $(shell $(PYTHON3) scripts/read_pyproject.py project/name | tr 'A-Z' 'a-z')
+VERSION = $(shell $(PYTHON3) scripts/read_pyproject.py project/version)
 
-.DEFAULT_GOAL = all
-
-PROJECT = rule34py
-VERSION = $(shell git describe --tags)
-
-TWINE = twine
+# Binaries
 PYTHON3 ?= python3
+PYTEST = $(PYTHON3) -m pytest
 PYTHON_BUILD = $(PYTHON3) -m build
 RUFF = $(PYTHON3) -m ruff
-SPHINX_BUILD = $(PYTHON3) -m sphinx
-PYTEST = $(PYTHON3) -m pytest
+SPHINX = $(PYTHON3) -m sphinx
+TWINE = $(PYTHON3) -m twine
 
+# Source files
 builddir ?= build
 srcdir = rule34Py
 
+dist_files = \
+	$(srcdir) \
+	LICENSE \
+	NOTICE.md \
+	pyproject.toml \
+	README.md \
+
+sdist = $(builddir)/$(PROJECT)-$(VERSION).tar.gz  # The python sdist.
+wheels = $(builddir)/$(PROJECT)-$(VERSION)-py3-none-any.whl  # The python wheels.
+
 # Installation Directories
 prefix ?= /usr/local
 
 docdir ?= $(prefix)/share/doc/$(project)
 htmldir ?= $(docdir)/html
 
 
+.DEFAULT_GOAL = all
+
+
 # REAL TARGETS #
 ################
 
+$(wheels) &: $(dist_files)
+	$(PYTHON_BUILD) --outdir $(builddir) --wheel
+
+
+$(sdist) : $(dist_files)
+	$(PYTHON_BUILD) --outdir $(builddir) --sdist
+
 
 # PHONY TARGETS #
 #################
 
-all : html
-	$(PYTHON3) -m build --wheel --outdir $(builddir) --verbose
+# Build all binary targets necessary for installation.
+# Does not build documentation or source distributions.
+all : $(wheels)
 .PHONY : all
 
 
-check :
-	$(TWINE) check dist/*
-	PYTHONPATH=$(srcdir)/.. $(PYTEST) tests/unit/
+# Run pre-installation tests on the built artifacts.
+check : all
+	PYTHONPATH=$(builddir)/lib $(PYTEST) tests/unit/
 .PHONY : check
 
 
+# Remove all files created as a result of building the project.
 clean : mostlyclean
 	find ./ -depth -path '**/.pytest_cache*' -print -delete
 	find ./ -depth -path '**/__pycache__*' -print -delete
 	$(RUFF) clean
 .PHONY : clean
 
 
-dist :
-	$(PYTHON_BUILD) --sdist --wheel --outdir $(builddir)
+# Build the redistributable source archive.
+dist : $(sdist)
 .PHONY : dist
 
-publish : clean dist check
-	$(TWINE) upload dist/*
-.PHONY : publish
-
 
-distclean : clean
-.PHONY : distclean
+# Check and publish the python package index artifacts.
+publish : $(sdist) $(wheels)
+	$(TWINE) check $(^)
+	$(TWINE) upload $(^)
+.PHONY : publish
 
 
+# Build the project's HTML documentation.
 html :
-	$(SPHINX_BUILD) --builder html docs $(builddir)/html
+	$(SPHINX) --builder html docs $(builddir)/html
 .PHONY : html
 
 
+# Lint the project source for quality.
 lint :
 	$(RUFF) check $(srcdir)
 .PHONY : lint
 
 
+# Remove files created as a result of building the project, except those that
+# rarely need to be rebuilt.
 mostlyclean :
 	rm -rf $(builddir)
 	find ./ -depth -path '**/rule34Py.egg-info*' -print -delete