python-netgear-switch-library 0.0.post327__tar.gz → 0.0.post330__tar.gz

{python_netgear_switch_library-0.0.post327 → python_netgear_switch_library-0.0.post330}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-netgear-switch-library
-Version: 0.0.post327
+Version: 0.0.post330
 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

{python_netgear_switch_library-0.0.post327 → python_netgear_switch_library-0.0.post330}/docs/_ext/support_tables.py

@@ -32,9 +32,12 @@ from __future__ import annotations
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar
 
+from docutils import nodes
 from docutils.parsers.rst import directives
+from sphinx.transforms.post_transforms import SphinxPostTransform
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
+from sphinx.util.nodes import make_refnode
 
 from netgear_switch.capabilities import (
     READ_OPERATIONS,
@@ -43,12 +46,12 @@ from netgear_switch.capabilities import (
     backends_for,
     support,
 )
+from netgear_switch.protocols.http.endpoints import HTTP_SPECS
 from netgear_switch.registry import MODEL_ALIASES, MODELS, Backend, get_model
 
 if TYPE_CHECKING:
     from collections.abc import Iterable, Sequence
 
-    from docutils import nodes
     from sphinx.application import Sphinx
 
 logger = logging.getLogger(__name__)
@@ -87,6 +90,151 @@ def unverified_models() -> tuple[str, ...]:
     return tuple(key for key, model in MODELS.items() if not model.verified)
 
 
+#: The page documenting each backend. SSH, TELNET and CONSOLE are three
+#: transports over one command surface, so all three land on the CLI page.
+_BACKEND_PAGES = {
+    Backend.SNMP: "protocols/snmp",
+    Backend.NSDP: "protocols/nsdp",
+    Backend.HTTP: "protocols/http",
+    Backend.SSH: "protocols/cli",
+    Backend.TELNET: "protocols/cli",
+    Backend.CONSOLE: "protocols/cli",
+}
+
+#: Each web-UI login scheme gets its own page. They share a transport and
+#: nothing else: different login mechanics, different session handling and
+#: different page sets, which is why one "HTTP" page could not describe them.
+_HTTP_SCHEME_PAGES = {
+    "MERGE_HASH_CGI": "protocols/http/merge-hash-cgi",
+    "GAMBIT": "protocols/http/gambit",
+    "CHEETAH_FORM": "protocols/http/cheetah-form",
+    "CHEETAH_V1": "protocols/http/cheetah-v1",
+    "XML_API": "protocols/http/xml-api",
+}
+
+#: Literal text -> the page that documents it. Everything a generated table or a
+#: docstring can name: every model key, every alias, every backend name, every
+#: web-UI login scheme, and ``CLI`` for the command surface as a whole.
+_LINKABLE: dict[str, str] = {
+    **{key: f"models/{key}" for key in MODELS},
+    **{alias: f"models/{key}" for alias, key in MODEL_ALIASES.items()},
+    **{backend.name: page for backend, page in _BACKEND_PAGES.items()},
+    **_HTTP_SCHEME_PAGES,
+    "CLI": "protocols/cli",
+}
+
+
+class ReferenceLinks(SphinxPostTransform):
+    """Link every inline literal that names something this documentation defines.
+
+    Three kinds of name are resolved, in order: a switch model key or alias, a
+    backend name, and any Python object autodoc has documented (matched on its
+    full dotted path, so there is no ambiguity to guess at).
+
+    Doing this in a post-transform rather than at each use is what makes the
+    linking total, and it exists because per-use linking kept missing cases:
+
+    * The generated tables wrote a model key as a bare literal in three of the
+      seven builders, so ``docs/models/index.rst`` listed eight model keys and
+      linked none of them, while the protocol pages linked theirs.
+    * ``conf.py`` sets ``default_role = "literal"``, so every single-backtick
+      name renders as text. The module lists at the bottom of each protocol
+      page are written that way -- ```netgear_switch.http_read``` -- and were
+      silently not links, even though the class names beside them, written with
+      an explicit role, were.
+
+    Neither failure could be caught by ``nitpicky``: an unresolved *reference*
+    fails the build, but a literal that should have been a reference is
+    indistinguishable from ordinary text. Only linking them automatically
+    closes that gap.
+
+    Matching is exact and confined to inline literals, so prose about "the HTTP
+    backend" is untouched while ``` ``HTTP`` ``` becomes a link.
+    """
+
+    # After filelinks' post-transform (400), whose repository links are already
+    # `reference` nodes by this point and are skipped below.
+    default_priority = 410
+
+    #: The facade a bare operation name should resolve to when several classes
+    #: define it. ``get_vlans`` is documented on nine classes -- both facades and
+    #: every reader -- and the one a reader of prose means is the public
+    #: synchronous entry point.
+    _PREFERRED_OWNER = "netgear_switch.sync_api.SyncSwitch."
+
+    def _short_index(self) -> dict[str, list[str]]:
+        """Last path component -> the full names that end with it."""
+        objects = self.env.domaindata.get("py", {}).get("objects", {})
+        index: dict[str, list[str]] = {}
+        for name, entry in objects.items():
+            if getattr(entry, "aliased", False):
+                continue  # a duplicate of the canonical entry
+            index.setdefault(name.rsplit(".", 1)[-1], []).append(name)
+        return index
+
+    def _python_target(self, text: str) -> tuple[str, str] | None:
+        """``(docname, node_id)`` for a documented Python object, if any.
+
+        An exact dotted path always wins. A bare name is resolved only when it
+        is shaped like an API name -- CamelCase, SCREAMING_CASE or containing an
+        underscore -- and resolves unambiguously, or to the preferred facade.
+
+        The shape test is what keeps the linking honest. ``port``, ``name``,
+        ``host`` and ``model`` are all documented dataclass fields *and* ordinary
+        words that appear as literals throughout these docstrings; linking every
+        occurrence to one arbitrary dataclass would be worse than not linking.
+        """
+        objects = self.env.domaindata.get("py", {}).get("objects", {})
+        entry = objects.get(text)
+        if entry is not None:
+            return entry.docname, entry.node_id
+        if not ("_" in text or (text[:1].isupper() and text.isalnum())):
+            return None
+        candidates = self._short_index().get(text)
+        if not candidates:
+            return None
+        if len(candidates) > 1:
+            preferred = [c for c in candidates if c.startswith(self._PREFERRED_OWNER)]
+            if len(preferred) != 1:
+                return None
+            candidates = preferred
+        entry = objects[candidates[0]]
+        return entry.docname, entry.node_id
+
+    def run(self, **kwargs: Any) -> None:
+        counts = self.env.domaindata.setdefault("ngsw_reflinks", {"linked": 0})
+        for node in list(self.document.findall(nodes.literal)):
+            if isinstance(node.parent, nodes.reference):
+                continue  # already a link (a resolved xref, or filelinks')
+            if "xref" in node["classes"]:
+                continue  # an unresolved cross-reference, not a plain literal
+            text = node.astext().strip()
+
+            docname = _LINKABLE.get(text)
+            if docname is not None and docname in self.env.found_docs:
+                node_id = ""
+            else:
+                found = self._python_target(text)
+                if found is None:
+                    continue
+                docname, node_id = found
+
+            # A page linking to itself is noise; an anchor on the same page is
+            # not -- it jumps to the definition.
+            if docname == self.env.docname and not node_id:
+                continue
+            link = make_refnode(
+                self.app.builder,
+                self.env.docname,
+                docname,
+                node_id or None,
+                node.deepcopy(),
+            )
+            link["classes"].append("ngsw-ref")
+            node.replace_self(link)
+            counts["linked"] += 1
+
+
 def _rst_escape(text: str) -> str:
     """Neutralise inline reST markup in generated cell text."""
     for char in ("\\", "*", "`", "|", "_"):
@@ -99,14 +247,22 @@ def _list_table(
     header: Sequence[str],
     rows: Iterable[Sequence[str]],
     *,
-    widths: str = "",
+    classes: Sequence[str] = (),
 ) -> str:
-    """Render a reST ``list-table`` block."""
+    """Render a reST ``list-table`` block.
+
+    No ``:widths:`` is emitted, deliberately. ``docs/_static/ngsw.css`` gives
+    these tables ``white-space: nowrap`` inside a horizontally scrolling box,
+    so the browser's own table layout sizes every column to its content --
+    which is always right, and cannot go stale the way a hand-picked
+    percentage does when a model name or a backend list changes.
+
+    ``classes`` adds CSS classes beyond ``ngsw-support-table``. Only a table
+    whose last column holds prose wants ``ngsw-reason-table``.
+    """
     out = [f".. list-table:: {title}" if title else ".. list-table::"]
     out.append("   :header-rows: 1")
-    if widths:
-        out.append(f"   :widths: {widths}")
-    out.append("   :class: ngsw-support-table")
+    out.append("   :class: " + " ".join(("ngsw-support-table", *classes)))
     out.append("")
     for row in (header, *rows):
         cells = list(row)
@@ -149,7 +305,7 @@ class ModelTable(_GeneratedTable):
                     model.switch_class.value.replace("_", " "),
                     str(model.port_count),
                     str(model.poe_port_count),
-                    ", ".join(b.name for b in backends_for(model)),
+                    ", ".join(f"``{b.name}``" for b in backends_for(model)),
                     "live-verified" if model.verified else "**unverified**",
                 ]
             )
