build: modernize to strict tier (uv_build, ruff, 3 type checkers, tox, split CI)

Packaging & config
- Replace setuptools/setup.py with the uv_build backend; pyproject.toml is now
  the single config home (build, project metadata, lint, typing, tests, coverage).
- Single-source the version: __about__.py reads importlib.metadata; expose
  python_utils.__version__. Static version lives in [project].
- PEP 735 dependency-groups (dev/test/docs/tox) alongside extras.

Lint, format & typing
- ruff lint + format (target py310); taplo for TOML; codespell.
- Strict typing with three checkers, all clean: mypy + basedpyright + pyrefly.
- Modernize annotations to PEP 604 (X | None, A | B); create TypeVars via typing.
- Keep python_utils.types.O / .U re-exported for backwards compatibility.

Tests, tox & CI
- Strict pytest (doctests, filterwarnings=error, xfail_strict); 100% branch coverage.
- tox matrix py3.10-3.14 + pypy3.10/3.11, per-checker and coverage envs (tox-uv).
- Split GitHub Actions: ci.yml / publish.yml (PyPI Trusted Publishing + attestations)
  / codeql.yml. lefthook git hooks replace any pre-commit config.

Docs
- README.rst -> README.md (absolute image URLs); furo + napoleon + myst-parser;
  .readthedocs.yaml with fail_on_warning.

Cleanup
- Delete setup.py/setup.cfg/MANIFEST.in, .coveragerc/pytest.ini/coverage.rc,
  codecov.yml, root requirements.txt, legacy main.yml. Explicit .gitignore.

The public API is preserved (only python_utils.__version__ is added); verified via a
programmatic API diff against the previous release.

BREAKING CHANGE: raise the Python floor from 3.9 to 3.10 (3.9 is EOL).

Author: wolph

.coveragerc

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [develop, master, main]
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          ['3.10', '3.11', '3.12', '3.13', '3.14', 'pypy3.10', 'pypy3.11']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      # tox-gh-actions maps the running interpreter to the matching env via the
+      # [gh-actions] table in tox.ini (PyPy keyed as `pypy-3.10` / `pypy-3.11`).
+      - run: uvx --with tox-uv --with tox-gh-actions tox
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage.*
+          include-hidden-files: true
+          if-no-files-found: error
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uvx --with tox-uv tox -e lint
+
+  type-check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        checker: [mypy, pyright, pyrefly]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uvx --with tox-uv tox -e ${{ matrix.checker }}
+
+  codespell:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uvx --with tox-uv tox -e codespell
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uvx --with tox-uv tox -e docs
+
+  coverage:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: coverage-*
+          merge-multiple: true
+      - run: uv run coverage combine
+      - run: uv run coverage report --show-missing --fail-under=100

.github/workflows/ci.yml

@@ -1,12 +1,11 @@
-name: "CodeQL"
+name: CodeQL
 
 on:
   push:
-    branches: [ "develop" ]
+    branches: [develop, master, main]
   pull_request:
-    branches: [ "develop" ]
   schedule:
-    - cron: "46 1 * * 3"
+    - cron: '46 1 * * 3'  # weekly, Wednesdays 01:46 UTC
 
 jobs:
   analyze:
@@ -16,26 +15,18 @@ jobs:
       actions: read
       contents: read
       security-events: write
-
     strategy:
       fail-fast: false
       matrix:
-        language: [ python ]
-
+        language: [python]
     steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-
+      - uses: actions/checkout@v4
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v3
         with:
           languages: ${{ matrix.language }}
           queries: +security-and-quality
-
-      - name: Autobuild
-        uses: github/codeql-action/autobuild@v2
-
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v3
         with:
-          category: "/language:${{ matrix.language }}"
+          category: '/language:${{ matrix.language }}'

.github/workflows/codeql.yml

@@ -0,0 +1,32 @@
+name: Publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC — PyPI Trusted Publishing + PEP 740 attestations
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true

.github/workflows/main.yml

@@ -1,7 +1,37 @@
-/build
-/dist
-/*.egg-info
-/docs/_build
-/cover
-/.eggs
-/.*
+# Byte-compiled / caches
+__pycache__/
+*.py[cod]
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtualenvs & tool caches
+.venv/
+.tox/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.dmypy.json
+
+# Local Python version pin (per-developer; not enforced on the matrix)
+.python-version
+
+# Coverage
+.coverage
+.coverage.*
+htmlcov/
+cover/
+
+# Docs
+docs/_build/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+
+# uv lockfile — not committed at this tier (library); commit at best-in-class.
+uv.lock

.github/workflows/publish.yml

@@ -1,35 +1,20 @@
-# Read the Docs configuration file for Sphinx projects
-# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+# Read the Docs configuration file for Sphinx projects.
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details.
 
-# Required
 version: 2
 
-# Set the OS, Python version and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.12"
-    # You can also specify other tool versions:
-    # nodejs: "20"
-    # rust: "1.70"
-    # golang: "1.20"
+    python: '3.13'
 
-# Build documentation in the "docs/" directory with Sphinx
 sphinx:
   configuration: docs/conf.py
-  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
-  # builder: "dirhtml"
-  # Fail on all warnings to avoid broken references
-  # fail_on_warning: true
+  fail_on_warning: true  # mirrors `sphinx-build -W` in CI/tox
 
-# Optionally build your docs in additional formats such as PDF and ePub
-formats:
-  - pdf
-  - epub
-
-# Optional but recommended, declare the Python requirements required
-# to build your documentation
-# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
 python:
   install:
-    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs