python-netgear-switch-library 0.0.post294__tar.gz → 0.0.post321__tar.gz

{python_netgear_switch_library-0.0.post294 → python_netgear_switch_library-0.0.post321}/.github/workflows/ci.yml

@@ -46,3 +46,31 @@ jobs:
 
       - name: Tests + coverage gate (>= 90)
         run: uv run pytest
+
+  docs:
+    # 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).
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0  # full history so hatch-vcs can derive the version
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Sync the docs extra
+        run: uv sync --extra docs
+
+      - name: Build the documentation (warnings are errors)
+        run: uv run sphinx-build -W --keep-going -b html docs docs/_build/html
+
+      - name: Upload the built documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html
+          retention-days: 7

{python_netgear_switch_library-0.0.post294 → python_netgear_switch_library-0.0.post321}/.gitignore

@@ -23,6 +23,10 @@ htmlcov/
 # hatch-vcs writes this at build/editable-install time; it is derived from git.
 /src/netgear_switch/_version.py
 
+# Sphinx build output (docs/Makefile's BUILDDIR). Read the Docs builds from a
+# clean checkout; a local `make -C docs html` writes here.
+/docs/_build/
+
 # Debian build byproducts (dpkg-buildpackage writes to the parent dir; local
 # builds may drop these in-tree).
 /built-debs/

python_netgear_switch_library-0.0.post321/.readthedocs.yaml

@@ -0,0 +1,32 @@
+# Read the Docs build configuration.
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_checkout:
+      # This project's version is derived from git by hatch-vcs (see
+      # pyproject.toml's [tool.hatch.version]). Read the Docs makes a SHALLOW
+      # clone with no tags, which makes that derivation fail the build. Fetch
+      # the full history + tags so the version the docs display is the real
+      # one. `|| true` keeps a build working if the clone is already complete.
+      - git fetch --unshallow || true
+      - git fetch --tags || true
+
+sphinx:
+  configuration: docs/conf.py
+  # A warning here means a broken cross-reference, a missing document, or a
+  # documented file path that no longer exists (see docs/_ext/filelinks.py).
+  # All three are documentation bugs, so they fail the build rather than
+  # shipping a page that quietly lies.
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

python_netgear_switch_library-0.0.post321/CLAUDE.md

