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

{python_netgear_switch_library-0.0.post325 → 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.post325
+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.post325 → 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
@@ -399,7 +395,12 @@ class BackendOperationTable(_GeneratedTable):
                     seen[reason] = index
                     notes.append(reason)
                 cells.append(f"{_NO} [{label}-{index}]_")
-            rows.append([f":py:meth:`~netgear_switch.SyncSwitch.{op.name}`", *cells])
+            # The facade class is documented under its defining module, so a
+            # `netgear_switch.SyncSwitch.x` target does not resolve and would
+            # render as plain text rather than a link.
+            rows.append(
+                [f":py:meth:`~netgear_switch.sync_api.SyncSwitch.{op.name}`", *cells]
+            )
         table = _list_table("", ["Operation", *keys], rows)
         if not notes:
             return table
@@ -445,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",
@@ -492,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."""
 
@@ -538,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.post325 → 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.post325 → python_netgear_switch_library-0.0.post327}/docs/api/cli.rst

@@ -17,7 +17,7 @@ Switch and credential resolution
 --------------------------------
 
 The shared path the CLI *and* the MCP server both use to turn arguments,
-environment variables and an inventory into a ready `SyncSwitch`.
+environment variables and an inventory into a ready :py:obj:`~netgear_switch.sync_api.SyncSwitch`.
 
 .. automodule:: netgear_switch.cli.resolve
 

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post327}/docs/api/facades.rst

@@ -1,7 +1,7 @@
 Facades
 =======
 
-`SyncSwitch` and `AsyncSwitch` are the public entry points. They expose the same
+:py:obj:`~netgear_switch.sync_api.SyncSwitch` and :py:obj:`~netgear_switch.aio_api.AsyncSwitch` are the public entry points. They expose the same
 operations with the same arguments, and both resolve exactly one backend per
 call — see :doc:`../guide/concepts`.
 

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post327}/docs/api/index.rst

@@ -5,7 +5,7 @@ Complete reference for every module in the ``netgear_switch`` package,
 generated from the source.
 
 Most callers need only :doc:`core` (the data model, the registry, the
-capability oracle) and :doc:`facades` (`SyncSwitch` and `AsyncSwitch`).
+capability oracle) and :doc:`facades` (:py:obj:`~netgear_switch.sync_api.SyncSwitch` and :py:obj:`~netgear_switch.aio_api.AsyncSwitch`).
 The rest is there for anyone reading the source, extending a backend, or
 building on the protocol layer directly.
 

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post327}/docs/conf.py

@@ -75,8 +75,49 @@ exclude_patterns = [
 
 # Single backticks mean "a Python object", which is what most inline references
 # in this project are.
-default_role = "py:obj"
-nitpicky = False
+# Single backticks mean "literal", not "cross-reference". The library's
+# docstrings use them loosely for prose and shell fragments (`snmpget`,
+# `apt-get install -y snmp`, `type: ignore`), which a py:obj default role turns
+# into a flood of unresolvable references under nitpicky mode. Cross-references
+# in this documentation are always written with an explicit role, so nothing is
+# lost -- and filelinks still turns any literal naming a repository file into a
+# link to that file.
+default_role = "literal"
+
+# Every cross-reference must resolve, or the build fails. This is what keeps the
+# documentation actually hyperlinked: an unresolved `py:obj` renders as plain
+# text, so without this a whole page of API names can silently stop being links
+# -- which is exactly what happened when references were written as
+# `netgear_switch.SyncSwitch` (autodoc documents the class under its DEFINING
+# module, netgear_switch.sync_api, so the short path never resolved).
+nitpicky = True
+nitpick_ignore = [
+    # Base classes autodoc emits for our enums. They resolve through
+    # intersphinx, so these only matter for an offline build.
+    ("py:class", "enum.Enum"),
+    ("py:class", "enum.IntEnum"),
+]
+
+# Napoleon splits a docstring "Returns:"/"Attributes:" type on its first comma,
+# so a generic like ``tuple[NsdpPortStatus, ...]`` arrives as the fragment
+# ``'tuple[NsdpPortStatus``. These are mis-parses of a real annotation, not
+# broken links; the signatures autodoc renders from the actual type hints are
+# correct. Ignored by shape so a genuinely missing class still fails the build.
+nitpick_ignore_regex = [
+    ("py:class", r"^'?(?:tuple|list|dict|Mapping|Sequence|frozenset)\[.*"),
+    # A prose Attributes: entry whose type slot holds a sentence.
+    ("py:class", r"^The [A-Z].*"),
+]
+
+if os.environ.get("NGSW_DOCS_OFFLINE"):
+    # Standard-library targets that only resolve when intersphinx can fetch its
+    # inventory. Online (CI and Read the Docs) they link properly and stay
+    # strict; offline they would be noise.
+    nitpick_ignore += [
+        ("py:class", "argparse.ArgumentParser"),
+        ("py:func", "asyncio.to_thread"),
+        ("py:func", "importlib.import_module"),
+    ]
 maximum_signature_line_length = 88
 
 # -- Autodoc ------------------------------------------------------------------

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post327}/docs/development.rst

@@ -33,7 +33,7 @@ hardware, no network. Coverage is enforced at 90%.
      - That every backend of a model reports the same thing — the parity
        guarantee, checked rather than asserted in prose.
    * - ``tests/test_facade_equivalence.py``
-     - That `SyncSwitch` and `AsyncSwitch` stay in step.
+     - That :py:obj:`~netgear_switch.sync_api.SyncSwitch` and :py:obj:`~netgear_switch.aio_api.AsyncSwitch` stay in step.
    * - ``tests/test_capabilities.py``
      - That the support tables in these docs match what the code actually does,
        by driving every operation for real.
@@ -96,7 +96,7 @@ The rules
 
 * **Never declare something unsupported to finish a task.** If you cannot
   implement it, say so plainly — naming the model, backend and operation — and
-  leave behind no `UnsupportedCapabilityError` that lacks captured device output
+  leave behind no :py:obj:`~netgear_switch.errors.UnsupportedCapabilityError` 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

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post327}/docs/fake/internals.rst

@@ -65,7 +65,7 @@ The faces
    * - ``faces/cli.py``
      - nothing
      - In-process: implements the ``CliSession`` protocol directly, so no SSH
-       or telnet server is needed. Reached via `VirtualSwitch.cli_session`.
+       or telnet server is needed. Reached via :py:obj:`~netgear_switch.virtual.server.VirtualSwitch.cli_session`.
 
 ``faces/mibview.py`` deserves a note. It builds a **sorted** OID view from the
 state so GETNEXT and GETBULK have real lexicographic-ordering semantics rather
@@ -93,8 +93,8 @@ From a real switch to a seed
 
    ngsw --switch core capture tmp/core.json
 
-`ngsw capture <cli.capture>` records the switch's full state via
-`SyncSwitch.snapshot`, and — given live access and a raw-walk callable — the
+:doc:`ngsw capture <../cli>` records the switch's full state via
+:py:obj:`~netgear_switch.sync_api.SyncSwitch.snapshot`, and — given live access and a raw-walk callable — the
 reference ``snmpbulkwalk`` output alongside it. The result is a JSON file used
 **for reference** when hand-authoring a seed. It is deliberately not loaded
 directly by the mock.
@@ -186,7 +186,8 @@ Where things live
    * - ``src/netgear_switch/virtual/seed.py``
      - One seed builder per model.
    * - ``src/netgear_switch/virtual/server.py``
-     - ``VirtualSwitch``, the seed map, and ``serve_forever``.
+     - :py:class:`~netgear_switch.virtual.server.VirtualSwitch`, the seed map,
+       and :py:func:`~netgear_switch.virtual.server.serve_forever`.
    * - ``src/netgear_switch/virtual/faces/``
      - The protocol faces.
    * - ``tests/fixtures/captures/``
@@ -194,4 +195,5 @@ Where things live
    * - ``tests/virtual/``
      - Tests of the mock itself.
    * - ``tests/conftest.py``
-     - The per-model ``VirtualSwitch`` fixtures this project uses.
+     - The per-model :py:class:`~netgear_switch.virtual.server.VirtualSwitch`
+       fixtures this project uses.

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post327}/docs/fake/serving.rst

@@ -141,7 +141,7 @@ The FASTPATH CLI
 The CLI face is deliberately **in-process**: it implements the ``CliSession``
 protocol rather than binding an SSH or telnet listener, so there is no key
 exchange or terminal emulation to fight. It is reached through
-`VirtualSwitch.cli_session`, not over a socket, and so is not exposed by
+:py:obj:`~netgear_switch.virtual.server.VirtualSwitch.cli_session`, not over a socket, and so is not exposed by
 ``ngsw serve``. See :doc:`testing`.
 
 This library against a mock

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post327}/docs/fake/testing.rst

@@ -37,7 +37,7 @@ A pytest fixture
        finally:
            mock.stop()
 
-`VirtualSwitch` is also a context manager, which is usually enough:
+:py:obj:`~netgear_switch.virtual.server.VirtualSwitch` is also a context manager, which is usually enough:
 
 .. code-block:: python
 
@@ -127,7 +127,7 @@ Every backend takes an injected client:
        async: the same arguments to ``AsyncHttpClient``.
    * - CLI
      - ``cli_client=mock.cli_session()`` — **synchronous only**. The CLI
-       transports block, so :py:class:`~netgear_switch.AsyncSwitch` has no CLI
+       transports block, so :py:class:`~netgear_switch.aio_api.AsyncSwitch` has no CLI
        backend and takes no ``cli_client``.
 
 All four at once
@@ -136,31 +136,66 @@ All four at once
 One mock, one facade, three protocols — which is what makes cross-backend
 behaviour testable without hardware:
 
-.. code-block:: python
+.. tab-set::
 
-   from netgear_switch import Backend, SyncSwitch, get_model
-   from netgear_switch.protocols.http.endpoints import http_spec
-   from netgear_switch.transport.http.client import HttpClient
-   from netgear_switch.transport.sync.snmp_netsnmp_cli import NetsnmpCliClient
-   from netgear_switch.virtual.server import VirtualSwitch
+   .. tab-item:: Sync
+      :sync: sync
 
-   model = get_model("gsm7252ps")
-   with VirtualSwitch(model="gsm7252ps") as mock:
-       switch = SyncSwitch(
-           model,
-           host=mock.host,
-           snmp_client=NetsnmpCliClient(f"{mock.host}:{mock.port}", "public"),
-           http_client=HttpClient(
-               f"{mock.host}:{mock.http_port}", "password", http_spec(model)
-           ),
-           cli_client=mock.cli_session(),
-       )
-       snmp = switch.get_vlans(backend=Backend.SNMP)
-       http = switch.get_vlans(backend=Backend.HTTP)
-       cli = switch.get_vlans(backend=Backend.SSH)
+      .. code-block:: python
+
+         from netgear_switch import Backend, SyncSwitch, get_model
+         from netgear_switch.protocols.http.endpoints import http_spec
+         from netgear_switch.transport.http.client import HttpClient
+         from netgear_switch.transport.sync.snmp_netsnmp_cli import NetsnmpCliClient
+         from netgear_switch.virtual.server import VirtualSwitch
+
+         model = get_model("gsm7252ps")
+         with VirtualSwitch(model="gsm7252ps") as mock:
+             switch = SyncSwitch(
+                 model,
+                 host=mock.host,
+                 snmp_client=NetsnmpCliClient(f"{mock.host}:{mock.port}", "public"),
+                 http_client=HttpClient(
+                     f"{mock.host}:{mock.http_port}", "password", http_spec(model)
+                 ),
+                 cli_client=mock.cli_session(),
+             )
+             snmp = switch.get_vlans(backend=Backend.SNMP)
+             http = switch.get_vlans(backend=Backend.HTTP)
+             cli = switch.get_vlans(backend=Backend.SSH)
+
+             assert {v.vlan_id for v in snmp} == {v.vlan_id for v in http} \
+                 == {v.vlan_id for v in cli}
+
+   .. tab-item:: Async
+      :sync: async
+
+      .. code-block:: python
+
+         from netgear_switch import AsyncSwitch, Backend, get_model
+         from netgear_switch.protocols.http.endpoints import http_spec
+         from netgear_switch.transport.aio.snmp_pysnmp import PysnmpClient
+         from netgear_switch.transport.http.client import AsyncHttpClient
+         from netgear_switch.virtual.server import VirtualSwitch
 
-       assert {v.vlan_id for v in snmp} == {v.vlan_id for v in http} \
-           == {v.vlan_id for v in cli}
+         model = get_model("gsm7252ps")
+         with VirtualSwitch(model="gsm7252ps") as mock:
+             switch = AsyncSwitch(
+                 model,
+                 host=mock.host,
+                 snmp_client=PysnmpClient(mock.host, "public", port=mock.port),
+                 http_client=AsyncHttpClient(
+                     f"{mock.host}:{mock.http_port}", "password", http_spec(model)
+                 ),
+                 # No cli_client: the async facade has no CLI backend.
+             )
+             try:
+                 snmp = await switch.get_vlans(backend=Backend.SNMP)
+                 http = await switch.get_vlans(backend=Backend.HTTP)
+
+                 assert {v.vlan_id for v in snmp} == {v.vlan_id for v in http}
+             finally:
+                 await switch.aclose()
 
 .. code-block:: text
 
@@ -197,24 +232,53 @@ Testing that your code handles refusals
 The most valuable thing a faithful mock gives you is the *failure* paths. The
 mock refuses exactly what the hardware refuses, with the same message:
 
-.. code-block:: python
+.. tab-set::
 
-   from netgear_switch import SyncSwitch, UnsupportedCapabilityError, get_model
-   from netgear_switch.transport.sync.nsdp_udp import UdpNsdpClient
-   from netgear_switch.virtual.server import VirtualSwitch
+   .. tab-item:: Sync
+      :sync: sync
 
-   with VirtualSwitch(model="gs110emx") as mock:
-       switch = SyncSwitch(
-           get_model("gs110emx"),
-           host=mock.host,
-           nsdp_client=UdpNsdpClient(
-               mock.host, client_port=0, server_port=mock.port, timeout=2.0
-           ),
-       )
-       try:
-           switch.get_poe()
-       except UnsupportedCapabilityError as exc:
-           print(exc)
+      .. code-block:: python
+
+         from netgear_switch import SyncSwitch, UnsupportedCapabilityError, get_model
+         from netgear_switch.transport.sync.nsdp_udp import UdpNsdpClient
+         from netgear_switch.virtual.server import VirtualSwitch
+
+         with VirtualSwitch(model="gs110emx") as mock:
+             switch = SyncSwitch(
+                 get_model("gs110emx"),
+                 host=mock.host,
+                 nsdp_client=UdpNsdpClient(
+                     mock.host, client_port=0, server_port=mock.port, timeout=2.0
+                 ),
+             )
+             try:
+                 switch.get_poe()
+             except UnsupportedCapabilityError as exc:
+                 print(exc)
+
+   .. tab-item:: Async
+      :sync: async
+
+      .. code-block:: python
+
+         from netgear_switch import AsyncSwitch, UnsupportedCapabilityError, get_model
+         from netgear_switch.transport.aio.nsdp_udp import AsyncUdpNsdpClient
+         from netgear_switch.virtual.server import VirtualSwitch
+
+         with VirtualSwitch(model="gs110emx") as mock:
+             switch = AsyncSwitch(
+                 get_model("gs110emx"),
+                 host=mock.host,
+                 nsdp_client=AsyncUdpNsdpClient(
+                     mock.host, client_port=0, server_port=mock.port, timeout=2.0
+                 ),
+             )
+             try:
+                 await switch.get_poe()
+             except UnsupportedCapabilityError as exc:
+                 print(exc)
+             finally:
+                 await switch.aclose()
 
 .. code-block:: text
 
@@ -272,7 +336,7 @@ configuration:
 Crafting a scenario
 -------------------
 
-`VirtualSwitch.state` is an ordinary mutable dataclass. Edit it to produce the
+``VirtualSwitch.state`` is an ordinary mutable dataclass. Edit it to produce the
 condition you want to test — a dead link, a PoE fault, a full MAC table:
 
 .. code-block:: python

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post327}/docs/guide/concepts.rst

@@ -10,7 +10,7 @@ Models
 A switch model is a frozen `netgear_switch.registry.SwitchModel` record: its
 key, display name, class, port and PoE-port counts, the backends it exposes, its
 SNMP vendor OID subtree, and a few per-model protocol dialect flags. The whole
-registry lives in ``src/netgear_switch/registry.py``, and `get_model` resolves a
+registry lives in ``src/netgear_switch/registry.py``, and :py:obj:`~netgear_switch.registry.get_model` resolves a
 key (or an alias, such as ``s3300`` for ``gsm7228ps``) to the record.
 
 Models fall into three classes, which is what decides the protocols available:
@@ -83,11 +83,11 @@ Dispatch: exactly one backend, every time
          await switch.get_vlans(backend=Backend.HTTP)  # exactly HTTP, or an error
 
 When you **name** a backend, that backend runs. If the model does not have it,
-you get `UnsupportedCapabilityError` immediately. If it has it but cannot serve
-that operation, you get `UnsupportedCapabilityError` naming the backend you
+you get :py:obj:`~netgear_switch.errors.UnsupportedCapabilityError` immediately. If it has it but cannot serve
+that operation, you get :py:obj:`~netgear_switch.errors.UnsupportedCapabilityError` naming the backend you
 asked for.
 
-When you **do not** name one, `SyncSwitch.resolve_backend` picks the first
+When you **do not** name one, :py:obj:`~netgear_switch.sync_api.SyncSwitch.resolve_backend` picks the first
 backend the model declares, in the fixed order **SNMP → NSDP → HTTP → SSH →
 TELNET → CONSOLE**. The choice depends only on the model, never on the
 operation: the facade does not probe one backend, catch its refusal, and try
@@ -105,7 +105,8 @@ names the other backends you could pass:
 
    **The library will never answer over a protocol you did not get.** This was
    not always true, and the cost of the old behaviour is why the rule is
-   absolute. ``SyncSwitch`` used to loop over SNMP → NSDP → HTTP, silently
+   absolute. :py:class:`~netgear_switch.sync_api.SyncSwitch` used to loop over
+   SNMP → NSDP → HTTP, silently
    returning the next backend's answer when one raised. That hid a real defect
    for months — ``HttpReader.get_vlans`` returned no untagged ports at all on
    the managed switches, and nobody noticed because SNMP quietly answered
@@ -149,7 +150,7 @@ Verification status
 This project distinguishes what has been *measured* from what has been
 *assumed*, and the distinction is visible in the API.
 
-`SwitchModel.verified`
+:py:attr:`~netgear_switch.registry.SwitchModel.verified`
     ``False`` marks a model registered from a specification sheet, with no
     device of that kind ever reachable from this project. Such a model is
     **excluded from every support table** — see :doc:`../models/index` —
@@ -167,7 +168,7 @@ This project distinguishes what has been *measured* from what has been
 Errors
 ------
 
-All errors derive from `NetgearSwitchError`. The distinctions that matter:
+All errors derive from :py:obj:`~netgear_switch.errors.NetgearSwitchError`. The distinctions that matter:
 
 .. list-table::
    :header-rows: 1
@@ -175,36 +176,36 @@ All errors derive from `NetgearSwitchError`. The distinctions that matter:
 
    * - Error
      - Means
-   * - `UnsupportedCapabilityError`
+   * - :py:obj:`~netgear_switch.errors.UnsupportedCapabilityError`
      - This backend genuinely cannot do this, for this model. Never "not
        implemented yet" — a missing implementation is a bug to fix, not a
        device limitation to document.
-   * - `CredentialError`
+   * - :py:obj:`~netgear_switch.errors.CredentialError`
      - A credential is missing or wrong. Note that an SNMP agent **silently
        drops** an unauthorised request, so a wrong write community looks exactly
        like an unreachable host.
-   * - `WriteVerificationError`
+   * - :py:obj:`~netgear_switch.errors.WriteVerificationError`
      - The write was sent and accepted, but reading back did not show the
        intended value.
-   * - `ProtectedPortError`
+   * - :py:obj:`~netgear_switch.errors.ProtectedPortError`
      - The port is in this switch's ``protected_ports`` set. Pass ``force=True``
        to override.
-   * - `HttpAuthError`, `HttpUnexpectedPageError`
+   * - :py:obj:`~netgear_switch.errors.HttpAuthError`, :py:obj:`~netgear_switch.errors.HttpUnexpectedPageError`
      - Web-UI login failed, or a page did not look like what the model's dialect
        expects (usually a session that expired).
-   * - `CliCommandError`
+   * - :py:obj:`~netgear_switch.errors.CliCommandError`
      - The switch's CLI rejected a command; the message carries what it said.
 
 `NotImplementedError` appears in exactly one place — certificate upload on a
 model whose real mechanism is known but not wired to that backend. It is
-deliberately *not* `UnsupportedCapabilityError`, because the hardware can do it;
+deliberately *not* :py:obj:`~netgear_switch.errors.UnsupportedCapabilityError`, because the hardware can do it;
 see :doc:`../models/support`.
 
 Synchronous and asynchronous
 ----------------------------
 
-:py:class:`~netgear_switch.SyncSwitch` and
-:py:class:`~netgear_switch.AsyncSwitch` expose the same operations with the same
+:py:class:`~netgear_switch.sync_api.SyncSwitch` and
+:py:class:`~netgear_switch.aio_api.AsyncSwitch` expose the same operations with the same
 arguments and the same semantics. They share the model registry, the parsers and
 the backend-resolution seam in ``src/netgear_switch/_dispatch.py``; only the
 transports differ. ``tests/test_facade_equivalence.py`` asserts they stay in
@@ -214,18 +215,18 @@ step.
 
    **One backend is synchronous-only: the CLI.** All three CLI transports —
    SSH, telnet and the serial console — are blocking, and none has an async
-   twin, so :py:class:`~netgear_switch.AsyncSwitch` has no CLI backend at all.
+   twin, so :py:class:`~netgear_switch.aio_api.AsyncSwitch` has no CLI backend at all.
    Asking for one raises rather than quietly blocking the event loop::
 
       UnsupportedCapabilityError: model 'gsm7252ps' CLI reads are not available
       via the async facade (CLI is synchronous ...)
 
    That also rules out
-   :py:meth:`~netgear_switch.SyncSwitch.upload_certificate_scp` on the async
+   :py:meth:`~netgear_switch.sync_api.SyncSwitch.upload_certificate_scp` on the async
    facade, since the operation is CLI-based by nature. Use
-   :py:class:`~netgear_switch.SyncSwitch` for those, or wrap the call in
+   :py:class:`~netgear_switch.sync_api.SyncSwitch` for those, or wrap the call in
    :py:func:`asyncio.to_thread`.
 
    **The support tables in** :doc:`../models/support` **describe the
    synchronous facade.** Every SNMP, NSDP and HTTP entry holds for both; the CLI
-   columns apply to :py:class:`~netgear_switch.SyncSwitch` only.
+   columns apply to :py:class:`~netgear_switch.sync_api.SyncSwitch` only.