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

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

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

@@ -399,7 +399,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

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post326}/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.post326}/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.post326}/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.post326}/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.post326}/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.post326}/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.post326}/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.post326}/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.post326}/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.

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post326}/docs/guide/configuration.rst

@@ -2,7 +2,7 @@ Inventories and credentials
 ===========================
 
 Hosts, models and credentials belong in an inventory file, not in your code or
-your shell history. `load_inventory` reads a TOML file into
+your shell history. :py:obj:`~netgear_switch.config.load_inventory` reads a TOML file into
 ``{name: SwitchConfig}``; the ``ngsw`` CLI and the MCP server both use it, via
 the same resolver.
 
@@ -70,7 +70,7 @@ Per switch:
 Secret specs
 ------------
 
-Any value marked "secret spec" above is resolved by `resolve_secret`, which
+Any value marked "secret spec" above is resolved by :py:obj:`~netgear_switch.config.resolve_secret`, which
 accepts three forms:
 
 .. list-table::
@@ -80,16 +80,16 @@ accepts three forms:
    * - Form
      - Behaviour
    * - ``${NAME}``
-     - Read environment variable ``NAME``. `CredentialError` if unset.
+     - Read environment variable ``NAME``. :py:obj:`~netgear_switch.errors.CredentialError` if unset.
    * - ``!command args``
      - Run the command (split with ``shlex``, no shell) and take its stdout,
-       stripped. A 10-second timeout; a non-zero exit raises `CredentialError`
+       stripped. A 10-second timeout; a non-zero exit raises :py:obj:`~netgear_switch.errors.CredentialError`
        with the command's stderr.
    * - anything else
      - The literal secret.
 
 Prefer the first two. **If any secret in the file is a literal, the file's
-permissions are checked** and `load_inventory` raises `ConfigError` unless the
+permissions are checked** and :py:obj:`~netgear_switch.config.load_inventory` raises :py:obj:`~netgear_switch.errors.ConfigError` unless the
 file is unreadable by group and other:
 
 .. code-block:: text
@@ -97,7 +97,7 @@ file is unreadable by group and other:
    ConfigError: inventory.toml has insecure permissions 0o644; chmod 600 it
    (contains a literal secret)
 
-That check is `ensure_secure_file`, and it only fires when a literal is present
+That check is :py:obj:`~netgear_switch.config.ensure_secure_file`, and it only fires when a literal is present
 — a file containing only ``${VAR}`` and ``!command`` specs needs no special
 mode.
 
@@ -136,7 +136,7 @@ Using an inventory
          finally:
              await switch.aclose()
 
-`SwitchConfig.snmp_write_community` and `SwitchConfig.http_password` resolve
+:py:attr:`~netgear_switch.config.SwitchConfig.snmp_write_community` and :py:attr:`~netgear_switch.config.SwitchConfig.http_password` resolve
 their specs on demand and take an explicit ``env=`` mapping, which makes them
 straightforward to test.
 
@@ -177,7 +177,7 @@ Protected ports
 ---------------
 
 ``protected_ports`` is enforced by the library, not just the CLI. Every write
-that names a port checks it and raises `ProtectedPortError` unless
+that names a port checks it and raises :py:obj:`~netgear_switch.errors.ProtectedPortError` unless
 ``force=True``:
 
 .. tab-set::

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post326}/docs/guide/installation.rst

@@ -32,7 +32,7 @@ in an HTTP stack, and vice versa.
      - Needed for
    * - ``[async]``
      - :pypi:`pysnmp`
-     - The asynchronous SNMP transport used by `AsyncSwitch`.
+     - The asynchronous SNMP transport used by :py:obj:`~netgear_switch.aio_api.AsyncSwitch`.
    * - ``[http]``
      - :pypi:`httpx`
      - Every web-UI backend, synchronous and asynchronous.

{python_netgear_switch_library-0.0.post325 → python_netgear_switch_library-0.0.post326}/docs/guide/quickstart.rst

@@ -9,8 +9,8 @@ faithful mock switches, and the example points at one.
    Every example below appears in **synchronous** and **asynchronous** form.
    Choosing one switches every example on the page, and the choice is
    remembered as you move around the site.
-   :py:class:`~netgear_switch.SyncSwitch` and
-   :py:class:`~netgear_switch.AsyncSwitch` expose the same operations with the
+   :py:class:`~netgear_switch.sync_api.SyncSwitch` and
+   :py:class:`~netgear_switch.aio_api.AsyncSwitch` expose the same operations with the
    same arguments; only the transports differ.
 
 Talk to a mock in-process
@@ -88,8 +88,8 @@ the switch at 10.1.5.22, not from invented values. See :doc:`../fake/index`.
 Talk to a real switch
 ---------------------
 
-The first argument is a :py:class:`~netgear_switch.SwitchModel`, which
-:py:func:`~netgear_switch.get_model` resolves from a registry key (``ngsw
+The first argument is a :py:class:`~netgear_switch.registry.SwitchModel`, which
+:py:func:`~netgear_switch.registry.get_model` resolves from a registry key (``ngsw
 models`` lists them all).
 
 .. tab-set::