docs(corekit): third whole-repo pass over corekit, const and vendor (#1103)

docs/source/pcapkit/const/mh.rst

@@ -93,7 +93,7 @@ enumerations include:
    * - :class:`MH_CGASec <pcapkit.const.mh.cga_sec.CGASec>`
      - CGA SEC [*]_
    * - :class:`MH_BindingError <pcapkit.const.mh.binding_error.BindingError>`
-     - Bingding Error Status Code [*]_
+     - Binding Error Status Code [*]_
 
 Access Technology Type Option Type Values
 =========================================

docs/source/pcapkit/const/ngap.rst

@@ -15,7 +15,7 @@ enumerations include:
    * - :class:`NGAP_ProtocolIE <pcapkit.const.ngap.protocol_ie.ProtocolIE>`
      - NGAP Protocol IE Identifiers [*]_
 
-Both are automatically generated from |pycrate|_'s compiled NGAP
+Each is automatically generated from |pycrate|_'s compiled NGAP
 specification rather than an IANA-style registry -- see
 :mod:`pcapkit.vendor.ngap.procedure_code`'s module docstring for why.
 

docs/source/pcapkit/corekit/decorators.rst

@@ -13,7 +13,7 @@ decorators, including :func:`~pcapkit.corekit.decorators.seekset`,
 .. versionremoved:: 1.5.0
 
    ``pcapkit.utilities.decorators``, now :mod:`pcapkit.corekit.decorators`
-   (:issue:`1735`). :mod:`pcapkit.utilities` does not export the three
+   (:issue:`1735`). :mod:`pcapkit.utilities` does not export these
    decorators either.
 
 .. autodecorator:: pcapkit.corekit.decorators.seekset
@@ -24,7 +24,9 @@ decorators, including :func:`~pcapkit.corekit.decorators.seekset`,
 
 .. important::
 
-   All three decorators above are designed for decorating *class methods*.
+   The decorators above are designed for decorating *methods*: an instance
+   method of a protocol for :func:`seekset` and :func:`beholder`, and a
+   classmethod of a schema for :func:`prepare`.
    For more information, please refer to the documentation of each
    decorator function.
 

docs/source/pcapkit/corekit/enum.rst

@@ -3,7 +3,7 @@ Enumeration Base
 
 .. module:: pcapkit.corekit.enum
 
-:mod:`pcapkit.corekit.enum` contains the two bases every enumeration in this
+:mod:`pcapkit.corekit.enum` contains the bases every enumeration in this
 library inherits from: :class:`EnumLookup`, the *lookup* half shared by open
 registries and closed sets alike, and its subclass :class:`EnumRegistry`, which
 adds the *mutating* half every registry under :mod:`pcapkit.const` inherits.

docs/source/pcapkit/corekit/fields/misc.rst

@@ -25,6 +25,8 @@ Generic Data Fields
    :members:
    :show-inheritance:
 
+.. autofunction:: pcapkit.corekit.fields.misc.nested_packet_context
+
 .. autoclass:: pcapkit.corekit.fields.misc.PayloadField
    :members:
    :show-inheritance:
@@ -43,7 +45,7 @@ Type Variables
    :type: pcapkit.protocols.schema.schema.Schema
 
 .. data:: _TP
-   :type: pcapkit.protocols.protocol.Protocol
+   :type: pcapkit.protocols.protocol.ProtocolBase
 
 .. data:: _TN
    :type: pcapkit.corekit.sentinels.NoValueType

docs/source/pcapkit/corekit/fields/strings.rst

@@ -21,6 +21,10 @@ String-based Fields
    :members:
    :show-inheritance:
 
+.. autoclass:: pcapkit.corekit.fields.strings.DecodedString
+   :members:
+   :show-inheritance:
+
 .. autoclass:: pcapkit.corekit.fields.strings.BitField
    :members:
    :show-inheritance:
@@ -36,4 +40,4 @@ Type Variables
 --------------
 
 .. data:: _T
-   :type: str | bytes | python:dict[str, typing.Any]
+   :type: str | bytes | dict[str, typing.Any]

docs/source/pcapkit/corekit/infoclass.rst

@@ -14,7 +14,9 @@ classes :class:`~pcapkit.corekit.infoclass.MultiInfo` and
    :members:
    :show-inheritance:
 
-   :param \*args: Arbitrary positional arguments.
+   :param dict\_: Source data, read as by :meth:`~pcapkit.corekit.infoclass.Info.from_dict`,
+      except that no value is rebuilt into the :class:`~pcapkit.corekit.infoclass.Info`
+      subclass its key's annotation names.
    :param \*\*kwargs: Arbitrary keyword arguments.
 
    .. autoattribute:: __additional__
@@ -39,6 +41,10 @@ Internal Definitions
    :no-members:
    :show-inheritance:
 
+.. autoclass:: pcapkit.corekit.infoclass.FinalisedState
+   :members:
+   :show-inheritance:
+
 .. autoclass:: pcapkit.corekit.infoclass._MultiInfo
    :no-members:
    :show-inheritance:

docs/source/pcapkit/corekit/io.rst

@@ -5,7 +5,7 @@ I/O Objects
 
 :mod:`pcapkit.corekit.io` contains
 :class:`~pcapkit.corekit.io.SeekableReader`, a seekable customisation of
-:class:`io.BufferedReader`, and two stream proxies:
+:class:`io.BufferedReader`, and the stream proxies:
 :class:`~pcapkit.corekit.io.PeekableStream`, which adds ``peek`` to a seekable
 stream, and :class:`~pcapkit.corekit.io.NamedStream`, which gives a stream a
 ``name``.

docs/source/pcapkit/corekit/protochain.rst

@@ -10,10 +10,6 @@ Protocol Chain
    :no-members:
    :show-inheritance:
 
-   :param proto: New protocol class on the top stack.
-   :param alias: New protocol alias on the top stack.
-   :param basis: Original protocol chain as base stacks.
-
    .. autoproperty:: protocols
    .. autoproperty:: aliases
    .. autoproperty:: chain

docs/source/pcapkit/corekit/sentinels.rst

@@ -8,7 +8,7 @@ singleton sentinel this package defines for itself: a value recognised only by
 identity (``value is SENTINEL``), so it cannot be confused with a value a
 caller might legitimately pass.
 
-All four are defined here, and this is their only import path: the modules
+They are all defined here, and this is their only import path: the modules
 that use them do not re-export them (:issue:`1744`).
 
 .. versionadded:: 1.5.0
@@ -31,7 +31,7 @@ that use them do not re-export them (:issue:`1744`).
 
    :class:`AbsentType` and :data:`ABSENT` are **private** -- never imported outside
    :mod:`pcapkit.protocols.protocol`, and named in no module's ``__all__``. For
-   SCREAMING_SNAKE consistency with the other three sentinels (see
+   SCREAMING_SNAKE consistency with the other sentinels (see
    :ref:`sentinel-convention`), neither carries the leading underscore that would
    hide it from Sphinx, so both are documented below and marked private.
 

docs/source/pcapkit/vendor/mh.rst

@@ -93,7 +93,7 @@ vendor crawlers include:
    * - :class:`MH_CGASec <pcapkit.vendor.mh.cga_sec.CGASec>`
      - CGA SEC [*]_
    * - :class:`MH_BindingError <pcapkit.vendor.mh.binding_error.BindingError>`
-     - Bingding Error Status Code [*]_
+     - Binding Error Status Code [*]_
 
 Access Technology Type Option Type Values
 =========================================

docs/source/pcapkit/vendor/ngap.rst

@@ -15,7 +15,7 @@ vendor crawlers include:
    * - :class:`NGAP_ProtocolIE <pcapkit.vendor.ngap.protocol_ie.ProtocolIE>`
      - NGAP Protocol IE Identifiers [*]_
 
-Both source the assignment from |pycrate|_'s already-installed, compiled NGAP
+Each sources the assignment from |pycrate|_'s already-installed, compiled NGAP
 specification rather than fetching a network registry -- see the module
 docstring below for why.
 
@@ -28,7 +28,7 @@ This module contains the vendor crawler for **NGAP Elementary Procedure Codes**,
 which is automatically generating :class:`pcapkit.const.ngap.procedure_code.ProcedureCode`.
 
 .. autoclass:: pcapkit.vendor.ngap.procedure_code.ProcedureCode
-   :members: FLAG, LINK
+   :members: FLAG
    :show-inheritance:
 
 NGAP Protocol IE Identifiers
@@ -40,7 +40,7 @@ This module contains the vendor crawler for **NGAP Protocol IE Identifiers**,
 which is automatically generating :class:`pcapkit.const.ngap.protocol_ie.ProtocolIE`.
 
 .. autoclass:: pcapkit.vendor.ngap.protocol_ie.ProtocolIE
-   :members: FLAG, LINK
+   :members: FLAG
    :show-inheritance:
 
 .. rubric:: Footnotes

docs/source/pcapkit/vendor/pcapng.rst

@@ -29,14 +29,14 @@ vendor crawlers include:
 
 .. note::
 
-   The three crawlers that scrape a registry table --
+   The crawlers that scrape a registry table --
    :class:`BlockType <pcapkit.vendor.pcapng.block_type.BlockType>`,
    :class:`OptionType <pcapkit.vendor.pcapng.option_type.OptionType>` and
    :class:`RecordType <pcapkit.vendor.pcapng.record_type.RecordType>` -- all read
    revision ``-03`` of the draft, as each one's ``LINK`` below shows. Revision
    ``-02`` renders its registries as ASCII art inside ``<pre>`` and carries no
-   registry ``<table>`` at all, so the ``table-1`` through ``table-10`` ids the
-   three crawlers select on exist only in ``-03``, where the registries are real
+   registry ``<table>`` at all, so the ``table-1`` through ``table-10`` ids
+   these crawlers select on exist only in ``-03``, where the registries are real
    tables. The footnotes below point at ``-03`` for the same reason.
 
 Block Types

pcapkit/const/ftp/command.py

@@ -32,7 +32,7 @@ class FEATCode(EnumRegistry, StrEnum):
     .. note::
 
        Declares every FEAT keyword the IANA registry's own ``FEAT code``
-       column names -- the 5 group markers below plus the per-command
+       column names -- the group markers below plus the per-command
        keywords generated after them (data-driven, not hand-picked; see
        :meth:`~pcapkit.vendor.ftp.command.Command.process`) -- rather than
        minting the per-command ones at import time as an incidental side
@@ -117,9 +117,9 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'FEATCode':
         this is done, implementations are recommended to use upper case
         letters when transmitting the feature response."* A caller feeding a
         ``FEAT`` response line is therefore holding upper case by
-        recommendation, while 5 of this registry's 15 codes are registered in
-        lower case -- measured on the IANA CSV: 10 distinct all-upper-case
-        keywords against ``base``, ``feat``, ``hist``, ``nat6`` and ``secu``,
+        recommendation, while some of this registry's codes are registered in
+        lower case -- measured on the IANA CSV: ``base``, ``feat``, ``hist``,
+        ``nat6`` and ``secu``, against all-upper-case keywords for the rest,
         with none mixed. Without this override ``get('BASE')`` raised
         :exc:`KeyError`, which is the defect GitHub issue :issue:`903`'s audit found.
 
@@ -274,7 +274,7 @@ class Command(EnumRegistry, StrEnum):
        :meth:`register`, and ``get`` is not given enough information to create
        one. Concretely true here -- a bare wire command word carries no
        :attr:`feat`/:attr:`desc`/:attr:`type`/:attr:`conf`, so a minted member
-       had all four hollowed out to their defaults; :meth:`register` is the
+       had each of them hollowed out to its default; :meth:`register` is the
        path that can actually supply them.
 
     """
@@ -495,10 +495,10 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> 'Command':
         entirely --
         :meth:`~pcapkit.corekit.enum.EnumRegistry._unregistered_member`
         bypasses :meth:`__new__` (it calls
-        :class:`str`'s directly), so those four attributes would otherwise
+        :class:`str`'s directly), so those attributes would otherwise
         be absent and :meth:`__repr__` (which reads :attr:`desc`) would
         raise on the result. There is no more specific value to reconstruct
-        them from -- a bare wire command word carries none of the four,
+        them from -- a bare wire command word carries none of them,
         which is exactly the owner's reasoning for why ``get()``/
         ``_missing_`` must not mint one: :meth:`register` is the path that
         can actually supply them.

pcapkit/const/ftp/return_code.py

@@ -339,7 +339,7 @@ def _unregistered_member(cls, value: 'int', name: 'str') -> 'ReturnCode':
         same way :meth:`__new__` would, rather than leaving them unset --
         :meth:`~pcapkit.corekit.enum.EnumRegistry._unregistered_member`
         bypasses :meth:`__new__` entirely (it calls :class:`int`'s directly),
-        so those three attributes would otherwise be missing from the result
+        so those attributes would otherwise be missing from the result
         and :meth:`__str__`/:meth:`__repr__` would raise on it.
 
         Args:

pcapkit/const/http/method.py

@@ -187,7 +187,7 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> 'Method':
         :meth:`__new__` itself would, rather than missing entirely --
         :meth:`~pcapkit.corekit.enum.EnumRegistry._unregistered_member`
         bypasses :meth:`__new__` (it calls :class:`str`'s directly), so
-        those two attributes would otherwise be absent. There is no more
+        those attributes would otherwise be absent. There is no more
         specific value to reconstruct them from -- a bare wire method verb
         carries neither, which is exactly the owner's reasoning for why
         ``get()``/``_missing_`` must not mint one: :meth:`register` is the
@@ -329,8 +329,8 @@ def _missing_(cls, value: 'str') -> 'Method':
                 :meth:`get`, which is case-**sensitive** per
                 :rfc:`9110#section-9.1`. The split was ruled deliberate on
                 GitHub issue :issue:`896`; GitHub issue :issue:`908` is the pointer between
-                the two, so a reader of this one file is not left with two
-                contradictory rationales and nothing tying them together.
+                the two, so the two rationales are not left contradicting each
+                other with nothing tying them together.
 
         """
         if not isinstance(value, str):

pcapkit/const/mh/__init__.py

@@ -94,7 +94,7 @@
    * - :class:`MH_CGASec <pcapkit.const.mh.cga_sec.CGASec>`
      - CGA SEC [*]_
    * - :class:`MH_BindingError <pcapkit.const.mh.binding_error.BindingError>`
-     - Bingding Error Status Code [*]_
+     - Binding Error Status Code [*]_
 
 .. [*] https://www.iana.org/assignments/mobility-parameters/mobility-parameters.xhtml#mobility-parameters-1
 .. [*] https://www.iana.org/assignments/mobility-parameters/mobility-parameters.xhtml#mobility-parameters-2

pcapkit/const/ngap/__init__.py

@@ -16,11 +16,12 @@
    * - :class:`NGAP_ProtocolIE <pcapkit.const.ngap.protocol_ie.ProtocolIE>`
      - NGAP Protocol IE Identifiers [*]_
 
-Both are automatically generated from
+They are automatically generated by
 :mod:`pcapkit.vendor.ngap.procedure_code` and
-:mod:`pcapkit.vendor.ngap.protocol_ie`, which source the assignment from
+:mod:`pcapkit.vendor.ngap.protocol_ie` respectively, which source the assignment from
 |pycrate|_'s compiled NGAP specification rather than a network registry --
-see that module's docstring for why, and GitHub issue :issue:`880` for the ruling.
+see :mod:`pcapkit.vendor.ngap.procedure_code`'s docstring for why, and GitHub
+issue :issue:`880` for the ruling.
 
 .. [*] 3GPP TS 38.413
 .. [*] 3GPP TS 38.413

pcapkit/const/reg/apptype/__init__.py

@@ -157,9 +157,9 @@ def __repr__(self) -> 'str':
 
 # NOTE: this is what makes ``AppType.get(port, proto=...)`` work on the base
 # class, which is where every caller in the library addresses it. It cannot live
-# in ``apptype.py``: that module is imported *by* all four registries, so it
-# cannot import them back. Here is the first point at which all four exist, or
-# for the lazy two, where to import them from.
+# in ``apptype.py``: that module is imported *by* every per-transport registry,
+# so it cannot import them back. Here is the first point at which all of them
+# exist, or, for the lazy ones, where to import them from.
 AppType.__registries__ = _Registries({
     TransportProtocol.tcp: ModuleDescriptor(f'{__name__}.tcp', _LAZY['tcp']),
     TransportProtocol.udp: ModuleDescriptor(f'{__name__}.udp', _LAZY['udp']),
@@ -187,7 +187,7 @@ class is bound here before it is returned.
 
 
 def __dir__() -> 'list[str]':
-    """The names an eager import of all four registries would list."""
+    """The names an eager import of every per-transport registry would list."""
     helpers = {'importlib', 'sys', 'TYPE_CHECKING', 'ModuleDescriptor', '_LAZY', '_Registries',
                '__getattr__', '__dir__'}
     return sorted({*globals(), *_LAZY, *_LAZY.values()} - helpers)