@@ -0,0 +1,203 @@
+# python-netgear-switch-library — working agreement
+
+These are **non-negotiable design principles** for this library. They override
+convenience, they override "it works on my switch", and they override any
+temptation to declare something unsupported. Each one is written here because it
+was violated in practice — the concrete example is included so the rule is not
+abstract.
+
+Anything that contradicts a principle below needs an explicit, recorded decision
+from the repository owner. "I couldn't get it working" is not such a decision.
+
+---
+
+## 1. Fail fast and loud. Never paper over a problem.
+
+If an operation cannot be performed as asked, **raise** — immediately, with the
+detail needed to debug it (which backend, which OID/URL/command, what the device
+answered). Never substitute a different behaviour to make a call appear to
+succeed.
+
+**Specifically forbidden: switching protocol/backend mid-operation.** A caller
+who asks for SNMP gets SNMP or an error. Silently retrying over HTTP is not
+robustness, it is data loss disguised as success.
+
+*Why this exists:* `SyncSwitch._read`/`_write` used to loop over
+`SNMP > NSDP > HTTP` and silently return the next backend's answer when one
+raised `UnsupportedCapabilityError`. That fallback concealed a real defect for
+months — `HttpReader.get_vlans()` returns no untagged ports at all on the managed
+switches, and nobody saw it because SNMP quietly answered in its place. Worse,
+every past "HTTP verified" claim became untrustworthy, because the HTTP path may
+never have run. On a write it is worse still: an operator who deliberately
+restricts SNMP write access could have their change pushed over another protocol
+without being told.
+
+Corollaries:
+- Verification must drive one backend **directly**. A cross-backend comparison is
+  only evidence if each backend answered on its own merits.
+- A degraded or partial result is a failure. Do not return `[]`, `None` or a
+  silently-truncated value where the caller asked a question you could not answer.
+- Errors must name the thing that failed. `commitFailed` on which OID, with which
+  value, for which model.
+
+## 2. Backends must have feature parity.
+
+Every backend a model supports (SNMP / NSDP / HTTP / CLI) must offer the **same
+functionality**. The point of having several is that the *caller* chooses — for
+example when SNMP writes are locked down, or when the web UI is the only thing
+reachable through a firewall. That choice only exists if the backends are
+equivalent.
+
+A backend missing an operation is a **missing implementation**, to be built. It
+is not a device limitation until proven otherwise (see principle 4). Only the
+repository owner may exempt a specific backend/operation, and the exemption must
+be recorded in the code with the reason.
+
+*Why this exists:* `vlan_membership_path=None  # vlanStatus carries the egress
+list inline` was left on every managed switch, so HTTP could neither report
+tagged/untagged membership nor write membership at all — while the same file
+already had the working `/iss/specific/vlanMembership.html` path for a sibling
+model. Likewise there was no CLI write backend whatsoever, even though the
+FASTPATH command sequences work (they were driven by hand on an M4300 to prove
+it).
+
+## 3. Every switch model, not just the one in front of you.
+
+A feature is not done when it works on one switch. It is done when it works on
+**every** registered model, verified against every reachable one. All models have
+feature parity unless the repository owner explicitly exempts one, with the reason
+recorded in the registry entry.
+
+When you implement or fix something, enumerate the models it applies to and check
+each. Firmware differs between SKUs of the *same* family — do not extrapolate.
+
+*Why this exists:* the M4300-16X was marked `snmp_vlan_write="fastpath_switchport"`
+purely by inference from the M4300-24X ("same firmware family"). It runs different
+firmware (12.0.19.15 vs 12.0.13.8) and **accepts** Q-BRIDGE writes the -24X
+refuses, so the inference could not be trusted even though it happened to reach the
+right answer.
+
+Measuring it (2026-07-30) replaced both the inference *and* the counter-example
+with the actual rule: `dot1qVlanStaticEgressPorts` is writable only while **no
+interface on the switch is in access mode** — switch-wide, not per-VLAN, and the
+same on both firmwares. An A/B/A on -16X port 1/0/1, issuing byte-identical writes
+while flipping only that one port's mode, gave general→noError, access→**commitFailed**,
+general→noError, trunk→noError, access→**commitFailed**, general→noError. The -24X
+looks different only because 21 of its 24 ports are access-mode, so the column is
+never writable there. And because an UNTAGGED membership write is *expressed as*
+access mode, the qbridge dialect would disable itself on first use — the -16X
+belongs on the switchport dialect after all, now for a reason instead of a guess.
+The lesson stands unchanged: the extrapolation was invalid, and only measurement
+told us what the devices actually do.
+
+## 4. A failure is something you did wrong.
+
+Not flaky hardware. Not "the switch is slow". Not a timeout that will pass. Before
+you even consider blaming the device, answer all of these:
+
+- **Have you actually debugged it,** or just observed it fail? What does the device
+  say when you ask it directly (its CLI, its web UI, its own config dump)?
+- **Is another setting required first?** Some writes are gated by other state.
+- **Are you sending the wrong details?** Wrong community, username, password,
+  port, value type, encoding, field width, or **ordering** of operations.
+- **Did you try every mechanism the device exposes,** or only the first one you
+  thought of?
+
+Only after that, and only with captured device output quoted as proof, may a
+limitation be recorded — and it must name the firmware version it applies to.
+
+*Why this exists,* three times over in one session:
+- "The S3300's SNMP agent is dead / timing out." It was not. The switch has no
+  `private` community (`show snmpcommunity` lists `pib` and `public`, both
+  Read/Write). An agent **silently drops** an unauthorized request, so a wrong
+  write community looks exactly like an unreachable host. Reads worked the whole
+  time. Wrong credential, blamed on hardware.
+- "The M4300 refuses VLAN writes." It does not. One OID was tried; the switch's
+  own vendor switchport table accepts membership writes. Never enumerating what
+  the device published, blamed on firmware.
+- "The S3300 forces untagged membership." It does not. Setting the egress bit
+  auto-untags the port, and that side effect beats an untagged varbind in the
+  **same PDU**; two PDUs, egress first, work perfectly. Wrong ordering, blamed on
+  firmware.
+
+## 5. The fake must behave like the real hardware. When it differs, fix the fake.
+
+The virtual switch (`src/netgear_switch/virtual/`) exists so this library can be
+tested honestly without hardware. That only works if it is a **faithful** model of
+the real devices — including their refusals, their quirks and their ordering
+requirements, not just their happy paths.
+
+Therefore:
+- When live hardware behaves differently from the mock, **the mock is wrong** and
+  must be corrected to match the device. Never adjust a test's expectation to
+  match a mock you already know is unfaithful, and never "fix" a divergence by
+  making the real-hardware path lenient.
+- The mock must reproduce **rejections** as faithfully as successes: the right SMI
+  error-status (`commitFailed` vs `notWritable` vs `wrongValue`), the same
+  preconditions, the same side effects, the same ordering sensitivity.
+- The mock must be an **independent** source of truth. If it derives a value using
+  the same formula as the code under test, it can only ever agree with that code
+  and proves nothing. Seed measured device values instead of computing them.
+- Every behaviour learned from hardware gets encoded in the mock **and** pinned by
+  a test in the same change, with a comment naming the host and firmware it was
+  observed on. A finding that is not in the mock will be regressed later.
+
+*Why this exists:* the VLAN PortList-width defect went unnoticed because the mock
+emitted the bitmap using `vlan_bitmap_width(model)` — the exact same wrong formula
+the buggy writer used — so mock and code agreed with each other while both
+disagreed with every real switch (whose widths are 79 / 131 / 45 bytes, none of
+them derivable from the port count). The round trip was green and meaningless.
+
+---
+
+## Practical rules that follow
+
+- **Ground everything in real devices.** Fixtures come from captured
+  traffic/pages, never from imagination or from a MIB's ideal semantics.
+- **Diff the device, don't guess the MIB.** To learn how something is configured:
+  capture a full walk to a file, change the setting through the switch's own
+  UI/CLI, walk again, diff. That is how the vendor switchport table was found with
+  no MIB file available.
+- **Never leave a device changed.** Record the exact prior state, use throwaway
+  VLAN ids and ports that are link-down and undescribed, restore, and prove the
+  restore by re-reading. Never persist config (`write memory`) during testing.
+- **Say what you actually verified.** Distinguish "live-verified on host X,
+  firmware Y" from "assumed". Never round an inference up to a fact.
+
+---
+
+## If you are a dispatched subagent
+
+The five principles above bind you exactly as they bind the main session. In
+particular:
+
+- **Never declare an operation unsupported to finish your task.** If you cannot
+  implement something, say so plainly in your report — naming the model, backend
+  and operation — and leave no `raise UnsupportedCapabilityError` behind that
+  lacks captured device output as proof. An honest "not done, here's why" is
+  wanted; a false "the hardware can't" is not.
+- **Implement across all backends and all models,** or state precisely which
+  combinations remain. Do not extrapolate one SKU's behaviour to its siblings.
+- **Verify by driving one backend directly**, never through a facade that might
+  substitute another — otherwise your PASS may be a different protocol answering.
+- **Encode what you learn from hardware into the virtual switch, plus a test**,
+  naming the host and firmware version in a comment. A finding that lives only in
+  your report will be regressed by the next change.
+
+### Live-hardware rules (absolute)
+
+- Credentials come from `sudo -n .venv/bin/gdoc2netcfg password --type password -q
+  <host>` run from `/opt/gdoc2netcfg`. **Never print a credential.**
+- Use throwaway VLAN ids in the 4001-4008 range, coordinated so concurrent agents
+  do not collide.
+- Touch only a port that is **link-down** AND whose description is empty or
+  `'empty'`. Never a described production port.
+- **Record the exact prior state, restore it, and prove the restore by
+  re-reading.** Never `write memory` / save configuration.
+
+### Running things on this machine
+
+It OOMs easily: `PYTHONPATH=src .venv/bin/python -m pytest <specific file> -q
+--no-cov`, one pytest process at a time, never the full suite. `uv run ruff check
+src/ tests/` and `uv run mypy` must both be clean. Never use `2>/dev/null` (a hook
+blocks it). Prefer Python over involved shell.