@@ -165,7 +321,6 @@ class ModelTable(_GeneratedTable):
                 "Status",
             ],
             rows,
-            widths="14 18 14 7 8 22 17",
         )
 
 
@@ -188,9 +343,8 @@ class ProtocolTable(_GeneratedTable):
             rows.append([f"``{key}``", *cells])
         return _list_table(
             "",
-            ["Model", *(b.name for b in self._COLUMNS)],
+            ["Model", *(f"``{b.name}``" for b in self._COLUMNS)],
             rows,
-            widths="26 12 12 12 12 12",
         )
 
 
@@ -259,7 +413,7 @@ class ModelSupportTable(_GeneratedTable):
 
         table = _list_table(
             "",
-            ["Operation", "What it does", *(b.name for b in backends)],
+            ["Operation", "What it does", *(f"``{b.name}``" for b in backends)],
             rows,
         )
         if not notes:
@@ -302,7 +456,7 @@ class SupportGaps(_GeneratedTable):
             "",
             ["Model", "Operation", "Served by", "Not served by", "Why"],
             rows,
-            widths="12 16 12 14 46",
+            classes=("ngsw-reason-table",),
         )
 
 
@@ -341,12 +495,12 @@ class BackendModelTable(_GeneratedTable):
         rows = []
         for key in _models_with(backends):
             model = MODELS[key]
