python-netgear-switch-library 0.0.post154__tar.gz → 0.0.post290__tar.gz

{python_netgear_switch_library-0.0.post154 → python_netgear_switch_library-0.0.post290}/.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
       matrix:
         python-version: ["3.11", "3.12", "3.13"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0  # full history so hatch-vcs can derive the version
 
@@ -30,7 +30,7 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y --no-install-recommends snmp
 
-      - uses: astral-sh/setup-uv@v6
+      - uses: astral-sh/setup-uv@v7
 
       - name: Install the matrix Python
         run: uv python install ${{ matrix.python-version }}

{python_netgear_switch_library-0.0.post154 → python_netgear_switch_library-0.0.post290}/.github/workflows/deb.yml

@@ -19,7 +19,7 @@ jobs:
       matrix:
         suite: [trixie, sid]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0  # full history so deb-version.py can count commits
 
@@ -30,7 +30,7 @@ jobs:
             docker.io/library/debian:${{ matrix.suite }} \
             sh packaging/ci-build.sh
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: debs-${{ matrix.suite }}
           path: built-debs/
@@ -45,16 +45,16 @@ jobs:
       name: github-pages
       url: ${{ steps.deploy.outputs.page_url }}
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Download trixie debs
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: debs-trixie
           path: apt-repo/trixie/
 
       - name: Download sid debs
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: debs-sid
           path: apt-repo/sid/
@@ -97,11 +97,11 @@ jobs:
             cd ../..
           done
 
-      - uses: actions/configure-pages@v5
+      - uses: actions/configure-pages@v6
 
-      - uses: actions/upload-pages-artifact@v3
+      - uses: actions/upload-pages-artifact@v5
         with:
           path: apt-repo/
 
       - id: deploy
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

{python_netgear_switch_library-0.0.post154 → python_netgear_switch_library-0.0.post290}/.github/workflows/publish-pypi.yml

@@ -16,11 +16,11 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
           fetch-depth: 0  # full history for hatch-vcs version derivation
 
-      - uses: astral-sh/setup-uv@v6
+      - uses: astral-sh/setup-uv@v7
 
       - name: Build sdist + wheel
         run: uv build
@@ -28,7 +28,7 @@ jobs:
       - name: Show derived version
         run: ls -1 dist/
 
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -41,7 +41,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{python_netgear_switch_library-0.0.post154 → python_netgear_switch_library-0.0.post290}/.gitignore

@@ -54,3 +54,6 @@ tmp/
 /.vscode
 /.zprofile
 /.zshrc
+
+# Playwright MCP scratch output
+.playwright-mcp/

{python_netgear_switch_library-0.0.post154 → python_netgear_switch_library-0.0.post290}/PKG-INFO

@@ -1,17 +1,24 @@
 Metadata-Version: 2.4
 Name: python-netgear-switch-library
-Version: 0.0.post154
+Version: 0.0.post290
 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
 License-File: LICENSE
 Requires-Python: >=3.11
+Requires-Dist: cryptography>=41
 Provides-Extra: async
 Requires-Dist: pysnmp>=7.0; extra == 'async'
 Provides-Extra: http
 Requires-Dist: httpx>=0.27; extra == 'http'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: ssh
+Requires-Dist: paramiko<3,>=2.12; extra == 'ssh'
+Requires-Dist: pyserial>=3.5; extra == 'ssh'
 Provides-Extra: sync
 Provides-Extra: testing
+Requires-Dist: mcp>=1.2; extra == 'testing'
 Requires-Dist: pysnmp>=7.0; extra == 'testing'
 Description-Content-Type: text/markdown
 
@@ -72,6 +79,55 @@ 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.
 
+## Mock switch daemons (`ngsw serve`)
+
+The library ships in-repo virtual/mock switches. `ngsw serve` runs them as
+standalone, long-lived daemons on real sockets, so an external tool or library
+can point at a mock when real hardware is unavailable (CI, local development,
+demos).
+
+```sh
+# Serve one model (ephemeral ports), or several, or every registered model:
+ngsw serve --model gsm7228ps
+ngsw serve --model gsm7228ps --model gs305ep
+ngsw serve --all
+```
+
+For each switch that comes up it prints the model, bind host, the actual bound
+port(s) (SNMP/NSDP over UDP, HTTP over TCP), and the SNMP community and HTTP
+password it accepts, then blocks until interrupted (`Ctrl-C` / `SIGTERM`), at
+which point every switch is stopped cleanly:
+
+```text
+[gsm7228ps] host=127.0.0.1
+    SNMP udp/36540
+    HTTP tcp/42629
+    community='public' http_password='password'
+serving 1 mock switch(es); press Ctrl-C to stop
+```
+
+Point any tool at the printed port. For example, with the mock above serving
+SNMP on UDP `36540`:
+
+```sh
+snmpwalk -v2c -c public 127.0.0.1:36540 1.3.6.1.2.1.1
+# ...or the library's own CLI against the same mock:
+ngsw --host 127.0.0.1 --model gsm7228ps --community public ports   # + your transport wiring
+```
+
+Options:
+
+- `--model KEY` — model to serve; repeatable. `--all` serves every registered
+  model (see `ngsw models`).
+- `--host IP` — bind address (default `127.0.0.1`). Pass `0.0.0.0` to expose the
+  mock to other hosts on the network.
+- `--community STR` / `--http-password STR` — credentials the mock accepts
+  (defaults `public` / `password`).
+- `--port N` / `--http-port N` — pin the SNMP/NSDP UDP port and the HTTP TCP
+  port instead of using ephemeral ones. Because a pinned port is a single
+  listener, these are only allowed when serving exactly one model; otherwise
+  leave them unset and read the printed ephemeral ports.
+
 ## Development
 
 ```sh

{python_netgear_switch_library-0.0.post154 → python_netgear_switch_library-0.0.post290}/README.md

@@ -55,6 +55,55 @@ 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.
 
+## Mock switch daemons (`ngsw serve`)
+
+The library ships in-repo virtual/mock switches. `ngsw serve` runs them as
+standalone, long-lived daemons on real sockets, so an external tool or library
+can point at a mock when real hardware is unavailable (CI, local development,
+demos).
+
+```sh
+# Serve one model (ephemeral ports), or several, or every registered model:
+ngsw serve --model gsm7228ps
+ngsw serve --model gsm7228ps --model gs305ep
+ngsw serve --all
+```
+
+For each switch that comes up it prints the model, bind host, the actual bound
+port(s) (SNMP/NSDP over UDP, HTTP over TCP), and the SNMP community and HTTP
+password it accepts, then blocks until interrupted (`Ctrl-C` / `SIGTERM`), at
+which point every switch is stopped cleanly:
+
+```text
+[gsm7228ps] host=127.0.0.1
+    SNMP udp/36540
+    HTTP tcp/42629
+    community='public' http_password='password'
+serving 1 mock switch(es); press Ctrl-C to stop
+```
+
+Point any tool at the printed port. For example, with the mock above serving
+SNMP on UDP `36540`:
+
+```sh
+snmpwalk -v2c -c public 127.0.0.1:36540 1.3.6.1.2.1.1
+# ...or the library's own CLI against the same mock:
+ngsw --host 127.0.0.1 --model gsm7228ps --community public ports   # + your transport wiring
+```
+
+Options:
+
+- `--model KEY` — model to serve; repeatable. `--all` serves every registered
+  model (see `ngsw models`).
+- `--host IP` — bind address (default `127.0.0.1`). Pass `0.0.0.0` to expose the
+  mock to other hosts on the network.
+- `--community STR` / `--http-password STR` — credentials the mock accepts
+  (defaults `public` / `password`).
+- `--port N` / `--http-port N` — pin the SNMP/NSDP UDP port and the HTTP TCP
+  port instead of using ephemeral ones. Because a pinned port is a single
+  listener, these are only allowed when serving exactly one model; otherwise
+  leave them unset and read the printed ephemeral ports.
+
 ## Development
 
 ```sh

python_netgear_switch_library-0.0.post290/docs/superpowers/plans/2026-07-23-gsm7252ps-http-xe-dialect.md

@@ -0,0 +1,130 @@
+# gsm7252ps HTTP (XE_FASTPATH dialect) Implementation Plan
+
+> **For agentic workers:** implement task-by-task, TDD, small commits.
+
+**Goal:** Add a full HTTP read backend to gsm7252ps whose output agrees with its
+SNMP backend, grounded in real captures. Design + live-verified XE format facts
+are in `docs/superpowers/specs/2026-07-23-gsm7252ps-http-xe-dialect-design.md`
+— READ THAT FIRST; it has the login scheme, page URLs, and the XE cell format.
+
+**Template:** The M4300 dialect is the closest existing analogue. Mirror it:
+`_M4300` spec in `protocols/http/endpoints.py`, `parse_m4300_*` +
+`parse_cheetah_rows` in `protocols/http/parse.py`, `_is_m4300_dialect` wiring in
+`http_read.py`, `web_m4300.py` mock face. The XE format differs (see spec §"XE
+cell format") — cells are `NAME=<port>.v_<row>_<col> VALUE="…"` with NO
+`<!-- field -->` comment, addressed by COLUMN INDEX.
+
+## Status (2026-07-23)
+Tasks 1-8 are DONE on branch `feat/gsm7252ps-http`. Task 9 (the live
+HTTP<->SNMP cross-verify against 10.1.5.22, then flipping
+`_GSM7252PS.reads_verified=True`) is the only remaining step and is
+controller-only.
+
+## Global Constraints
+- Honesty: `scheme_verified`/`reads_verified` only where grounded.
+- CORRECTION (2026-07-23): an earlier draft of this line claimed sensors and
+  mgmt_ip are JS-populated on gsm7252ps and must raise
+  `UnsupportedCapabilityError`. That was WRONG -- `sysInfo.html` carries both
+  in its static HTML (see the design doc's own CORRECTION section), and both
+  ops are implemented over HTTP. There is NO unsupported carve-out for this
+  model. An op may only be declared unsupported if it is PROVEN absent from
+  every capture.
+- Every column map hardcoded in a parser MUST be justified by a committed
+  fixture; document the column→field mapping in a comment beside it.
+- `uv run` for all python. Small commits per task.
+
+## Grounding assets
+Live captures are in `tmp/live-captures/gsm7252ps_*.html` (gitignored working
+copies, session tokens present). Task 1 copies + scrubs them into fixtures.
+
+---
+
+### Task 1: Fixtures
+- Copy these `tmp/live-captures/gsm7252ps_*` pages to
+  `tests/fixtures/http/gsm7252ps_<name>.html`, SCRUBBING any `SID=`/session
+  token to `SID=SCRUBBED`: portsConfiguration, portStatistics,
+  portPvidConfiguration, vlanStatus, basicAddressTable,
+  poeInterfaceConfiguration, lldpRemoteInventory, and the login page.
+- Also copy `base_system_management_sysInfo.html` as
+  `gsm7252ps_sysInfo.html` (evidence that sensors/mgmt-IP are JS-populated).
+- Commit.
+
+### Task 2: `parse_xe_rows` + get_ports parser (TDD)
+- In `parse.py`: `parse_xe_rows(html) -> dict[int, dict[str,str]]` grouping
+  `NAME=<u>.<s>.<p>.v_<row>_<col> VALUE="…"` cells by port number (the instance
+  prefix `1.0.52` → port 52), value keyed by the `v_<row>_<col>` coord. Add
+  `_XE_CELL_RE`. HTML-unescape values (interface names arrive escaped).
+- `parse_xe_port_status(html) -> list[PortStatus]` using the column map decoded
+  from `gsm7252ps_portsConfiguration.html` (spec shows v_1_2_8=autoneg,
+  _9=speed, _10=link; CONFIRM the port-name/admin columns against the fixture).
+- Test: `tests/protocols/http/test_parse.py` — assert exact port count (52) and
+  a few transcribed rows (port 52 link/speed) from the fixture.
+- Commit.
+
+### Task 3: remaining XE parsers (TDD, one commit each)
+For each, decode the column map from the fixture, implement, test vs fixture:
+- `parse_xe_stats` ← portStatistics.html (confirm counter columns; if the page
+  reports frames not octets, mirror parse_m4300_stats' honest None-bytes).
+- `parse_xe_pvids` ← portPvidConfiguration.html → list[(port, pvid)].
+- `parse_xe_vlans` ← vlanStatus.html → list[VLANInfo] (member/tagged/untagged).
+- `parse_xe_macs` ← basicAddressTable.html → list[MacEntry] (skip non-physical;
+  raise on truncated/paginated table like parse_m4300_macs).
+- `parse_xe_poe` ← poeInterfaceConfiguration.html → list[PoEStatus].
+- `parse_xe_lldp` ← lldpRemoteInventory.html → list[LLDPNeighbor] (if the
+  fixture has no neighbours, return [] and note it; do not invent).
+- `parse_xe_labelled_values` ← sysInfo.html: generic label-cell → value-cell
+  extractor for the format-(B) page.
+- `parse_xe_sensors` ← sysInfo.html → list[Sensor]: Temperature Status table,
+  FAN Status table (Fan1..Fan8), and RPS / Power Module state.
+- `parse_xe_mgmt_ip` ← sysInfo.html → MgmtIpConfig: `IPv4 Network Interface`
+  is "addr/netmask" (10.1.5.22/255.255.255.0); base_mac from
+  `System MAC Address` (E0:91:F5:0C:D6:DB on the fixture).
+  NOTE: an earlier draft wrongly called these two ops HTTP-infeasible. They are
+  NOT — see the design doc's CORRECTION section. Do not skip them.
+
+### Task 4: endpoint spec + dialect
+- `endpoints.py`: add `HtmlDialect.XE_FASTPATH`. Add `_GSM7252PS` HttpModelSpec:
+  scheme=CHEETAH_FORM, login_path=`/base/cheetah_login.html`,
+  username_field=`uname`, username=`admin`, password_field=`pwd`,
+  cookie_name=`SID`, read paths at `/` prefix (dashboard_path=
+  `/portsConfiguration.html`, stats_path=`/portStatistics.html`,
+  pvid_path=`/portPvidConfiguration.html`, vlan_config_path=`/vlanStatus.html`,
+  mac_table_path=`/basicAddressTable.html`, poe_status_path=
+  `/poeInterfaceConfiguration.html`,
+  sysinfo_path=`/base/system/management/sysInfo.html`), html_dialect=
+  XE_FASTPATH, scheme_verified=True, reads_verified=False (flipped after live
+  cross-verify). Register in `_SPECS`.
+- Test `test_endpoints.py`: gsm7252ps has a spec; test_every_http_model_has_a_spec passes.
+
+### Task 5: registry HTTP backend
+- `registry.py`: gsm7252ps backends `{Backend.SNMP}` → `{Backend.SNMP, Backend.HTTP}`.
+- Update the seed docstring/comment note. Test `test_registry.py`.
+
+### Task 6: http_read dispatch
+- `http_read.py`: add `_is_xe_fastpath_dialect(spec)`. Wire get_ports/stats/
+  pvids/vlans/macs/poe/lldp to the XE parsers (parallel to the m4300 branches).
+  get_sensors/get_mgmt_ip: wire to parse_xe_sensors / parse_xe_mgmt_ip via
+  sysinfo_path. NO UnsupportedCapabilityError carve-out for this model.
+  Mirror both Sync and Async readers.
+- Tests `test_http_read.py` using the fixtures via a mock transport.
+
+### Task 7: mock face + seed upgrade
+- New `virtual/web_gsm7252ps.py`: render the XE (A) cell format from
+  `VirtualSwitchState` (instance-prefixed v_ cells) for ports/stats/pvids/
+  vlans/macs/poe pages.
+- `faces/http.py`: CHEETAH_FORM login (uname+pwd → SID) + XE render dispatch
+  for the gsm7252ps model.
+- `seed.py`: upgrade `seed_gsm7252ps` from ILLUSTRATIVE → transcribed from the
+  real 52-port capture (real link/speed/PVID/VLAN values from the fixtures).
+- Test `test_virtual_http_face.py`.
+
+### Task 8: cross-backend equivalence
+- `test_cross_backend_equivalence.py`: parametrize gsm7252ps SNMP↔HTTP for
+  ports/stats/pvids/vlans/macs/poe/lldp, driving both faces of one
+  VirtualSwitch, asserting agreement.
+- Full suite green: `uv run --extra http --extra async --extra mcp pytest`.
+
+### Task 9 (CONTROLLER-ONLY, live): HTTP↔SNMP cross-verify
+- The controller runs the real HTTP reads vs SNMP against 10.1.5.22, fixes any
+  live discrepancy, then flips `_GSM7252PS.reads_verified=True`. Not a subagent
+  task (needs the switch + credentials).

python_netgear_switch_library-0.0.post290/docs/superpowers/specs/2026-07-23-gsm7252ps-http-xe-dialect-design.md

@@ -0,0 +1,141 @@
+# gsm7252ps HTTP backend (XE_FASTPATH dialect) — Design
+
+**Goal:** Give the gsm7252ps a full HTTP read backend whose output agrees with
+its existing SNMP backend, grounded entirely in real captures from the live
+switch (10.1.5.22). One step of the broader fleet-HTTP + CLI goal
+(see memory `netgear-fleet-http-and-cli-scope`).
+
+**Status:** Design approved 2026-07-23. Grounding captured live (see
+`tmp/live-captures/gsm7252ps_*.html`). Next: writing-plans → subagent-driven.
+
+## Live-verified facts (real switch 10.1.5.22, admin login)
+
+- **Login:** `CHEETAH_FORM` — `POST /base/cheetah_login.html`, form fields
+  `uname=admin` + `pwd=<password>` (+ err_flag=0, submt, login_button.x/y),
+  sets an `SID` cookie. Validated live.
+- **Read pages** live at the ROOT `/` prefix (NOT `/base/`, NOT `/v1/`), e.g.
+  `/portsConfiguration.html`, `/portStatistics.html`, `/vlanStatus.html`,
+  `/portPvidConfiguration.html`, `/basicAddressTable.html`,
+  `/poeInterfaceConfiguration.html`, `/portSummary.html`,
+  `/lldpRemoteInventory.html`, `/vlanConfiguration.html`, and
+  `/base/system/management/sysInfo.html`.
+- **Switch:** 52 ports (1/0/1 .. 1/0/52).
+
+## The XE cell format (the crux)
+
+Pages are "auto-generated by XE". The M4300 parsers do NOT work here (verified:
+they return 0 rows / raise). Two data formats appear:
+
+### (A) Instance-prefixed `v_` cells — STATICALLY PARSEABLE (the core pages)
+Each data cell is an HTML `<TD>` carrying a hidden input:
+```
+<TD class="def alt0" p="1.0.520" id=1_2_10>
+  <INPUT xid=1_2_10 TYPE=hidden NAME=1.0.52.v_1_2_10 VALUE="Link Up">Link Up</TD>
+```
+- `NAME=<instance>.v_<row>_<col>` — a row **instance prefix** and a **column
+  coordinate** `v_<row>_<col>`.
+- **CORRECTION (2026-07-23, from the committed fixtures):** the instance
+  prefix is `1.<row-index>.<row-count>`, NOT `unit.slot.port`. In
+  `gsm7252ps_portsConfiguration.html` the FIRST row is
+  `NAME=1.0.52.v_1_2_1 VALUE="1/0/1"` and the last is `1.51.52 -> "1/0/52"`:
+  the trailing 52 is the ROW COUNT, identical on every row. Reading "1.0.52"
+  as "port 52" would label all 52 ports 52. Port identity comes from the row's
+  own cells (the `ifindex` column, or the `1/0/N` interface name).
+- There is **NO `<!-- field_name -->` comment** (unlike M4300). Fields are
+  addressed by COLUMN INDEX; the column→field meaning is fixed per page and
+  must be hardcoded from a real capture (documented beside each map).
+- Example column map for `portsConfiguration.html` (from capture):
+  `v_1_2_8`=autoneg ("Auto"), `v_1_2_9`=speed ("1000 Mbps"),
+  `v_1_2_10`=link ("Link Up"/"Link Down"). (Implementer: confirm the full
+  column set against the fixture; the numeric columns and their labels are
+  both present in the captured HTML.)
+
+### (B) Plain label/value tables — ALSO STATICALLY PARSEABLE
+`sysInfo.html` (sensors: Temperature/FAN/RPS/Power-Module; system name, MAC,
+product name, up-time; mgmt-IP) does NOT use the `v_` cell format. It uses
+plain label/value table cells, e.g. a `<td class="font10Bold">System MAC
+Address</td>` label followed by a value cell. **The values ARE present in the
+static HTML** — verified live on 10.1.5.22:
+
+```
+System MAC Address        E0:91:F5:0C:D6:DB
+IPv4 Network Interface    10.1.5.22/255.255.255.0
+RPS                       Operational
+Power Module              Operational
+Product Name              GSM7252PS 48-Port GE L2+ Managed Stackable PoE Switch
+System Up Time            13 days 7 hours 44 mins 6 secs
+Temperature Status        (Sensor Type / Unit table)
+FAN Status                (Unit ID / Fan1..Fan8 OK table)
+```
+
+**CORRECTION (2026-07-23):** an earlier draft of this design claimed these
+values were JS-populated and therefore declared `get_sensors`/`get_mgmt_ip`
+HTTP-infeasible. That was WRONG — it came from grepping for the `v_` cell
+pattern (absent here) and inferring "JS-only" instead of reading the page text.
+`sysInfo.html` and its `_rw` variant are byte-identical in content; no extra
+endpoint is needed. Both ops ARE supported over HTTP. Do not re-introduce an
+`UnsupportedCapabilityError` for them.
+
+## Read-op feasibility (full-parity target, honest boundary)
+
+| Op | HTTP page | Format | HTTP support |
+|----|-----------|--------|--------------|
+| get_ports | portsConfiguration.html / portSummary.html | (A) | YES |
+| get_stats | portStatistics.html | (A) — confirm counters | YES |
+| get_pvids | portPvidConfiguration.html | (A) | YES |
+| get_vlans | vlanStatus.html / vlanConfiguration.html | (A) | YES |
+| get_macs (FDB) | basicAddressTable.html (169 KB) | (A) | YES |
+| get_poe | poeInterfaceConfiguration.html | (A) | YES (48-PoE) |
+| get_lldp | lldpRemoteInventory.html / lldpRemoteDevice.html | (A) | YES if neighbours present; capture to confirm |
+| get_sensors | sysInfo.html | (B) label/value | **YES** — Temperature + FAN tables, RPS/Power Module status |
+| get_mgmt_ip | sysInfo.html | (B) label/value | **YES** — `IPv4 Network Interface` (addr/netmask) + `System MAC Address` |
+
+**Every read op the model supports is served over HTTP. There is no
+UnsupportedCapabilityError carve-out for this model.** An op may only be
+declared unsupported if it is PROVEN absent from every page (no value in any
+capture), not merely because the first parse attempt missed it.
+
+## Design
+
+- **New `HtmlDialect.XE_FASTPATH`** (generic name — a firmware-family trait,
+  extensible to other XE switches later; validated only against gsm7252ps now
+  and marked as such).
+- **Parser** `parse_xe_rows(html)`: group `NAME=<port>.v_<row>_<col> VALUE="…"`
+  cells by port instance (`1.0.N` → port N), each row = {column-coord: value}.
+  Then per-op `parse_xe_{port_status,stats,pvids,vlans,macs,poe,lldp}` apply a
+  hardcoded column map. (Implemented: each map is documented beside the parser
+  AND cross-checked against that page's own visible header row, which carries
+  the human label under the same coordinate.) **Plus** a separate `parse_xe_labelled_values(html)` for
+  format (B) (label cell → value cell), feeding `parse_xe_sensors` (Temperature
+  + FAN tables, RPS/Power Module) and `parse_xe_mgmt_ip` (`IPv4 Network
+  Interface` "addr/netmask" + `System MAC Address`) from `sysInfo.html`.
+  Every (A) column map must be grounded in a committed fixture. Reuse existing
+  helpers (`_speed_text_to_mbps`, `_int`) where they fit.
+- **Endpoint spec** `_GSM7252PS` (HttpModelSpec): scheme CHEETAH_FORM, login
+  `/base/cheetah_login.html`, username_field=uname, username=admin,
+  password_field=pwd, cookie SID, read paths at `/` prefix,
+  `sysinfo_path="/base/system/management/sysInfo.html"` (serves BOTH sensors and
+  mgmt-IP), html_dialect=XE_FASTPATH. `scheme_verified=True` (login validated live);
+  `reads_verified=True` only after the live HTTP↔SNMP cross-verify passes.
+- **Registry:** gsm7252ps backends `{SNMP}` → `{SNMP, HTTP}`.
+- **Dispatch:** `http_read.py` gains `_is_xe_fastpath_dialect` wiring each read
+  op to its XE parser, INCLUDING get_sensors + get_mgmt_ip via sysInfo.html.
+  No UnsupportedCapabilityError carve-out for this model.
+- **Mock:** new `virtual/web_gsm7252ps.py` renders the XE (A) cell format from
+  `VirtualSwitchState`; `faces/http.py` adds the CHEETAH_FORM login + XE render.
+  `seed_gsm7252ps` upgraded from ILLUSTRATIVE → transcribed from the real
+  52-port capture (real link/speed/PVID/VLAN values) so the mock mimics
+  hardware.
+- **Fixtures:** `tests/fixtures/http/gsm7252ps_*.html` — the real captures with
+  session tokens (SID) scrubbed.
+
+## Testing / honesty
+
+- Unit tests for each XE parser against the real fixtures (exact expected
+  values transcribed from the capture).
+- `test_cross_backend_equivalence.py`: gsm7252ps SNMP↔HTTP for every supported
+  op, driving both faces of one VirtualSwitch (mock renders real XE format).
+- One live HTTP↔SNMP cross-verify against 10.1.5.22 before flipping
+  `reads_verified=True`.
+- Any op without a grounded capture stays `UnsupportedCapabilityError` — never
+  fabricated.

python_netgear_switch_library-0.0.post290/pyproject.toml

@@ -0,0 +1,115 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-netgear-switch-library"
+dynamic = ["version"]
+description = "Python library and CLI to query and control Netgear switches over SNMP, NSDP and HTTP."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Tim Ansell", email = "me@mith.ro" }]
+# cryptography is a first-class core dep: the SSL-certificate upload API
+# (HttpWriter.upload_certificate) uses it to convert an RSA private key to the
+# PKCS#1 "traditional" form the GS728TPP GoAhead XML API requires, with no
+# shelling out to openssl. It ships type stubs, so mypy stays clean.
+dependencies = ["cryptography>=41"]
+
+[project.optional-dependencies]
+# The sync SNMP transport shells out to the net-snmp CLI tools (snmpget/
+# snmpbulkwalk/snmpset), which are a system package (apt install snmp), not a
+# Python dependency; ezsnmp fails to build on arm64 and is intentionally not
+# used.
+sync = []
+async = ["pysnmp>=7.0"]
+http = ["httpx>=0.27"]
+# FASTPATH CLI backend (SSH/telnet/console). paramiko is PINNED <3: old FASTPATH
+# firmware (GSM7252PS/M4300) only offers diffie-hellman-group14-sha1 KEX + the
+# ssh-rsa (SHA-1) host key, which paramiko 3.0 dropped from its default
+# preferred lists (2.12 is confirmed working live). The SSH transport ALSO
+# re-inserts those legacy algorithms explicitly (see transport/cli/ssh.py), so
+# the pin is belt-and-suspenders. pyserial drives the serial-console transport;
+# the telnet transport uses the stdlib telnetlib (removed in Python 3.13 -- see
+# transport/cli/telnet.py).
+ssh = ["paramiko>=2.12,<3", "pyserial>=3.5"]
+testing = ["pysnmp>=7.0", "mcp>=1.2"]
+# MCP server (ngsw-mcp): exposes the read/write API as MCP tools over stdio.
+mcp = ["mcp>=1.2"]
+
+[project.scripts]
+ngsw = "netgear_switch.cli.main:main"
+ngsw-mcp = "netgear_switch.mcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.11", "pytest-cov>=5.0"]
+
+# Rolling release: the version is derived from git, never hand-edited and never
+# tagged. Every commit on main increments the commit height, so post-release
+# versioning yields a real, monotonic version (0.0.postN with no tag; X.Y.postN
+# once a vX.Y tag ever exists). "no-local-version" keeps the version PyPI-upload
+# safe. These forms are also valid Debian versions verbatim.
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+version_scheme = "post-release"
+local_scheme = "no-local-version"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/netgear_switch/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/netgear_switch"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/netgear_switch/py.typed" = "netgear_switch/py.typed"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --cov=netgear_switch --cov-report=term-missing --cov-fail-under=90"
+
+[tool.ruff]
+target-version = "py311"
+src = ["src", "tests"]
+extend-exclude = [
+    "src/netgear_switch/_version.py",
+    # Pure-data module: single-line HTML string constants copied byte-for-byte
+    # from real GS110EMX captures (see virtual/web_gs110emx.py) -- there is no
+    # meaningful line-length/style to enforce on a literal HTML capture.
+    "src/netgear_switch/virtual/web_gs110emx_templates.py",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF", "PT", "TC", "C4", "PIE", "RET", "N"]
+
+[tool.mypy]
+packages = ["netgear_switch"]
+strict = true
+python_version = "3.11"
+
+[[tool.mypy.overrides]]
+module = "netgear_switch._version"
+ignore_errors = true
+
+# The MCP server wraps the external, untyped `mcp` SDK: its FastMCP.tool()
+# decorator is untyped (so every tool trips untyped-decorator) and its
+# handlers return Any. Relax just those two checks for this one module rather
+# than sprinkle per-line ignores; the wrapped library calls stay fully typed.
+[[tool.mypy.overrides]]
+module = "netgear_switch.mcp.*"
+disallow_untyped_decorators = false
+warn_return_any = false
+
+[[tool.mypy.overrides]]
+module = "mcp.*"
+ignore_missing_imports = true
+
+# The CLI transports lazily import optional, unstubbed third-party libraries
+# (paramiko for SSH, pyserial for the serial console). They are behind the
+# '[ssh]' extra and imported inside methods, so the library stays fully typed;
+# relax only the missing-stub check for these two, like the mcp override above.
+[[tool.mypy.overrides]]
+module = ["paramiko.*", "serial.*"]
+ignore_missing_imports = true