{python_netgear_switch_library-0.0.post294 → python_netgear_switch_library-0.0.post321}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-netgear-switch-library
-Version: 0.0.post294
+Version: 0.0.post321
 Summary: Python library and CLI to query and control Netgear switches over SNMP, NSDP and HTTP.
 Author-email: Tim Ansell <me@mith.ro>
 License-Expression: Apache-2.0
@@ -9,6 +9,16 @@ Requires-Python: >=3.11
 Requires-Dist: cryptography>=41
 Provides-Extra: async
 Requires-Dist: pysnmp>=7.0; extra == 'async'
+Provides-Extra: docs
+Requires-Dist: furo>=2024.8.6; extra == 'docs'
+Requires-Dist: httpx>=0.27; extra == 'docs'
+Requires-Dist: mcp>=1.2; extra == 'docs'
+Requires-Dist: paramiko<3,>=2.12; extra == 'docs'
+Requires-Dist: pyserial>=3.5; extra == 'docs'
+Requires-Dist: pysnmp>=7.0; extra == 'docs'
+Requires-Dist: sphinx-argparse>=0.5; extra == 'docs'
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == 'docs'
+Requires-Dist: sphinx>=8.1; extra == 'docs'
 Provides-Extra: http
 Requires-Dist: httpx>=0.27; extra == 'http'
 Provides-Extra: mcp