-            reached = ", ".join(b.name for b in backends_for(model) if b in backends)
+            reached = ", ".join(
+                f"``{b.name}``" for b in backends_for(model) if b in backends
+            )
             rows.append(
                 [
-                    # Absolute doc path: this table is included from
-                    # docs/protocols/, so a relative target would resolve there.
-                    f":doc:`{key} </models/{key}>`",
+                    f"``{key}``",
                     _rst_escape(model.display_name),
                     model.switch_class.value.replace("_", " "),
                     str(model.port_count),
@@ -359,7 +513,6 @@ class BackendModelTable(_GeneratedTable):
             "",
             ["Model", "Product", "Class", "Ports", "Reached over"],
             rows,
-            widths="16 24 18 10 32",
         )
 
 
@@ -410,6 +563,136 @@ class BackendOperationTable(_GeneratedTable):
         return f"{table}\n{citations}\n"
 
 
+#: Every page an ``HttpModelSpec`` can carry a path for, in the order a reader
+#: meets them. ``None`` on a spec means that firmware ships no such page, which
+#: is why the generated coverage table can show a real gap rather than implying
+#: the operation is merely unimplemented here.
+_HTTP_PAGE_FIELDS = (
+    ("Dashboard / port status", "dashboard_path"),
+    ("Port statistics", "stats_path"),
+    ("PoE status", "poe_status_path"),
+    ("PoE configuration", "poe_config_path"),
+    ("VLAN configuration", "vlan_config_path"),
+    ("VLAN membership", "vlan_membership_path"),
+    ("PVIDs", "pvid_path"),
+    ("MAC / FDB table", "mac_table_path"),
+    ("LLDP neighbours", "lldp_path"),
+    ("System info", "sysinfo_path"),
+    ("Management IP", "mgmt_ip_path"),
+    ("Port configuration", "port_config_path"),
+    ("Certificate upload", "cert_upload_path"),
+    ("Reboot", "reboot_path"),
+    ("Logout", "logout_path"),
+)
+
+
+def _scheme_specs(scheme: str) -> list[Any]:
+    return [s for s in HTTP_SPECS.values() if s.scheme.name == scheme]
+
+
+def _transport(spec: Any) -> str:
+    """How the web UI is reached: scheme and port, where they are not default."""
+    proto = "HTTPS" if spec.secure else "HTTP"
+    return f"{proto}, port {spec.web_port}" if spec.web_port else proto
+
+
+class HttpSchemeTable(_GeneratedTable):
+    """Every web-UI login scheme, with the models and dialects behind it."""
+
+    def body(self) -> str:
+        rows = []
+        for scheme, page in _HTTP_SCHEME_PAGES.items():
+            specs = _scheme_specs(scheme)
+            if not specs:  # pragma: no cover - every scheme has a model today
+                continue
+            dialects = sorted({s.html_dialect.name for s in specs})
+            rows.append(
+                [
+                    f":doc:`{scheme} </{page}>`",
+                    ", ".join(f"``{s.model_key}``" for s in specs),
+                    ", ".join(f"``{d}``" for d in dialects),
+                    _transport(specs[0]),
+                ]
+            )
+        return _list_table(
+            "",
+            ["Login scheme", "Switches", "HTML dialect", "Reached over"],
+            rows,
+        )
+
+
+class HttpSchemeFacts(_GeneratedTable):
+    """One login scheme: the models on it and how each one is talked to."""
+
+    required_arguments = 1
+
+    def body(self) -> str:
+        scheme = self.arguments[0].strip().upper()
+        specs = _scheme_specs(scheme)
+        if not specs:
+            raise self.error(f"ngsw-http-scheme: no model uses scheme {scheme!r}")
+        rows = []
+        for spec in specs:
+            if spec.session_token_field:
+                session = f"token, ``{spec.session_token_field}``"
+            elif spec.cookie_name:
+                session = f"cookie, ``{spec.cookie_name}``"
+            else:
+                session = "none"
+            rows.append(
+                [
+                    f"``{spec.model_key}``",
+                    f"``{spec.html_dialect.name}``",
+                    _transport(spec),
+                    f"``{spec.login_path}``",
+                    ", ".join(
+                        f"``{f}``"
+                        for f in (spec.username_field, spec.password_field)
+                        if f
+                    ),
+                    session,
+                ]
+            )
+        return _list_table(
+            "",
+            [
+                "Switch",
+                "HTML dialect",
+                "Reached over",
+                "Login path",
+                "Fields",
+                "Session",
+            ],
+            rows,
+        )
+
+
+class HttpSchemePages(_GeneratedTable):
+    """Which pages each model on a scheme actually ships."""
+
+    required_arguments = 1
+
+    def body(self) -> str:
+        scheme = self.arguments[0].strip().upper()
+        specs = _scheme_specs(scheme)
+        if not specs:
+            raise self.error(f"ngsw-http-scheme-pages: no model uses {scheme!r}")
+        rows = []
+        for label, field in _HTTP_PAGE_FIELDS:
+            cells = []
+            for spec in specs:
+                path = getattr(spec, field, None)
+                cells.append(f"``{path}``" if path else _NO)
+            if all(cell == _NO for cell in cells):
+                continue
+            rows.append([label, *cells])
+        return _list_table(
+            "",
+            ["Page", *(f"``{s.model_key}``" for s in specs)],
+            rows,
+        )
+
+
 class ModelFacts(_GeneratedTable):
     """The registry record for one model, as a field list."""
 
@@ -453,7 +736,7 @@ class ModelFacts(_GeneratedTable):
                 "yes" if model.has_mac_table else "no",
             ]
         )
