python-netgear-switch-library 0.1.post16__tar.gz → 0.1.post26__tar.gz

python_netgear_switch_library-0.1.post26/.github/apt-packaging.toml

@@ -0,0 +1,9 @@
+# How this repository is packaged, and why it differs from the defaults.
+# See https://github.com/mithro/apt-repo-action/blob/main/docs/packaging.md
+
+kind = "B"                  # our own code: debian/ at the root of main
+architectures = "all"       # pure Python
+suites = ["bookworm", "trixie", "forky", "sid"]
+
+[exceptions]
+PKG-SUITES = "fpgas.online uses it"

python_netgear_switch_library-0.1.post26/.github/workflows/deb.yml

@@ -0,0 +1,177 @@
+name: Debian packages
+
+# Rolling release: every push to main runs the gates (ruff, mypy --strict,
+# pytest with coverage >= 90, the documentation build), builds
+# python3-netgear-switch-library for each suite and republishes a signed apt
+# repository per suite on GitHub Pages
+# (https://mith.ro/python-netgear-switch-library/<suite>/). The package is
+# Architecture: all (pure Python), so one x86 build per suite serves every
+# architecture. A pull request runs the same gates and builds, and publishes
+# nothing. The version is git-derived (vX.Y at a tag, vX.Y.postN after it --
+# identical to the wheel's).
+#
+# publish-pypi.yml is triggered by this workflow completing on main, and
+# proceeds only when it succeeded. Renaming this workflow breaks that trigger.
+#
+# This follows mithro/apt-repo-action's docs/packaging.md; the differences
+# from its defaults are declared in .github/apt-packaging.toml.
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: deb-${{ github.ref }}
+  # A newer push to a pull request cancels the older build. On the default
+  # branch a running publish is never cancelled: the newest push waits for it,
+  # and replaces any older push still waiting (it contains that one's commits).
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    # The same gates as local development. A green run is what "mergeable"
+    # means.
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+        include:
+          # The documentation is built once, on the newest Python.
+          - python-version: "3.13"
+            docs: true
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # full history so hatch-vcs can derive the version
+
+      # The build generates debian/changelog: apt-repo-action's shared
+      # scripts/deb-version.py writes the build's entry, with the version
+      # derived from git. Committing a build's output would pin a stale
+      # version (and name a commit that may not exist), so it must not be
+      # tracked. (This job runs on the runner, not in a container, so git is
+      # already there and the checkout is a real clone.)
+      - name: debian/changelog is not committed
+        run: |
+          git rev-parse --is-inside-work-tree
+          if git ls-files --error-unmatch debian/changelog; then
+            echo "::error file=debian/changelog::debian/changelog is committed, but the build generates it: git rm it"
+            exit 1
+          fi
+
+      - name: Install net-snmp CLI (system dependency for the sync transport)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends snmp
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Install the matrix Python
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync all extras and the dev group
+        run: uv sync --all-extras --dev --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run ruff check
+
+      - name: Type-check (mypy --strict)
+        run: uv run mypy
+
+      - name: Tests + coverage gate (>= 90)
+        run: uv run pytest
+
+      # The published documentation generates its model/backend support tables
+      # from the library itself and links every file reference to the file, so
+      # a stale table or a renamed file is a build failure rather than a page
+      # that quietly misleads. Warnings are errors here exactly as they are on
+      # Read the Docs (see .readthedocs.yaml's fail_on_warning).
+      #
+      # Read the Docs' EXACT invocation, `-j auto` included. That flag matters:
+      # a parallel read needs every registered Sphinx domain to implement
+      # merge_domaindata, and sphinx-argparse's does not -- which broke the
+      # published build while a gate without `-j auto` stayed green. Run what
+      # production runs.
+      - name: Build the documentation (Read the Docs' command, warnings are errors)
+        if: matrix.docs
+        run: >
+          uv run python -m sphinx -T -W --keep-going -j auto -b html
+          -d docs/_build/doctrees -D language=en docs docs/_build/html
+
+      - name: Upload the built documentation
+        if: matrix.docs
+        uses: actions/upload-artifact@v7
+        with:
+          name: docs-html
+          path: docs/_build/html
+          retention-days: 7
+
+  build-deb:
+    name: build-deb (${{ matrix.suite }} ${{ matrix.arch }})
+    needs: test
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        suite: [bookworm, trixie, forky, sid]
+        arch: [all]
+    steps:
+      - name: Check out
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # full history + tags: the version is git describe's
+
+      # The shared build: debian:<suite>, build deps from debian/control, and
+      # the version from the shared deb-version.py (with ~deb<R>, and ~pr<P>
+      # on a pull request). Writes the .debs to built-debs/.
+      - name: Build
+        uses: mithro/apt-repo-action/build-deb@main
+        with:
+          suite: ${{ matrix.suite }}
+          arch: ${{ matrix.arch }}
+
+      # Install what was just built into a clean container of the same suite,
+      # dependencies from the Debian archive: the module imports with the
+      # package's version, the CLI runs, and it reads a mock switch's ports
+      # over HTTP (`ngsw serve`). No real switch is needed.
+      - name: Install test
+        run: |
+          docker run --rm \
+            -v "${PWD}/built-debs:/debs:ro" \
+            -v "${PWD}/packaging:/packaging:ro" \
+            docker.io/library/debian:${{ matrix.suite }} \
+            sh /packaging/install-test.sh
+
+      - name: Upload
+        uses: actions/upload-artifact@v7
+        with:
+          name: debs-${{ matrix.suite }}-${{ matrix.arch }}
+          path: built-debs/*.deb
+          retention-days: 14
+
+  publish-apt:
+    # Build and test pull requests, but never publish from one (or from any
+    # branch but main): that would overwrite the live repository with
+    # unreviewed packages.
+    if: github.event_name != 'pull_request' && github.ref_name == github.event.repository.default_branch
+    needs: build-deb
+    # Scoped to this job alone. A job calling a reusable workflow sets the
+    # maximum permissions available to it, so the elevated Pages scopes stay
+    # here rather than applying to the whole workflow.
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    uses: mithro/apt-repo-action/.github/workflows/publish-apt.yml@main
+    with:
+      suites: "bookworm trixie forky sid"
+      # Pure Python: one Architecture: all deb serves every architecture.
+      architectures: "all"
+      description: "Python library and CLI (ngsw) for Netgear switches"
+    secrets:
+      gpg-private-key: ${{ secrets.APT_GPG_PRIVATE_KEY }}

{python_netgear_switch_library-0.1.post16 → python_netgear_switch_library-0.1.post26}/.github/workflows/publish-pypi.yml

@@ -4,11 +4,12 @@ name: Publish to PyPI
 # hatch-vcs (see pyproject.toml): vX.Y at a tag, vX.Y.postN N commits later, so
 # each commit produces a new, unique version -- no manual bump.
 #
-# This workflow is gated on CI: it runs when the "CI" workflow (ruff, mypy,
-# pytest + coverage, docs) COMPLETES for a push to main, and the build job only
-# proceeds when that run SUCCEEDED. Before this gate, a red CI run and a PyPI
-# upload raced each other and broken commits were published (13ef042 shipped
-# with the docs job failing, a60bae6 with every test job failing). The
+# This workflow is gated on CI: it runs when the "Debian packages" workflow
+# (deb.yml: its test job runs ruff, mypy, pytest + coverage and the docs build,
+# then it builds and publishes the .debs) COMPLETES for main, and the build job
+# only proceeds when that run SUCCEEDED. Before this gate, a red CI run and a
+# PyPI upload raced each other and broken commits were published (13ef042
+# shipped with the docs job failing, a60bae6 with every test job failing). The
 # workflow_dispatch path stays for manual re-runs.
 #
 # Publishing uses PyPI Trusted Publishing (OIDC): there is no API token in the
@@ -16,7 +17,7 @@ name: Publish to PyPI
 # RELEASING.md).
 on:
   workflow_run:
-    workflows: [CI]
+    workflows: [Debian packages]
     types: [completed]
     branches: [main]
   workflow_dispatch:
@@ -24,10 +25,13 @@ on:
 jobs:
   build:
     # workflow_run fires on EVERY completion (failure and cancelled included);
-    # only a successful CI run is a release. Dependent jobs inherit the skip.
+    # only a successful run is a release. `branches: [main]` matches a pull
+    # request from a fork's own `main` too, so a pull request's run is
+    # excluded explicitly. Dependent jobs inherit the skip.
     if: >-
       github.event_name == 'workflow_dispatch' ||
-      github.event.workflow_run.conclusion == 'success'
+      (github.event.workflow_run.conclusion == 'success' &&
+       github.event.workflow_run.event != 'pull_request')
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5

{python_netgear_switch_library-0.1.post16 → python_netgear_switch_library-0.1.post26}/.gitignore

@@ -34,7 +34,12 @@ htmlcov/
 *.buildinfo
 *.changes
 /debian/.debhelper/
+# Written by each build (apt-repo-action's scripts/deb-version.py); never committed.
+/debian/changelog
 /debian/files
+/debian/*.substvars
+/debian/*.debhelper
+/debian/*.debhelper.log
 /debian/python3-netgear-switch-library/
 /debian/debhelper-build-stamp
 

{python_netgear_switch_library-0.1.post16 → python_netgear_switch_library-0.1.post26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-netgear-switch-library
-Version: 0.1.post16
+Version: 0.1.post26
 Summary: Python library and CLI to query and control Netgear switches over SNMP, NSDP and HTTP.
 Author-email: Tim Ansell <me@mith.ro>
 License: Apache-2.0
@@ -59,7 +59,30 @@ test your own tools against a mock), and generated
 Status: **early development.** See `docs/superpowers/specs/` for the design and
 `docs/superpowers/plans/` for the implementation plans.
 
-## Installation
+## Install
+
+### Debian (apt)
+
+Signed `.deb` packages are published as an apt repository per Debian suite:
+**bookworm**, **trixie**, **forky** and **sid** (`Architecture: all`, so every
+architecture, including Raspberry Pi OS). Put your suite's name in place of
+`trixie` below:
+
+```sh
+sudo install -d -m0755 /etc/apt/keyrings
+curl -fsSL https://mith.ro/python-netgear-switch-library/python-netgear-switch-library.gpg | sudo tee /etc/apt/keyrings/python-netgear-switch-library.gpg > /dev/null
+echo "deb [signed-by=/etc/apt/keyrings/python-netgear-switch-library.gpg] https://mith.ro/python-netgear-switch-library/trixie/ ./" \
+  | sudo tee /etc/apt/sources.list.d/python-netgear-switch-library.list
+sudo apt update
+sudo apt install python3-netgear-switch-library
+```
+
+The repository's signing key has the fingerprint
+`E870 0619 795F D931 79E2  600A 8F51 2272 5C6D 8239`
+(`gpg --show-keys /etc/apt/keyrings/python-netgear-switch-library.gpg`).
+
+This installs the `netgear_switch` library and the `ngsw` CLI, and pulls in the
+`snmp` net-snmp CLI tools automatically.
 
 ### pip / uv (PyPI)
 
@@ -76,37 +99,16 @@ transport shells out to the **net-snmp command-line tools**, a system package
 sudo apt install snmp   # provides snmpget/snmpbulkwalk/snmpset
 ```
 
-### Debian / Ubuntu (apt)
-
-Signed `.deb` packages for Debian **trixie** and **sid** are published to a
-GitHub Pages apt repository. Pick the line matching your suite:
-
-```sh
-sudo install -d -m0755 /etc/apt/keyrings
-curl -fsSL https://mith.ro/python-netgear-switch-library/python-netgear-switch-library.gpg \
-  | sudo tee /etc/apt/keyrings/python-netgear-switch-library.gpg > /dev/null
-
-# trixie:
-echo "deb [signed-by=/etc/apt/keyrings/python-netgear-switch-library.gpg] https://mith.ro/python-netgear-switch-library/trixie/ ./" \
-  | sudo tee /etc/apt/sources.list.d/python-netgear-switch-library.list
-# sid:
-echo "deb [signed-by=/etc/apt/keyrings/python-netgear-switch-library.gpg] https://mith.ro/python-netgear-switch-library/sid/ ./" \
-  | sudo tee /etc/apt/sources.list.d/python-netgear-switch-library.list
-
-sudo apt update
-sudo apt install python3-netgear-switch-library
-```
-
-This installs the `netgear_switch` library and the `ngsw` CLI, and pulls in the
-`snmp` net-snmp CLI tools automatically.
-
 Either way, once installed run `ngsw --help` to see available commands.
 
 ### Versioning
 
 This project is a **rolling release**: the version is derived from git
-(`0.0.postN` / `X.Y.postN`), and every merge to `main` publishes a new version
-to PyPI and the apt repo. There are no tags or manual version bumps.
+(`X.Y` at a `vX.Y` tag, `X.Y.postN` N commits after it), and every merge to
+`main` publishes a new version to PyPI and the apt repository, with no manual
+version bumps. The `.deb` adds the suite (`0.1.post23~deb12` on bookworm,
+`~deb13` trixie, `~deb14` forky, nothing on sid), so an upgrade to the next
+Debian release also upgrades the package. See `RELEASING.md`.
 
 ## Mock switch daemons (`ngsw serve`)
 

{python_netgear_switch_library-0.1.post16 → python_netgear_switch_library-0.1.post26}/README.md

@@ -24,7 +24,30 @@ test your own tools against a mock), and generated
 Status: **early development.** See `docs/superpowers/specs/` for the design and
 `docs/superpowers/plans/` for the implementation plans.
 
-## Installation
+## Install
+
+### Debian (apt)
+
+Signed `.deb` packages are published as an apt repository per Debian suite:
+**bookworm**, **trixie**, **forky** and **sid** (`Architecture: all`, so every
+architecture, including Raspberry Pi OS). Put your suite's name in place of
+`trixie` below:
+
+```sh
+sudo install -d -m0755 /etc/apt/keyrings
+curl -fsSL https://mith.ro/python-netgear-switch-library/python-netgear-switch-library.gpg | sudo tee /etc/apt/keyrings/python-netgear-switch-library.gpg > /dev/null
+echo "deb [signed-by=/etc/apt/keyrings/python-netgear-switch-library.gpg] https://mith.ro/python-netgear-switch-library/trixie/ ./" \
+  | sudo tee /etc/apt/sources.list.d/python-netgear-switch-library.list
+sudo apt update
+sudo apt install python3-netgear-switch-library
+```
+
+The repository's signing key has the fingerprint
+`E870 0619 795F D931 79E2  600A 8F51 2272 5C6D 8239`
+(`gpg --show-keys /etc/apt/keyrings/python-netgear-switch-library.gpg`).
+
+This installs the `netgear_switch` library and the `ngsw` CLI, and pulls in the
+`snmp` net-snmp CLI tools automatically.
 
 ### pip / uv (PyPI)
 
@@ -41,37 +64,16 @@ transport shells out to the **net-snmp command-line tools**, a system package
 sudo apt install snmp   # provides snmpget/snmpbulkwalk/snmpset
 ```
 
-### Debian / Ubuntu (apt)
-
-Signed `.deb` packages for Debian **trixie** and **sid** are published to a
-GitHub Pages apt repository. Pick the line matching your suite:
-
-```sh
-sudo install -d -m0755 /etc/apt/keyrings
-curl -fsSL https://mith.ro/python-netgear-switch-library/python-netgear-switch-library.gpg \
-  | sudo tee /etc/apt/keyrings/python-netgear-switch-library.gpg > /dev/null
-
-# trixie:
-echo "deb [signed-by=/etc/apt/keyrings/python-netgear-switch-library.gpg] https://mith.ro/python-netgear-switch-library/trixie/ ./" \
-  | sudo tee /etc/apt/sources.list.d/python-netgear-switch-library.list
-# sid:
-echo "deb [signed-by=/etc/apt/keyrings/python-netgear-switch-library.gpg] https://mith.ro/python-netgear-switch-library/sid/ ./" \
-  | sudo tee /etc/apt/sources.list.d/python-netgear-switch-library.list
-
-sudo apt update
-sudo apt install python3-netgear-switch-library
-```
-
-This installs the `netgear_switch` library and the `ngsw` CLI, and pulls in the
-`snmp` net-snmp CLI tools automatically.
-
 Either way, once installed run `ngsw --help` to see available commands.
 
 ### Versioning
 
 This project is a **rolling release**: the version is derived from git
-(`0.0.postN` / `X.Y.postN`), and every merge to `main` publishes a new version
-to PyPI and the apt repo. There are no tags or manual version bumps.
+(`X.Y` at a `vX.Y` tag, `X.Y.postN` N commits after it), and every merge to
+`main` publishes a new version to PyPI and the apt repository, with no manual
+version bumps. The `.deb` adds the suite (`0.1.post23~deb12` on bookworm,
+`~deb13` trixie, `~deb14` forky, nothing on sid), so an upgrade to the next
+Debian release also upgrades the package. See `RELEASING.md`.
 
 ## Mock switch daemons (`ngsw serve`)
 

{python_netgear_switch_library-0.1.post16 → python_netgear_switch_library-0.1.post26}/RELEASING.md

@@ -2,18 +2,26 @@
 
 This project is a **rolling release**. There are no manual version bumps: the
 version is derived from `git describe` (`hatch-vcs` for the wheel,
-`packaging/deb-version.py` for the `.deb`) — `X.Y` at a `vX.Y` tag,
-`X.Y.postN` N commits after it — and **every green merge to `main` publishes
-new packages** automatically:
-
-- `.github/workflows/ci.yml` — runs the gates (ruff, mypy --strict, pytest with
-  coverage >= 90, docs build) on every push and PR. A green run is what
-  "mergeable" means, and it is what triggers the two release workflows.
+[apt-repo-action](https://github.com/mithro/apt-repo-action)'s shared
+`scripts/deb-version.py` for the `.deb`) — `X.Y` at a `vX.Y` tag,
+`X.Y.postN` N commits after it, and for the `.deb` the suite's `~deb<R>`
+(`~deb12` bookworm, `~deb13` trixie, `~deb14` forky, none on sid) — and
+**every green merge to `main` publishes new packages** automatically:
+
+- `.github/workflows/deb.yml` ("Debian packages") — its `test` job runs the
+  gates (ruff, mypy --strict, pytest with coverage >= 90, docs build) on every
+  push and PR; a green run is what "mergeable" means. Then `build-deb` builds
+  the `.deb` for bookworm, trixie, forky and sid with apt-repo-action's shared
+  `build-deb` action and install-tests it (`packaging/install-test.sh`), and,
+  on `main` only, `publish-apt` republishes the signed apt repo on GitHub
+  Pages. A pull request builds preview packages (`~pr<N>`, sorting below
+  `main`'s) as workflow artifacts and publishes nothing.
 - `.github/workflows/publish-pypi.yml` — builds and uploads the wheel + sdist to
-  PyPI when CI **succeeds** on `main` (`workflow_run`; a failed or cancelled CI
-  run publishes nothing, and the checkout is pinned to the SHA CI validated).
-- `.github/workflows/deb.yml` — builds `.deb`s for trixie + sid and republishes
-  the signed apt repo on GitHub Pages, gated the same way.
+  PyPI when "Debian packages" **succeeds** on `main` (`workflow_run`; a failed
+  or cancelled run publishes nothing, and the checkout is pinned to the SHA it
+  validated).
+
+`debian/changelog` is not committed: the build writes it, with the version.
 
 Merges to `main` MUST use `--no-ff` merge commits so history stays linear per PR.
 
@@ -82,21 +90,15 @@ re-runs idempotent.
    gpg --armor --export-secret-keys me@mith.ro | pbcopy   # or xclip / paste manually
    ```
 
-   The workflow imports this key and exports the matching public key to
-   `netgear-switch.gpg` at the apt repo root, which users install into
-   `/etc/apt/keyrings/`.
-
-3. **Until `APT_GPG_PRIVATE_KEY` is set, the apt repo is published UNSIGNED and
-   is unusable by design.** The `deb.yml` "Sign repo" step is gated on
-   `if: env.GPG_PRIVATE_KEY != ''`, so with no secret it is skipped entirely:
-   no `Release.gpg`, no `InRelease`, and no `netgear-switch.gpg` public key are
-   published. This is not a bug — it is intentional: the README and
-   `packaging/apt-index.html` both tell users to configure their `sources.list`
-   entry with `[signed-by=/etc/apt/keyrings/python-netgear-switch-library.gpg]` (never
-   `[trusted=yes]`), so `apt update` will fail closed (unable to fetch the
-   missing/invalid signature) rather than silently accepting an unsigned repo.
-   Setting this secret is therefore **required** before the apt repo works at
-   all, not just before it works securely.
+   `mithro/apt-repo-action`'s publish workflow imports this key and publishes
+   the matching public key as `python-netgear-switch-library.gpg` (binary) and
+   `.asc` (armoured) at the apt repo root; users install the `.gpg` into
+   `/etc/apt/keyrings/` (see the repo's index page).
+
+3. **Until `APT_GPG_PRIVATE_KEY` is set, the publish job fails.**
+   `mithro/apt-repo-action` refuses to publish an unsigned repository, so
+   nothing is deployed rather than something consumers would have to trust
+   with `[trusted=yes]`.
 
 ### 3. GitHub Pages
 
@@ -113,7 +115,7 @@ re-runs idempotent.
   `X.Y.postN` version (matches `git describe --tags` on `main`, e.g. `v0.1-3-g…`
   → `0.1.post3`).
 - apt: `sudo apt update && apt-cache policy python3-netgear-switch-library` on a
-  Debian trixie/sid box configured per the README. Before the GPG key is set
+  Debian bookworm/trixie/forky/sid box configured per the README. Before the GPG key is set
   (see step 2 above), expect `apt update` to fail with a signature error for
   this repo — that confirms the fail-closed behavior is working, not that
   something is broken.

{python_netgear_switch_library-0.1.post16 → python_netgear_switch_library-0.1.post26}/debian/rules

@@ -3,11 +3,14 @@
 # Build the netgear_switch Python package with dh-python/pybuild straight from
 # pyproject.toml (hatchling backend). The upstream version is normally derived
 # from git by hatch-vcs, but during the .deb build there may be no VCS context in
-# the unpacked source, so we pin it to the changelog version (set by
-# packaging/deb-version.py) through SETUPTOOLS_SCM_PRETEND_VERSION. dpkg source
-# format is native, so the changelog version has no Debian revision to strip.
+# the unpacked source, so we pin it to the changelog version (written by the
+# build) through SETUPTOOLS_SCM_PRETEND_VERSION. dpkg source format is native,
+# so the changelog version has no Debian revision to strip. It can carry the
+# Debian-only ~deb<R> suite and ~pr<P> preview suffixes (0.1.post20~deb12~pr15),
+# which aren't PEP 440: everything from the first ~ is dropped, leaving the
+# same X.Y[.postN] the wheel on PyPI has.
 export PYBUILD_NAME = netgear_switch
-export SETUPTOOLS_SCM_PRETEND_VERSION = $(shell dpkg-parsechangelog -SVersion)
+export SETUPTOOLS_SCM_PRETEND_VERSION = $(firstword $(subst ~, ,$(shell dpkg-parsechangelog -SVersion)))
 
 %:
 	dh $@ --with python3 --buildsystem=pybuild

{python_netgear_switch_library-0.1.post16 → python_netgear_switch_library-0.1.post26}/docs/conf.py

@@ -228,9 +228,10 @@ def _force_serial_build(app: Sphinx) -> None:
     this project, well inside any build timeout. Remove this once
     sphinx-argparse implements ``merge_domaindata``.
 
-    This is why the CI documentation job passes ``-j auto`` too (see
-    ``.github/workflows/ci.yml``): the gate must run the command Read the Docs
-    runs, or a failure like this one reaches production with CI still green.
+    This is why the CI documentation build passes ``-j auto`` too (see the
+    ``test`` job in ``.github/workflows/deb.yml``): the gate must run the
+    command Read the Docs runs, or a failure like this one reaches production
+    with CI still green.
     """
     app.parallel = 1
 

{python_netgear_switch_library-0.1.post16 → python_netgear_switch_library-0.1.post26}/docs/development.rst

@@ -123,7 +123,8 @@ repository, with the version derived from git — no manual version bumps. See
 Continuous integration
 ----------------------
 
-``.github/workflows/ci.yml`` runs the test suite, lint, type-check and the
-documentation build across supported Python versions;
-``.github/workflows/publish-pypi.yml`` and ``.github/workflows/deb.yml`` handle
-publication.
+``.github/workflows/deb.yml`` ("Debian packages") runs the test suite, lint,
+type-check and the documentation build across supported Python versions in its
+``test`` job, then builds the ``.deb`` for every suite and, from ``main``,
+publishes the apt repository. ``.github/workflows/publish-pypi.yml`` publishes
+to PyPI once that workflow has succeeded on ``main``.

{python_netgear_switch_library-0.1.post16 → python_netgear_switch_library-0.1.post26}/docs/guide/installation.rst

@@ -76,25 +76,23 @@ from the ``[async]`` extra.
 Debian and Ubuntu
 -----------------
 
-Signed ``.deb`` packages for Debian **trixie** and **sid** are published to a
-GitHub Pages apt repository:
+Signed ``.deb`` packages are published as an apt repository per Debian suite:
+**bookworm**, **trixie**, **forky** and **sid** (``Architecture: all``, so every
+architecture, including Raspberry Pi OS). Put your suite's name in place of
+``trixie`` below:
 
 .. code-block:: sh
 
    sudo install -d -m0755 /etc/apt/keyrings
-   curl -fsSL https://mith.ro/python-netgear-switch-library/python-netgear-switch-library.gpg \
-     | sudo tee /etc/apt/keyrings/python-netgear-switch-library.gpg > /dev/null
-
-   # trixie:
+   curl -fsSL https://mith.ro/python-netgear-switch-library/python-netgear-switch-library.gpg | sudo tee /etc/apt/keyrings/python-netgear-switch-library.gpg > /dev/null
    echo "deb [signed-by=/etc/apt/keyrings/python-netgear-switch-library.gpg] https://mith.ro/python-netgear-switch-library/trixie/ ./" \
      | sudo tee /etc/apt/sources.list.d/python-netgear-switch-library.list
-   # sid:
-   echo "deb [signed-by=/etc/apt/keyrings/python-netgear-switch-library.gpg] https://mith.ro/python-netgear-switch-library/sid/ ./" \
-     | sudo tee /etc/apt/sources.list.d/python-netgear-switch-library.list
-
    sudo apt update
    sudo apt install python3-netgear-switch-library
 
+The repository's signing key has the fingerprint
+``E870 0619 795F D931 79E2  600A 8F51 2272 5C6D 8239``.
+
 This installs the ``netgear_switch`` library and the ``ngsw`` CLI, and pulls in
 the net-snmp tools automatically. The packaging lives in ``debian/`` and
 ``packaging/``.
@@ -104,9 +102,10 @@ Versioning
 
 A **rolling release**. The version is derived from ``git describe`` by
 ``hatch-vcs``: ``X.Y`` at a ``vX.Y`` tag, ``X.Y.postN`` N commits after it
-(``0.1``, ``0.1.post1``, …). Every merge to ``main`` whose CI run is green
-publishes to PyPI and to the apt repository — a red run publishes nothing. No
-manual version bumps — see ``RELEASING.md``.
+(``0.1``, ``0.1.post1``, …). The ``.deb`` adds the suite: ``~deb12`` on
+bookworm, ``~deb13`` trixie, ``~deb14`` forky and nothing on sid. Every merge
+to ``main`` whose tests pass publishes to PyPI and to the apt repository — a
+red run publishes nothing. No manual version bumps — see ``RELEASING.md``.
 
 .. note::
 

python_netgear_switch_library-0.1.post26/packaging/install-test.sh

@@ -0,0 +1,76 @@
+#!/bin/sh
+# Install the built .debs into a clean debian:<suite> container, with their
+# dependencies from the Debian archive, and exercise them without a switch.
+# Run by .github/workflows/deb.yml's "Install test" step, and locally, as:
+#   docker run --rm -v "$PWD/built-debs:/debs:ro" -v "$PWD/packaging:/packaging:ro" \
+#     debian:trixie sh /packaging/install-test.sh
+set -eux
+
+export DEBIAN_FRONTEND=noninteractive
+apt-get update
+# Recommends too, as a plain `apt install` would: python3-httpx (the HTTP
+# backend), and python3-mcp where the suite has it.
+apt-get install -y /debs/*.deb
+
+# The Python version is the package's without the Debian-only ~deb<R> and
+# ~pr<P> suffixes (debian/rules strips them), and must be exactly that: the
+# wheel on PyPI carries the same X.Y[.postN].
+deb_version=$(dpkg-query -W -f '${Version}' python3-netgear-switch-library)
+py_version=${deb_version%%~*}
+python3 - "$py_version" <<'EOF'
+import sys
+from importlib.metadata import version
+
+import netgear_switch
+import netgear_switch.cli.main
+import netgear_switch.sync_api
+
+want = sys.argv[1]
+assert netgear_switch.__version__ == want, (netgear_switch.__version__, want)
+assert version("python-netgear-switch-library") == want
+assert netgear_switch.__file__.startswith("/usr/lib/python3/dist-packages/"), netgear_switch.__file__
+print("netgear_switch", netgear_switch.__version__, "from", netgear_switch.__file__)
+EOF
+
+# The CLI entry point, and a command that needs no switch: the model registry.
+ngsw --help
+models=$(ngsw models)
+echo "$models"
+echo "$models" | grep -q '^gsm7252ps '
+echo "$models" | grep -q '^gs305ep '
+
+# The synchronous SNMP transport shells out to net-snmp: a hard dependency.
+command -v snmpget snmpbulkwalk snmpset
+
+# The MCP server entry point is installed unconditionally; it runs when the
+# suite has python3-mcp (a Recommends; sid only, so far).
+command -v ngsw-mcp
+if python3 -c 'import importlib.util, sys; sys.exit(importlib.util.find_spec("mcp") is None)'; then
+  ngsw-mcp --help
+fi
+
+# A real round trip, with no switch: serve the in-package mock GS305EP (a Plus
+# switch, driven over its HTTP web UI) on port 80, where ngsw looks for it,
+# and read its ports back through the HTTP backend (python3-httpx, a
+# Recommends every suite has).
+cd "$(mktemp -d)"
+ngsw serve --model gs305ep --http-port 80 > serve.log 2>&1 &
+serve=$!
+tries=0
+until grep -q '^serving ' serve.log; do
+  tries=$((tries + 1))
+  if [ "$tries" -gt 60 ] || ! kill -0 "$serve"; then
+    cat serve.log
+    exit 1
+  fi
+  sleep 0.5
+done
+cat serve.log
+ports=$(ngsw --host 127.0.0.1 --model gs305ep --http-password password --backend http ports)
+echo "$ports"
+kill "$serve"
+# The mock's seeded state: five ports, port 1 up at 1000 Mb/s.
+echo "$ports" | grep -Eq '^1 +Port 1 +up +enabled +1000 '
+test "$(echo "$ports" | grep -Ec '^[1-5] +Port ')" -eq 5
+
+echo "install test passed: python3-netgear-switch-library $deb_version"