@@ -27,6 +37,11 @@ Description-Content-Type: text/markdown
 Query and control all your Netgear switches — SNMP (managed), NSDP and HTTP
 web-UI (Plus) — behind one model-driven Python API and the `ngsw` CLI.
 
+**Documentation: <https://python-netgear-switch-library.readthedocs.io/>** — API
+reference, the complete `ngsw` CLI reference, the virtual-switch guide (how to
+test your own tools against a mock), and generated
+[model × protocol and model × functionality support tables](https://python-netgear-switch-library.readthedocs.io/en/latest/models/support.html).
+
 Status: **early development.** See `docs/superpowers/specs/` for the design and
 `docs/superpowers/plans/` for the implementation plans.
 
@@ -128,12 +143,24 @@ Options:
   listener, these are only allowed when serving exactly one model; otherwise
   leave them unset and read the printed ephemeral ports.
 
+Full details, including worked examples of testing an external tool against a
+mock, are in the [virtual switch
+guide](https://python-netgear-switch-library.readthedocs.io/en/latest/fake/).
+
 ## Development
 
 ```sh
 uv sync --all-extras
 uv run pytest
 uv run ruff check
+uv run mypy
+```
+
+Build the documentation (warnings are errors, as on Read the Docs):
+
+```sh
+uv sync --extra docs
+make -C docs html
 ```
 
 ## License

{python_netgear_switch_library-0.0.post294 → python_netgear_switch_library-0.0.post321}/README.md

@@ -3,6 +3,11 @@
 Query and control all your Netgear switches — SNMP (managed), NSDP and HTTP
 web-UI (Plus) — behind one model-driven Python API and the `ngsw` CLI.
 
+**Documentation: <https://python-netgear-switch-library.readthedocs.io/>** — API
+reference, the complete `ngsw` CLI reference, the virtual-switch guide (how to
+test your own tools against a mock), and generated
+[model × protocol and model × functionality support tables](https://python-netgear-switch-library.readthedocs.io/en/latest/models/support.html).
+
 Status: **early development.** See `docs/superpowers/specs/` for the design and
 `docs/superpowers/plans/` for the implementation plans.
 
@@ -104,12 +109,24 @@ Options:
   listener, these are only allowed when serving exactly one model; otherwise
   leave them unset and read the printed ephemeral ports.
 
+Full details, including worked examples of testing an external tool against a
+mock, are in the [virtual switch
+guide](https://python-netgear-switch-library.readthedocs.io/en/latest/fake/).
+
 ## Development
 
 ```sh
 uv sync --all-extras
 uv run pytest
 uv run ruff check
+uv run mypy
+```
+
+Build the documentation (warnings are errors, as on Read the Docs):
+
+```sh
+uv sync --extra docs
+make -C docs html
 ```
 
 ## License

python_netgear_switch_library-0.0.post321/docs/Makefile

@@ -0,0 +1,30 @@
+# Documentation build. `make html` mirrors what Read the Docs runs
+# (see .readthedocs.yaml), including warnings-as-errors.
+#
+# `make offline` additionally skips the intersphinx inventory fetch, for
+# building without network access.
+
+SPHINXOPTS    ?= -W --keep-going
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+.PHONY: help html offline linkcheck clean Makefile
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+html:
+	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+offline:
+	@NGSW_DOCS_OFFLINE=1 $(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+linkcheck:
+	@$(SPHINXBUILD) -M linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)