-        return _list_table("", ["Field", "Value"], rows, widths="30 70")
+        return _list_table("", ["Field", "Value"], rows)
 
 
 class ModelPhoto(_GeneratedTable):
@@ -594,6 +877,13 @@ def _report_missing_photos(app: Sphinx, exception: Exception | None) -> None:
     )
 
 
+def _report_reference_links(app: Sphinx, exception: Exception | None) -> None:
+    if exception is not None:
+        return
+    linked = app.env.domaindata.get("ngsw_reflinks", {}).get("linked", 0)
+    logger.info("ngsw: linked %d model/backend/API reference(s)", linked)
+
+
 def setup(app: Sphinx) -> dict[str, Any]:
     app.add_directive("ngsw-unverified-note", UnverifiedNote)
     app.add_directive("ngsw-model-table", ModelTable)
@@ -606,5 +896,10 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_directive("ngsw-backend-models", BackendModelTable)
     app.add_directive("ngsw-backend-operations", BackendOperationTable)
     app.add_directive("ngsw-support-gaps", SupportGaps)
+    app.add_directive("ngsw-http-scheme-table", HttpSchemeTable)
+    app.add_directive("ngsw-http-scheme", HttpSchemeFacts)
+    app.add_directive("ngsw-http-scheme-pages", HttpSchemePages)
+    app.add_post_transform(ReferenceLinks)
     app.connect("build-finished", _report_missing_photos)
