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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-netgear-switch-library
-Version: 0.0.post326
+Version: 0.0.post327
 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.post326 → python_netgear_switch_library-0.0.post327}/docs/_ext/support_tables.py

@@ -341,9 +341,7 @@ 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(b.name for b in backends_for(model) if b in backends)
             rows.append(
                 [
                     # Absolute doc path: this table is included from
@@ -382,9 +380,7 @@ class BackendOperationTable(_GeneratedTable):
         for op in (*READ_OPERATIONS, *WRITE_OPERATIONS):
             cells = []
             for key in keys:
-                backend = next(
-                    (b for b in backends_for(key) if b in backends), None
-                )
+                backend = next((b for b in backends_for(key) if b in backends), None)
                 if backend is None:  # pragma: no cover - filtered by _models_with
                     cells.append(_NO)
                     continue
@@ -450,9 +446,7 @@ class ModelFacts(_GeneratedTable):
                     ]
                 )
         if aliases:
-            rows.append(
-                ["Aliases", ", ".join(f"``{a}``" for a in aliases)]
-            )
+            rows.append(["Aliases", ", ".join(f"``{a}``" for a in aliases)])
         rows.append(
             [
                 "MAC/FDB table",
@@ -497,6 +491,71 @@ class ModelPhoto(_GeneratedTable):
 MISSING_PHOTOS: set[str] = set()
 
 
+class ModelDiagram(_GeneratedTable):
+    """A schematic port map for one model, drawn from the registry.
+
+    Not a photograph and not a faceplate: it shows the ports *as this library
+    addresses them*, which is the thing a caller actually needs when deciding
+    what to pass as ``port=``. Generated from ``port_count`` and
+    ``poe_port_count``, so it cannot drift from the registry -- and so it never
+    asserts a physical arrangement nobody measured.
+    """
+
+    required_arguments = 1
+
+    _COLS = 26
+    _BOX = 26
+    _GAP = 4
+
+    def body(self) -> str:
+        model = get_model(self.arguments[0])
+        total, poe = model.port_count, model.poe_port_count
+        step = self._BOX + self._GAP
+        rows = (total + self._COLS - 1) // self._COLS
+        width = min(total, self._COLS) * step + self._GAP
+        height = rows * step + self._GAP + 22
+
+        parts = [
+            f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {width} {height}" '
+            f'role="img" aria-label="Port map: {total} ports, {poe} with PoE" '
+            'style="max-width:100%;height:auto">'
+        ]
+        for index in range(total):
+            port = index + 1
+            col, row = index % self._COLS, index // self._COLS
+            x = self._GAP + col * step
+            y = self._GAP + row * step
+            # PoE ports come first on every model in this registry; anything
+            # beyond that count is drawn as a plain (usually uplink) port.
+            fill = "#2b6cb0" if port <= poe else "#a0aec0"
+            parts.append(
+                f'<rect x="{x}" y="{y}" width="{self._BOX}" height="{self._BOX}" '
+                f'rx="3" fill="{fill}"/>'
+                f'<text x="{x + self._BOX / 2}" y="{y + self._BOX / 2 + 4}" '
+                'font-size="10" text-anchor="middle" fill="#fff" '
+                f'font-family="monospace">{port}</text>'
+            )
+        legend_y = rows * step + self._GAP + 14
+        parts.append(
+            f'<rect x="4" y="{legend_y - 9}" width="11" height="11" rx="2" '
+            'fill="#2b6cb0"/>'
+            f'<text x="20" y="{legend_y}" font-size="11" fill="currentColor">'
+            f"PoE ({poe})</text>"
+            f'<rect x="86" y="{legend_y - 9}" width="11" height="11" rx="2" '
+            'fill="#a0aec0"/>'
+            f'<text x="102" y="{legend_y}" font-size="11" fill="currentColor">'
+            f"no PoE ({total - poe})</text>"
+        )
+        parts.append("</svg>")
+        svg = "".join(parts)
+        return (
+            ".. raw:: html\n\n"
+            f'   <figure class="ngsw-port-map">{svg}'
+            "<figcaption>Port map as the library addresses these ports — "
+            "schematic, not a faceplate layout.</figcaption></figure>\n"
+        )
+
+
 class UnverifiedNote(_GeneratedTable):
     """Name the models the tables leave out, and say why."""
 
@@ -543,6 +602,7 @@ def setup(app: Sphinx) -> dict[str, Any]:
     app.add_directive("ngsw-model-support", ModelSupportTable)
     app.add_directive("ngsw-model-facts", ModelFacts)
     app.add_directive("ngsw-model-photo", ModelPhoto)
+    app.add_directive("ngsw-model-diagram", ModelDiagram)
     app.add_directive("ngsw-backend-models", BackendModelTable)
     app.add_directive("ngsw-backend-operations", BackendOperationTable)
     app.add_directive("ngsw-support-gaps", SupportGaps)

{python_netgear_switch_library-0.0.post326 → python_netgear_switch_library-0.0.post327}/docs/_static/ngsw.css

@@ -25,3 +25,14 @@ a.repofile tt {
   text-decoration: underline;
   text-decoration-style: dotted;
 }
+
+/* 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.post326 → python_netgear_switch_library-0.0.post327}/docs/models/gs105pe.rst

@@ -3,6 +3,8 @@ GS105PE
 
 .. ngsw-model-photo:: gs105pe
 
+.. ngsw-model-diagram:: gs105pe
+
 A 5-port "Smart Plus" switch (Gen-2 Broadcom BCM53125) — a genuinely distinct
 SKU from the GS305EP, not a rebadge. No SNMP; NSDP and the web UI.
 

{python_netgear_switch_library-0.0.post326 → python_netgear_switch_library-0.0.post327}/docs/models/gs110emx.rst

@@ -3,6 +3,8 @@ GS110EMX
 
 .. ngsw-model-photo:: gs110emx
 
+.. ngsw-model-diagram:: gs110emx
+
 A 10-port Plus switch with multi-gigabit uplinks and no PoE. Like every Plus
 model it has **no SNMP agent**: it is managed over NSDP and its web UI.
 

{python_netgear_switch_library-0.0.post326 → python_netgear_switch_library-0.0.post327}/docs/models/gs305ep.rst

@@ -3,6 +3,8 @@ GS305EP
 
 .. ngsw-model-photo:: gs305ep
 
+.. ngsw-model-diagram:: gs305ep
+
 A 5-port Plus switch with PoE on 4 ports. No SNMP; managed over NSDP and the
 web UI.
 

{python_netgear_switch_library-0.0.post326 → python_netgear_switch_library-0.0.post327}/docs/models/gs728tpp.rst

@@ -3,6 +3,8 @@ GS728TPP
 
 .. ngsw-model-photo:: gs728tpp
 
+.. ngsw-model-diagram:: gs728tpp
+
 A 28-port Smart Managed Pro switch with 24 PoE+ ports. The most unusual entry in
 the registry: its SNMP agent implements **no Netgear vendor OIDs at all**, and
 its web UI is an XML API rather than scraped HTML.

{python_netgear_switch_library-0.0.post326 → python_netgear_switch_library-0.0.post327}/docs/models/gsm7228ps.rst

@@ -3,6 +3,8 @@ S3300-52X-PoE+
 
 .. ngsw-model-photo:: gsm7228ps
 
+.. ngsw-model-diagram:: gsm7228ps
+
 A 52-port Smart Managed Pro switch with 48 PoE ports — despite the
 ``GSM7228PS`` part-number family suggesting 28. The registry key is
 ``gsm7228ps``; ``s3300`` is an alias resolving to the same record, because the

{python_netgear_switch_library-0.0.post326 → python_netgear_switch_library-0.0.post327}/docs/models/gsm7252ps.rst

@@ -3,6 +3,8 @@ GSM7252PS
 
 .. ngsw-model-photo:: gsm7252ps
 
+.. ngsw-model-diagram:: gsm7252ps
+
 A 52-port Fully Managed stackable switch, 48 of them PoE. The model with the
 widest verified backend coverage in this fleet — SNMP, the XE FASTPATH web UI
 and the CLI are all cross-verified against each other — and the one the

{python_netgear_switch_library-0.0.post326 → python_netgear_switch_library-0.0.post327}/docs/models/m4300-16x.rst

@@ -3,6 +3,8 @@ M4300-16X
 
 .. ngsw-model-photo:: m4300-16x
 
+.. ngsw-model-diagram:: m4300-16x
+
 The XSM4316, a Fully Managed 10G switch with PoE on all 16 ports, running
 FASTPATH **12.0.19.15** — a different firmware from its M4300-24X sibling, which
 is exactly why its behaviour was measured rather than inherited.

{python_netgear_switch_library-0.0.post326 → python_netgear_switch_library-0.0.post327}/docs/models/m4300-24x.rst

@@ -3,6 +3,8 @@ M4300-24X
 
 .. ngsw-model-photo:: m4300-24x
 
+.. ngsw-model-diagram:: m4300-24x
+
 The XSM4324CS, a Fully Managed 10G aggregation switch running FASTPATH
 12.0.13.8. Reachable over SNMP, the Cheetah ``/v1`` web UI, and the FASTPATH
 CLI on SSH or telnet.

{python_netgear_switch_library-0.0.post326 → python_netgear_switch_library-0.0.post327}/src/netgear_switch/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.0.post326'
-__version_tuple__ = version_tuple = (0, 0, 'post326')
+__version__ = version = '0.0.post327'
+__version_tuple__ = version_tuple = (0, 0, 'post327')
 
 __commit_id__ = commit_id = None