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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-netgear-switch-library
-Version: 0.0.post330
+Version: 0.0.post332
 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.post330 → python_netgear_switch_library-0.0.post332}/docs/api/cli.rst

@@ -16,8 +16,8 @@ Entry point
 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 :py:obj:`~netgear_switch.sync_api.SyncSwitch`.
+The shared path the CLI *and* the MCP server use to turn arguments, 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.post330 → python_netgear_switch_library-0.0.post332}/docs/api/index.rst

@@ -6,8 +6,8 @@ generated from the source.
 
 Most callers need only :doc:`core` (the data model, the registry, the
 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.
+The rest serves anyone reading the source, extending a backend, or building on
+the protocol layer directly.
 
 .. toctree::
    :maxdepth: 2
@@ -39,7 +39,7 @@ Layering
    transport/…                               sockets, subprocesses, sessions
 
 ``registry.py``, ``models.py``, ``errors.py``, ``capabilities.py`` and
-``config.py`` sit beside all of it: every layer uses them, none of them import a
+``config.py`` sit beside all of it: every layer uses them, none of them imports a
 layer.
 
 The package namespace

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/api/transport.rst

@@ -39,8 +39,8 @@ HTTP
 CLI
 ---
 
-Three transports for one command surface. ``CliSession`` is the protocol they
-all satisfy — and so does the mock's in-process CLI face.
+Three transports for one command surface. All three satisfy the ``CliSession``
+protocol — and so does the mock's in-process CLI face.
 
 .. automodule:: netgear_switch.transport.cli
 

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/cli.rst

@@ -14,7 +14,7 @@ state capture, and the mock switch daemons.
 Selecting a switch
 ------------------
 
-Two ways, and exactly one of them is needed:
+Two ways; pick exactly one:
 
 **From an inventory** — ``--switch NAME`` together with ``--config
 <inventory.toml>``; ``--switch`` without ``--config`` is an error. Credentials
@@ -31,7 +31,7 @@ Choosing the protocol
 ---------------------
 
 ``--backend snmp|nsdp|http|ssh|telnet|console`` runs the operation over exactly
-that protocol. If it cannot serve the operation the command fails saying so; it
+that protocol. If it cannot serve the operation, the command fails saying so; it
 is never re-routed. Without the flag, the model's default backend is used — see
 :doc:`guide/concepts`.
 
@@ -115,7 +115,7 @@ The ``--model`` is only a placeholder to carry the host and credentials;
 
    ngsw --switch core capture core-2026-07-31.json
 
-This is how this project's fixtures and mock seeds are produced — see
+This is how the project's fixtures and mock seeds are produced — see
 :doc:`fake/internals`.
 
 **Run mock switches for another tool to talk to**

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/conf.py

@@ -32,6 +32,9 @@ REPO_ROOT = DOCS_DIR.parent
 sys.path.insert(0, str(DOCS_DIR / "_ext"))
 sys.path.insert(0, str(REPO_ROOT / "src"))
 
+# Imported after the path is set up, so a bare checkout resolves it too.
+from netgear_switch.protocols.http.endpoints import HTTP_SPECS  # noqa: E402
+
 # -- Project ------------------------------------------------------------------
 
 project = "python-netgear-switch-library"
@@ -73,8 +76,6 @@ exclude_patterns = [
     "README.md",
 ]
 
-# Single backticks mean "a Python object", which is what most inline references
-# in this project are.
 # 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
@@ -84,6 +85,20 @@ exclude_patterns = [
 # link to that file.
 default_role = "literal"
 
+# Counted from the library rather than written into the prose, because a
+# hand-written count goes stale silently: this documentation claimed "Four
+# distinct login schemes and five HTML dialects" when there were five and seven.
+#
+# There is deliberately no count of read or write OPERATIONS here. How many
+# there are is not a useful thing for a reader to know -- the pages that used to
+# open with one are followed immediately by a table naming every operation, so
+# the number told nobody anything the table did not. What matters is that the
+# set is the same on every backend, which is what those pages now say.
+rst_prolog = f"""
+.. |scheme-count| replace:: {len({s.scheme for s in HTTP_SPECS.values()})}
+.. |dialect-count| replace:: {len({s.html_dialect for s in HTTP_SPECS.values()})}
+"""
+
 # 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

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/development.rst

@@ -75,7 +75,7 @@ honest:
     warnings fail the build, so the documentation cannot keep pointing at a file
     that has been renamed or deleted.
 
-Writing documentation, then, is mostly a matter of naming files in double
+Writing documentation is therefore mostly a matter of naming files in double
 backticks and letting the extension do the rest::
 
     See ``src/netgear_switch/registry.py`` for the registry.
@@ -92,7 +92,7 @@ a real device, writing a seed, and when a verification flag may be flipped.
 The rules
 ---------
 
-:doc:`guide/principles` is not optional reading for contributors. In particular:
+:doc:`guide/principles` is required reading for contributors. In particular:
 
 * **Never declare something unsupported to finish a task.** If you cannot
   implement it, say so plainly — naming the model, backend and operation — and
@@ -117,8 +117,8 @@ Releasing
 ---------
 
 A rolling release: every merge to ``main`` publishes to PyPI and the apt
-repository, with the version derived from git. There are no manual version
-bumps. See ``RELEASING.md``.
+repository, with the version derived from git — no manual version bumps. See
+``RELEASING.md``.
 
 Continuous integration
 ----------------------

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/fake/index.rst

@@ -24,8 +24,8 @@ Then, from any tool:
 
    snmpwalk -v2c -c public 127.0.0.1:36540 1.3.6.1.2.1.1
 
-Why it is worth trusting
-------------------------
+Why you can trust it
+--------------------
 
 A mock is only useful if it behaves like the thing it stands in for. This one is
 built to a strict rule: **where the fake differs from real hardware, the fake is
@@ -59,12 +59,12 @@ can only ever agree with that code.
 with a comment naming the host and firmware version it was observed on. A
 finding that lives only in a report gets regressed by the next change.
 
-The mock has also been cross-checked by tools that know nothing about this
-library: the third-party ProSafeLinux NSDP implementation decodes both mock
-switches completely with every value matching the seed, and the C tool
-``ngadmin`` validated the packet header — and surfaced a real four-byte
-sequence-number bug in the process, which was fixed. A mock validated only by
-the client that talks to it proves nothing.
+Tools that know nothing about this library have cross-checked it too. The
+third-party ProSafeLinux NSDP implementation decodes both mock switches
+completely, every value matching the seed; the C tool ``ngadmin`` validated the
+packet header — and surfaced a real four-byte sequence-number bug in the
+process, since fixed. A mock validated only by the client that talks to it
+proves nothing.
 
 What it is not
 --------------

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/fake/internals.rst

@@ -82,9 +82,9 @@ The HTML dialects differ enough that each has its own renderer:
 ``web_gs105pe.py`` and ``web_gs728tpp.py``, with shared pieces in ``web.py``.
 
 ``web_gs110emx_templates.py`` is pure data: single-line HTML strings copied
-byte-for-byte from real captures. It is excluded from lint precisely because
-there is no meaningful style to enforce on a literal capture, and reformatting it
-would destroy its value as evidence.
+byte-for-byte from real captures. It is excluded from lint precisely because a
+literal capture has no meaningful style to enforce, and reformatting it would
+destroy its value as evidence.
 
 From a real switch to a seed
 ----------------------------
@@ -96,8 +96,8 @@ From a real switch to a seed
 :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.
+**for reference** when hand-authoring a seed; the mock deliberately never loads
+it directly.
 
 That last point is the important one. A seed is written by hand *from* a
 capture, which forces a human to decide what each value means, and lets the
@@ -145,8 +145,8 @@ library:
 * **ngadmin** (a C implementation) validated the packet header — and surfaced a
   real four-byte sequence-number bug in the process, which was fixed.
 
-The harness for this is a veth pair into a network namespace, so NSDP's
-broadcast behaviour is exercised rather than bypassed.
+The harness is a veth pair into a network namespace, so NSDP's broadcast
+behaviour is exercised rather than bypassed.
 
 Adding a model
 --------------

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/fake/serving.rst

@@ -11,8 +11,8 @@ tool — in any language — can talk to one when hardware is unavailable.
    ngsw serve --all                                 # every registered model
 
 Each switch that comes up prints its model, bind address, the port it actually
-bound for each protocol, and the credentials it accepts. Then it blocks until
-interrupted, at which point every switch is stopped cleanly.
+bound for each protocol, and the credentials it accepts. The command then blocks
+until interrupted, stopping every switch cleanly.
 
 .. code-block:: text
 
@@ -29,9 +29,9 @@ interrupted, at which point every switch is stopped cleanly.
        community='public' http_password='password'
    serving 10 mock switch(es); press Ctrl-C to stop
 
-Which faces bind is decided by the model's registry entry, which is why the
-GS110EMX above offers NSDP and HTTP while the M7300 offers only SNMP — the mocks
-have exactly the backends the real switches have.
+The model's registry entry decides which faces bind, which is why the GS110EMX
+above offers NSDP and HTTP while the M7300 offers only SNMP — the mocks have
+exactly the backends the real switches have.
 
 Options
 -------
@@ -60,8 +60,8 @@ Options
 .. note::
 
    A pinned port is a single listener, so ``--port``/``--http-port`` are only
-   accepted when serving exactly one model. Serving several, leave them unset
-   and read the printed ports.
+   accepted when serving exactly one model. When serving several, leave them
+   unset and read the printed ports.
 
 One bad model never takes the fleet down: a switch that cannot bind is reported
 and skipped, and the rest keep serving.
@@ -140,9 +140,9 @@ 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
-:py:obj:`~netgear_switch.virtual.server.VirtualSwitch.cli_session`, not over a socket, and so is not exposed by
-``ngsw serve``. See :doc:`testing`.
+exchange or terminal emulation to fight. Reach it through
+:py:obj:`~netgear_switch.virtual.server.VirtualSwitch.cli_session`, not over a socket; ``ngsw serve`` therefore does
+not expose it. See :doc:`testing`.
 
 This library against a mock
 ---------------------------

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/fake/testing.rst

@@ -133,8 +133,8 @@ Every backend takes an injected client:
 All four at once
 ----------------
 
-One mock, one facade, three protocols — which is what makes cross-backend
-behaviour testable without hardware:
+One mock, one facade, three protocols — what makes cross-backend behaviour
+testable without hardware:
 
 .. tab-set::
 
@@ -207,9 +207,9 @@ behaviour testable without hardware:
    internal and link-aggregation interfaces (here, ifIndexes 418 and above)
    that the web UI's port table does not list, and this model's VLAN 1 has two
    ports SNMP shows as *configured* members while the web UI shows *current*
-   ones. Both are genuine properties of the two interfaces, not mock artefacts —
-   ``tests/test_cross_backend_equivalence.py`` restricts to physical ports and
-   pins the known difference explicitly rather than hiding it.
+   ones. Both are genuine properties of the two management interfaces, not mock
+   artefacts — ``tests/test_cross_backend_equivalence.py`` restricts to physical
+   ports and pins the known difference explicitly rather than hiding it.
 
 The CLI, with no SSH server
 ---------------------------
@@ -229,7 +229,7 @@ CLI backend.
 Testing that your code handles refusals
 ---------------------------------------
 
-The most valuable thing a faithful mock gives you is the *failure* paths. The
+The *failure* paths are the most valuable thing a faithful mock gives you. The
 mock refuses exactly what the hardware refuses, with the same message:
 
 .. tab-set::
@@ -358,7 +358,7 @@ condition you want to test — a dead link, a PoE fault, a full MAC table:
    binds, so a direct edit to ``state`` after ``start()`` is picked up by the
    HTTP, NSDP and CLI faces — which read the state live — but **not** by SNMP.
    Writes performed *through* a protocol rebuild the view and are consistent
-   everywhere; it is only out-of-band edits that need to happen first.
+   everywhere; only out-of-band edits need to happen first.
 
 Testing model detection
 -----------------------
@@ -384,8 +384,8 @@ with the wrong model:
                             Smart Switch with PoE+ and 4 10G uplinks',
                  sys_object_id='1.3.6.1.4.1.4526.100.10.19')
 
-Note it identified the switch by ``sysObjectID`` — which is the only way to tell
-this SKU apart from the S3300-28X, whose ``sysDescr`` text is indistinguishable.
+Identification came from ``sysObjectID`` — the only way to tell this SKU apart
+from the S3300-28X, whose ``sysDescr`` text is indistinguishable.
 
 Testing tools that are not this library
 ---------------------------------------
@@ -435,7 +435,7 @@ A common case: your exporter or check script takes a host and a community.
 
 Parametrising over models is where the fake earns its keep: the M4300-24X has no
 PoE at all, the GS728TPP has no vendor OIDs, and the S3300 answers to a different
-vendor subtree. Code that only ever met one switch tends to assume all three
+vendor subtree. Code written against a single switch tends to assume all three
 away.
 
 Choosing a model to test against
@@ -476,7 +476,7 @@ trustworthy:
   session for ordinary page ``GET``\ s. Real firmware does.
 * **Out-of-band state edits after** ``start()`` **are invisible to SNMP.** See
   the note above.
-* **The CLI face is in-process.** There is no SSH or telnet listener to test a
+* **The CLI face is in-process.** No SSH or telnet listener exists to test a
   transport against; it exercises the command surface, not the connection.
 * **Not every page of a real web UI exists** — only the pages the library uses.
 

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/guide/concepts.rst

@@ -13,7 +13,8 @@ SNMP vendor OID subtree, and a few per-model protocol dialect flags. The whole
 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:
+Models fall into three classes, and the class decides which protocols are
+available:
 
 Fully Managed (``FULLY_MANAGED``)
     M4300, GSM7252PS. Full SNMP with the Netgear ``4526.10`` vendor subtree, a
@@ -48,18 +49,18 @@ A backend is *the protocol an operation travels over*:
      - The Netgear Switch Discovery Protocol, over UDP. The only management
        protocol besides the web UI on Plus switches.
    * - ``HTTP``
-     - The switch's own web UI, scraped and driven as a browser would. Four
-       distinct login schemes and five HTML dialects across the fleet.
+     - The switch's own web UI, scraped and driven as a browser would.
+       |scheme-count| distinct login schemes and |dialect-count| page dialects
+       across the fleet.
    * - ``SSH`` / ``TELNET`` / ``CONSOLE``
      - The FASTPATH command line. One command surface reached over three
        transports; ``CONSOLE`` is a serial line rather than a network backend,
        so it is never registered on a model.
 
-The same nine read operations and ten write operations are implemented on every
-backend a model has. That is deliberate: if SNMP writes are locked down on your
-network, or the web UI is the only port through a firewall, you can pick a
-different protocol and get the same answer. :doc:`../models/support` lists the
-gaps that remain.
+Every read and every write is implemented on every backend a model has. That is
+deliberate: if SNMP writes are locked down on your network, or the web UI is the
+only port through a firewall, you can pick a different protocol and get the same
+answer. :doc:`../models/support` lists the gaps that remain.
 
 Dispatch: exactly one backend, every time
 -----------------------------------------
@@ -181,9 +182,9 @@ All errors derive from :py:obj:`~netgear_switch.errors.NetgearSwitchError`. The
        implemented yet" — a missing implementation is a bug to fix, not a
        device limitation to document.
    * - :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.
+     - A credential is missing or wrong. An SNMP agent **silently drops** an
+       unauthorised request, so a wrong write community looks exactly like an
+       unreachable host.
    * - :py:obj:`~netgear_switch.errors.WriteVerificationError`
      - The write was sent and accepted, but reading back did not show the
        intended value.

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/guide/configuration.rst

@@ -65,7 +65,7 @@ Per switch:
    * - ``nsdp.interface``
      - no
      - Interface to send NSDP from, e.g. ``eth0``. NSDP is broadcast-based, so
-       on a multi-homed host this matters.
+       this matters on a multi-homed host.
 
 Secret specs
 ------------
@@ -176,7 +176,7 @@ Plus switch reached over NSDP is never asked for an SNMP community.
 Protected ports
 ---------------
 
-``protected_ports`` is enforced by the library, not just the CLI. Every write
+``protected_ports`` is enforced by the library, not only the CLI. Every write
 that names a port checks it and raises :py:obj:`~netgear_switch.errors.ProtectedPortError` unless
 ``force=True``:
 
@@ -206,5 +206,5 @@ that names a port checks it and raises :py:obj:`~netgear_switch.errors.Protected
          await switch.set_port_enabled(49, False)              # ProtectedPortError
          await switch.set_port_enabled(49, False, force=True)  # proceeds
 
-It is the cheapest possible guard against disabling the uplink you are
+That one list is the cheapest guard against disabling the uplink you are
 connected through.

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/guide/installation.rst

@@ -62,8 +62,8 @@ The net-snmp system dependency
 ------------------------------
 
 The **synchronous** SNMP transport shells out to the net-snmp command-line
-tools rather than binding a Python SNMP library. They are a system package, not
-a Python dependency:
+tools rather than binding a Python SNMP library. Those tools are a system
+package, not a Python dependency:
 
 .. code-block:: sh
 
@@ -104,8 +104,8 @@ Versioning
 
 A **rolling release**. The version is derived from git by ``hatch-vcs``
 (``0.0.postN``, or ``X.Y.postN`` once a ``vX.Y`` tag exists); every merge to
-``main`` publishes to PyPI and to the apt repository. There are no manual
-version bumps — see ``RELEASING.md``.
+``main`` publishes to PyPI and to the apt repository. No manual version bumps —
+see ``RELEASING.md``.
 
 .. note::
 

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/guide/principles.rst

@@ -6,8 +6,8 @@ and each is stated here with the concrete failure that produced it — an abstra
 principle is easy to rationalise around, a remembered bug is not. The canonical
 text lives in ``CLAUDE.md`` at the repository root.
 
-They matter to *users* of the library because they explain what its behaviour
-guarantees, and what a message from it actually means.
+They matter to *users* because they explain what the library guarantees, and
+what a message from it actually means.
 
 1. Fail fast and loud
 ---------------------
@@ -52,7 +52,7 @@ is not a device limitation until proven otherwise. Remaining gaps are listed in
 *Why:* every managed switch was once marked as having no HTTP VLAN-membership
 path, so the web UI could neither report tagged/untagged membership nor write
 it — while the same file already carried the working page for a sibling model.
-There was also no CLI write backend at all, though the FASTPATH command
+The library also had no CLI write backend at all, though the FASTPATH command
 sequences were known to work.
 
 3. Models have parity
@@ -111,7 +111,7 @@ recorded — naming the firmware version it applies to.
 The :doc:`virtual switch <../fake/index>` exists so this library can be tested
 honestly without hardware. That only works if it is a **faithful** model of the
 real devices — including their refusals, quirks and ordering requirements, not
-just their happy paths.
+only their happy paths.
 
 * When live hardware differs from the mock, **the mock is wrong** and gets
   fixed. Never adjust a test's expectation to match a mock already known to be

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/guide/quickstart.rst

@@ -82,8 +82,8 @@ Either way:
                 netmask='255.255.255.0', gateway='10.1.5.1',
                 base_mac='E0:91:F5:0C:D6:DB')
 
-That output is a real GSM7252PS's data: the mock is seeded from a capture of
-the switch at 10.1.5.22, not from invented values. See :doc:`../fake/index`.
+That output is real GSM7252PS data: the mock is seeded from a capture of the
+switch at 10.1.5.22, not from invented values. See :doc:`../fake/index`.
 
 Talk to a real switch
 ---------------------
@@ -187,9 +187,9 @@ back to another protocol — see :doc:`concepts`.
 
 That the three agree is asserted, not assumed —
 ``tests/test_cross_backend_equivalence.py`` compares them for every model with
-more than one backend. They agree on the *physical* ports; SNMP additionally
-reports internal and link-aggregation interfaces that a web UI's port table does
-not list, and one model has a VLAN where SNMP shows configured members and the
+more than one backend. They agree on the *physical* ports; SNMP also reports
+internal and link-aggregation interfaces that a web UI's port table does not
+list, and one model has a VLAN where SNMP shows configured members and the
 web UI shows current ones. Both are real properties of the interfaces, and the
 tests pin them explicitly rather than papering over them.
 
@@ -198,7 +198,7 @@ Ask before you act
 
 :py:mod:`netgear_switch.capabilities` answers "can this model do this, over
 that?" without touching the switch. It is the same data that generates
-:doc:`../models/support`, and it is a plain function — there is nothing to await.
+:doc:`../models/support`, exposed as a plain function — nothing to await.
 
 .. code-block:: python
 
@@ -254,8 +254,8 @@ rules this project follows when testing writes against live hardware.
 Sweep a fleet
 -------------
 
-Where the two APIs genuinely differ is concurrency: the async facade can talk to
-a whole inventory at once.
+Concurrency is where the two APIs genuinely differ: the async facade talks to a
+whole inventory at once.
 
 .. tab-set::
 

{python_netgear_switch_library-0.0.post330 → python_netgear_switch_library-0.0.post332}/docs/guide/reading.rst

@@ -1,8 +1,8 @@
 Reading a switch
 ================
 
-Nine read operations, available on :py:obj:`~netgear_switch.sync_api.SyncSwitch` and :py:obj:`~netgear_switch.aio_api.AsyncSwitch` alike, each
-taking an optional ``backend=``. All return frozen dataclasses from
+Every read below is available on :py:obj:`~netgear_switch.sync_api.SyncSwitch` and :py:obj:`~netgear_switch.aio_api.AsyncSwitch` alike, and each
+takes an optional ``backend=``. They return frozen dataclasses from
 `netgear_switch.models`, identical whichever protocol produced them.
 
 The operations
@@ -129,7 +129,7 @@ Snapshots
          snap = await switch.snapshot()
          print(snap.model, snap.host, len(snap.ports), len(snap.vlans))
 
-Fields that backend cannot serve degrade to ``()`` or ``None``. They are *not*
+Fields the backend cannot serve degrade to ``()`` or ``None``. They are *not*
 re-read over another protocol — so a snapshot describes what one protocol
 really reports, rather than a blend of several. To compare protocols, take two
 snapshots:
@@ -158,7 +158,7 @@ snapshots:
          over_web = await switch.snapshot(backend=Backend.HTTP)
          assert over_snmp.vlans == over_web.vlans
 
-This is exactly what the cross-backend equivalence tests do; see
+The cross-backend equivalence tests do exactly this; see
 ``tests/test_cross_backend_equivalence.py``.
 
 .. note::
@@ -172,8 +172,8 @@ This is exactly what the cross-backend equivalence tests do; see
 Reading a fleet
 ---------------
 
-This is where the two APIs stop being interchangeable: the asynchronous facade
-reads every switch at once, the synchronous one reads them in turn.
+Here the two APIs stop being interchangeable: the asynchronous facade reads
+every switch at once, the synchronous one reads them in turn.
 
 .. tab-set::
 
@@ -257,8 +257,8 @@ Handling refusals
 Capturing what a switch says
 ----------------------------
 
-``ngsw capture`` writes a complete JSON record of a switch's readable state,
-which is how this project's fixtures and mock seeds are produced:
+``ngsw capture`` writes a complete JSON record of a switch's readable state.
+This project's fixtures and mock seeds are produced with it:
 
 .. code-block:: sh