+    app.connect("build-finished", _report_reference_links)
     return {"version": "1.0", "parallel_read_safe": True, "parallel_write_safe": True}

python_netgear_switch_library-0.0.post330/docs/_static/ngsw.css

@@ -0,0 +1,68 @@
+/* Generated support tables are wide by nature -- one column per switch model.
+   Let them scroll inside their own box rather than stretch the page. */
+table.ngsw-support-table {
+  display: block;
+  overflow-x: auto;
+  max-width: 100%;
+  white-space: nowrap;
+}
+
+table.ngsw-support-table td,
+table.ngsw-support-table th {
+  vertical-align: top;
+}
+
+/* A table whose LAST column carries full sentences (the parity-gaps "Why"
+   column): let it wrap, and give it room to be worth wrapping.
+
+   Scoped to that one class deliberately. As a blanket
+   `.ngsw-support-table td:last-child` rule this forced 20rem onto the last
+   column of every generated table -- so the model table's Status column, whose
+   widest value is the 13-character "live-verified", was rendered 320px wide. */
+table.ngsw-reason-table td:last-child {
+  white-space: normal;
+  min-width: 20rem;
+}
+
+/* Links produced by docs/_ext/filelinks.py: a file path that is also a link.
+   Keep the monospace look, add the underline links normally get. */
+a.repofile code,
+a.repofile tt {
+  text-decoration: underline;
+  text-decoration-style: dotted;
+}
+
+/* Product photos (docs/_ext/support_tables.py's ngsw-model-photo).
+
+   The class sits on the <img>, not the <figure>: reST's `figure` directive
+   applies its :class: to the image node, unlike the port map below, which is
+   raw HTML and carries the class on the figure itself. */
+img.ngsw-model-photo {
+  max-width: 100%;
+  height: auto;
+  border-radius: 6px;
+  /* These are product shots on a white background. Painting that background on
+     explicitly, rather than leaving whatever the image happens to carry, keeps
+     them from reading as a bright cut-out in the dark theme. */
+  background: #fff;
+  padding: 0.75rem;
+}
+figure:has(> img.ngsw-model-photo) {
+  margin: 1rem 0 1.5rem;
+}
+figure:has(> img.ngsw-model-photo) figcaption {
+  font-size: 0.85em;
+  opacity: 0.75;
+  margin-top: 0.4rem;
+}
+
+/* Generated port maps (docs/_ext/support_tables.py's ngsw-model-diagram). */
+figure.ngsw-port-map {
+  margin: 1rem 0 1.5rem;
+  text-align: center;
+}
+figure.ngsw-port-map figcaption {
+  font-size: 0.85em;
+  opacity: 0.75;
+  margin-top: 0.4rem;
+}

python_netgear_switch_library-0.0.post330/docs/protocols/http/cheetah-form.rst

@@ -0,0 +1,60 @@
+CHEETAH_FORM — the Cheetah login form
+=====================================
+
+The managed switches' web UI. A plain HTML form: username and password posted
+in the clear to ``/base/cheetah_login.html``, answered with a session cookie.
+No nonce, no hashing.
+
+Switches
+--------
+
+.. ngsw-http-scheme:: CHEETAH_FORM
+
+Two dialects on one login
+-------------------------
+
+``gsm7252ps`` and ``gsm7228ps`` log in identically and then serve the same
+Cheetah XE page grid, so both reuse the ``parse_xe_*`` parsers for ports,
+statistics, PVIDs, VLANs, PoE and LLDP.
+
+They are separate dialects because two pages genuinely differ on the S3300: its
+MAC table has shifted columns and escaped ``1/gN`` port names, and its sensor
+page differs too. Everything else is shared.
+
+The XUI shape worth knowing
+---------------------------
+
+These pages carry two ``<FORM>`` elements, and the interesting fields are not
+always the visible ones. Two consequences:
+
+**Errors arrive with HTTP 200.** A write that "succeeded" by status code may have
+failed in the body, so the library reads the body's status fields rather than
+trusting the response code.
+
+**A write must replay the whole form**, including hidden and list-navigation
+fields. This is where "the GSM7252PS refuses PoE writes over HTTP" came from —
+it was not firmware. The form needs a list-unit field (``v_1_1_1``) that the
+writer was not sending. With it, PoE writes apply cleanly.
+
+That is worth stating plainly because it is the exact failure mode this project
+treats as a bug in our code until proven otherwise: a missing field is rejected
+by the firmware in a way that looks indistinguishable from a device limitation.
+
+Pages
+-----
+
+.. ngsw-http-scheme-pages:: CHEETAH_FORM
+
+Certificate upload
+------------------
+
+Both models accept an HTTPS certificate through this UI, and the S3300's flow is
+grounded in a working prior implementation rather than inferred. See
+:py:meth:`~netgear_switch.sync_api.SyncSwitch.upload_certificate`.
+
+API
+---
+
+* ``netgear_switch.protocols.http.parse`` — the ``parse_xe_*`` parsers.
+* ``netgear_switch.protocols.http.forms`` — form scraping and replay.
+* ``netgear_switch.virtual.web_fastpath_xui`` — the mock's XUI renderer.

python_netgear_switch_library-0.0.post330/docs/protocols/http/cheetah-v1.rst

@@ -0,0 +1,57 @@
+CHEETAH_V1 — the M4300 ``/v1`` UI
+=================================
+
+The M4300's web interface. It posts both a username and a password, and then
+guards every subsequent request with a ``Referer`` header rather than a CSRF
+token field.
+
+Switches
+--------
+
+.. ngsw-http-scheme:: CHEETAH_V1
+
+How the login works
+-------------------
+
+**Both fields are required.** ``uname`` and ``pwd`` are posted together;
+password-only login is rejected.
+
+**The CSRF defence is the Referer header.** Requests without a plausible
+``Referer`` are refused, which is why the spec carries ``needs_referer``. This
+is unusual enough that a client written against any of the other four schemes
+will fail here for reasons that look like an authentication problem.
+
+**The session id has a short life.** The RID the UI issues expires in about 60
+seconds of inactivity, so a long-running read sequence must expect to
+re-authenticate rather than assume one login covers the whole run.
+
+The two SKUs are not reached the same way
+-----------------------------------------
+
+They share a dialect and a login, and differ in transport: the M4300-16X serves
+its UI over **HTTPS on port 49152**, while the M4300-24X is plain HTTP on the
+default port. The generated table above states each one's transport rather than
+letting the shared dialect imply a shared endpoint.
+
+That difference is measured, not assumed — the same pair of switches also runs
+different firmware (12.0.19.15 vs 12.0.13.8) and behaves differently on SNMP
+VLAN writes. Treating either as a proxy for the other has produced wrong answers
+in this project before.
+
+A dead end worth recording
+--------------------------
+
+The M4300's read-page URLs cannot be recovered by reading its HTML: the server
+builds its menu dynamically, so static analysis of the login page yields
+nothing. The paths in the spec came from driving the live UI.
+
+Pages
+-----
+
+.. ngsw-http-scheme-pages:: CHEETAH_V1
+
+API
+---
+
+* ``netgear_switch.protocols.http.session`` — Referer handling and the RID.
+* ``netgear_switch.virtual.web_m4300`` — the mock's renderer for these pages.