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

docs/source/pcapkit/vendor/hip.rst

@@ -4,7 +4,7 @@
 
 .. module:: pcapkit.vendor.hip
 
-This module contains all constant enumerations of
+This module contains all vendor crawlers of
 :class:`~pcapkit.protocols.internet.hip.HIP` implementations. Available
 vendor crawlers include:
 

docs/source/pcapkit/vendor/ngap.rst

@@ -16,8 +16,9 @@ vendor crawlers include:
      - NGAP Protocol IE Identifiers [*]_
 
 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.
+specification rather than fetching a network registry: 3GPP publishes TS 38.413
+as a PDF, with no registry kept in step with it that a crawler could fetch
+(:issue:`880`).
 
 NGAP Elementary Procedure Codes
 ===============================

pcapkit/const/__init__.py

@@ -11,7 +11,7 @@
 # IANA registration
 from pcapkit.const.reg import *
 
-# Miscellanous
+# Miscellaneous
 from pcapkit.const.pcapng import *
 
 # per protocol

pcapkit/corekit/decorators.py

@@ -61,12 +61,12 @@ def seekset(func: 'Callable[Concatenate[ProtocolBase, P], R_seekset]') -> 'Calla
         This decorator function is designed for decorating *instance methods*.
 
     The decorator will keep the current offset of :attr:`self._file <pcapkit.protocols.protocol.Protocol._file>`,
-    then call the decorated function. Afterwards, it will rewind the  offset of
-    :attr:`self._file <pcapkit.protocols.protocol.Protocol._file>` to the original and returns the return value from
+    then call the decorated function. Afterwards, it will rewind the offset of
+    :attr:`self._file <pcapkit.protocols.protocol.Protocol._file>` to the original and return the return value from
     the decorated function.
 
     Note:
-        The decorated function should have following signature::
+        The decorated function should have the following signature::
 
             func(self: 'pcapkit.protocols.protocol.ProtocolBase',
                  *args: 'typing.Any', **kwargs: 'typing.Any') -> 'typing.Any'
@@ -110,7 +110,7 @@ def beholder(
     end-of-file :exc:`~pcapkit.utilities.exceptions.StructError`.
 
     Note:
-        The decorated function should have following signature::
+        The decorated function should have the following signature::
 
             func(self: 'pcapkit.protocols.protocol.ProtocolBase',
                  proto: 'int', length: 'typing.Optional[int]',
@@ -218,7 +218,7 @@ def prepare(func: 'Callable[Concatenate[Type[R_prepare], bytes | IO[bytes], Opti
     the revised version of parameter list to the original method.
 
     Note:
-        The decorated function should have following signature::
+        The decorated function should have the following signature::
 
             func(cls: 'typing.Type[pcapkit.protocols.schema.schema.Schema]',
                  data: 'bytes | typing.IO[bytes]',

pcapkit/corekit/fields/collections.py

@@ -336,7 +336,7 @@ def eool(self) -> 'int | StdlibEnum | AenumEnum':
 
     @property
     def option_padding(self) -> 'int':
-        """Length option padding data."""
+        """Length of option padding data."""
         return self._option_padding
 
     def __init__(self, length: 'int | Callable[[dict[str, Any]], int]' = lambda _: -1,
@@ -402,9 +402,11 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list
 
         Important:
             If the option list ended before the specified size limit,
-            set :attr:`self.option_padding <OptionField.option_padding>`
-            as the remaining length to the ``packet`` argument such that
-            the next fields can be aware of such informations.
+            :attr:`self.option_padding <OptionField.option_padding>` is set
+            to the remaining length, which :meth:`Schema.unpack
+            <pcapkit.protocols.schema.schema.Schema.unpack>` records in
+            ``packet`` as ``__option_padding__`` so that the next fields can
+            be aware of it.
 
         Raises:
             FieldValueError: If an option consumes nothing from ``buffer``, since

pcapkit/corekit/fields/misc.py

@@ -278,7 +278,8 @@ def protocol(self, protocol: 'Type[_TP] | str') -> 'None':
             from pcapkit.protocols import __proto__  # pylint: disable=import-outside-toplevel
 
             # NOTE: The registry is keyed on the upper-cased class name, both
-            # when it is seeded (``pcapkit/protocols/__init__.py:76``) and when
+            # when it is seeded (the loop over ``__all__`` in
+            # :mod:`pcapkit.protocols`) and when
             # ``pcapkit.foundation.registry.protocols.register_protocol`` adds to
             # it, so a name looked up in any other case would miss every time --
             # and a miss leaves ``_protocol`` as :obj:`None`, which the property

pcapkit/corekit/infoclass.py

@@ -267,9 +267,9 @@ class InfoMeta(abc.ABCMeta):
       .. note::
 
          This is implemented thru the :meth:`__new__` method, which will
-         inherit the additional and excluded field names from the base
-         classes, as well as populating the additional and excluded field
-         from the subclass attributes.
+         inherit the additional, excluded and included field names from the
+         base classes, as well as populating the additional, excluded and
+         included fields from the subclass attributes.
 
          .. code-block:: python
 
@@ -747,9 +747,9 @@ def to_dict(self) -> 'OrderedMultiDict[str, VT]':
         Important:
             We only convert nested :class:`Info` objects into :obj:`dict` if
             they are the direct value of the :class:`Info` object's attribute.
-            Should such :class:`Info` objects be nested within other data,
+            Should such :class:`Info` objects be nested within other data
             types, such as :obj:`list`, :obj:`tuple`, :obj:`set`, etc., we
-            shall not convert them into :obj:`dict` and remain them intact.
+            leave them intact rather than converting them into :obj:`dict`.
 
         Note:
             :meth:`from_dict` reverses the flattening only for keys whose type

pcapkit/corekit/io.py

@@ -10,7 +10,8 @@
 :class:`~pcapkit.corekit.io.PeekableStream`, which adds ``peek`` to a
 seekable stream, and :class:`~pcapkit.corekit.io.NamedStream`, which gives
 a stream a ``name``, as well as :func:`~pcapkit.corekit.io.advance`, which moves
-a stream past more octets than one read or seek can take.
+a stream past more octets than one read or seek can take, and
+:func:`~pcapkit.corekit.io.can_seek`, which tells whether a stream really seeks.
 
 """
 import io

pcapkit/corekit/packet.py

@@ -172,9 +172,11 @@ def to_dict(self) -> 'dict[str, Any]':
         """Convert the instance into :obj:`dict`.
 
         Returns:
-            The fields, with ``packet`` resolved if it had not been read yet --
-            a :obj:`dict` holding the placeholder would leak an implementation
-            detail into what is meant to be plain data.
+            The fields, as :meth:`Info.to_dict
+            <pcapkit.corekit.infoclass.Info.to_dict>` exports them, with
+            ``packet`` resolved if it had not been read yet -- an export
+            holding the placeholder would leak an implementation detail into
+            what is meant to be plain data.
 
         """
         self.__analyse__()

pcapkit/vendor/__init__.py

@@ -5,8 +5,8 @@
 
 .. module:: pcapkit.vendor
 
-This module contains all web crawlers of :mod:`pcapkit`, which are
-automatically generating the :mod:`pcapkit.const` module's constant
+This module contains all web crawlers of :mod:`pcapkit`, which
+automatically generate the :mod:`pcapkit.const` module's constant
 enumerations.
 
 The crawlers need the ``vendor`` extra, ``pip install "pypcapkit[vendor]"``.
@@ -101,7 +101,7 @@ def __getattr__(name: 'str') -> 'typing.NoReturn':
     # IANA registration
     from pcapkit.vendor.reg import *
 
-    # Miscellanous
+    # Miscellaneous
     from pcapkit.vendor.pcapng import *
 
     # per protocol

pcapkit/vendor/__main__.py

@@ -152,10 +152,9 @@ def _snapshot_and_restore(vendor: 'Type[Vendor]') -> 'Iterator[None]':
         #
         # The `else:` below is deliberate, not a style default pylint would
         # pick: collapsing it into an unindented statement after this whole
-        # `try` (as an earlier round of this same PR did) makes "cleanup
-        # only runs on success" a fact that has to be re-derived from
-        # "`raise` never falls through", rather than one the structure
-        # states directly -- and it silently stopped being true the moment
+        # `try` makes "cleanup only runs on success" a fact that has to be
+        # re-derived from "`raise` never falls through", rather than one the
+        # structure states directly -- and it silently stopped being true the moment
         # someone deleted that `raise`.  A mutation test proved it: with the
         # `raise` gone, the unindented `os.remove(backup)` still ran, after
         # `os.replace` had already renamed the backup away, so it raised
@@ -196,7 +195,7 @@ def run(vendor: 'Type[Vendor]') -> 'bool':
         # Unconditional, unlike the warning below: VendorRuntimeWarning is
         # filterable and VERBOSE defaults false, so without a plain print a CI
         # log that ignores warnings would show nothing at all about which
-        # target broke or why -- exactly the failure mode this fix exists for.
+        # target broke or why -- exactly the failure mode this print exists for.
         print(f'{vendor.__module__}.{vendor.__name__} failed: {error!r}', file=sys.stderr)
         warn(f'{vendor.__module__}.{vendor.__name__} <{error!r}>', VendorRuntimeWarning, stacklevel=2)
         return False

pcapkit/vendor/default.py

@@ -568,7 +568,7 @@ def _dest_path(cls) -> 'str':
         ``sys.exit(SomeCrawler())``, so running one from a second checkout, or
         from a module that never sits under ``vendor/`` at all, resolves
         :mod:`pcapkit.vendor` from wherever it is installed while
-        ``inspect.getfile(cls)`` names a file elsewhere entirely --  and
+        ``inspect.getfile(cls)`` names a file elsewhere entirely -- and
         :meth:`Vendor.__init__ <pcapkit.vendor.default.Vendor.__init__>` then opens that path with ``'w'``, silently
         truncating whatever :attr:`~Vendor.__module__` actually names instead of
         raising. So the escape is rejected outright, rather than trusted to
@@ -618,15 +618,15 @@ def _request(self) -> 'list[str]':
         arguments.
 
         The method will first try to *GET* the content of :attr:`~Vendor.LINK`.
-        Should any exception raised, it will first try with proxy settings from
+        Should any exception be raised, it will first try with proxy settings from
         :func:`~pcapkit.vendor.default.get_proxies`.
 
         .. note::
 
            Since some :attr:`~Vendor.LINK` links are from Wikipedia, etc., they
            might not be available in certain areas, e.g. the amazing PRC :)
 
-        Would proxies failed again, it will prompt for user intervention, i.e.
+        Should the proxies fail again, it will prompt for user intervention, i.e.
         it will use :func:`webbrowser.open` to open the page in browser for you, and
         you can manually load that page and save the HTML source at the location
         it provides.

pcapkit/vendor/hip/__init__.py

@@ -3,7 +3,7 @@
 """:class:`~pcapkit.protocols.internet.hip.HIP` Vendor crawlers
 ========================================================================
 
-.. module:: pcapkit.const.hip
+.. module:: pcapkit.vendor.hip
 
 This module contains all vendor crawlers of
 :class:`~pcapkit.protocols.internet.hip.HIP` implementations. Available

pcapkit/vendor/hip/certificate.py

@@ -2,7 +2,7 @@
 """HIP Certificate Types
 ===========================
 
-.. module:: pcapkit.const.hip.certificate
+.. module:: pcapkit.vendor.hip.certificate
 
 This module contains the vendor crawler for **HIP Certificate Types**,
 which is automatically generating :class:`pcapkit.const.hip.certificate.Certificate`.

pcapkit/vendor/hip/cipher.py

@@ -2,7 +2,7 @@
 """Cipher IDs
 ================
 
-.. module:: pcapkit.const.hip.cipher
+.. module:: pcapkit.vendor.hip.cipher
 
 This module contains the vendor crawler for **Cipher IDs**,
 which is automatically generating :class:`pcapkit.const.hip.cipher.Cipher`.

pcapkit/vendor/hip/di.py

@@ -2,7 +2,7 @@
 """DI-Types
 ==============
 
-.. module:: pcapkit.const.hip.di
+.. module:: pcapkit.vendor.hip.di
 
 This module contains the vendor crawler for **DI-Types**,
 which is automatically generating :class:`pcapkit.const.hip.di.DITypes`.

pcapkit/vendor/hip/ecdsa_curve.py

@@ -2,7 +2,7 @@
 """ECDSA Curve Label
 =======================
 
-.. module:: pcapkit.const.hip.ecdsa_curve
+.. module:: pcapkit.vendor.hip.ecdsa_curve
 
 This module contains the vendor crawler for **ECDSA Curve Label**,
 which is automatically generating :class:`pcapkit.const.hip.ecdsa_curve.ECDSACurve`.

pcapkit/vendor/hip/ecdsa_low_curve.py

@@ -2,7 +2,7 @@
 """ECDSA_LOW Curve Label
 ===========================
 
-.. module:: pcapkit.const.hip.ecdsa_low_curve
+.. module:: pcapkit.vendor.hip.ecdsa_low_curve
 
 This module contains the vendor crawler for **ECDSA_LOW Curve Label**,
 which is automatically generating :class:`pcapkit.const.hip.ecdsa_low_curve.ECDSALowCurve`.

pcapkit/vendor/hip/eddsa_curve.py

@@ -2,7 +2,7 @@
 """EdDSA Curve Label
 ===========================
 
-.. module:: pcapkit.const.hip.eddsa_curve
+.. module:: pcapkit.vendor.hip.eddsa_curve
 
 This module contains the vendor crawler for **EdDSA Curve Label**,
 which is automatically generating :class:`pcapkit.const.hip.eddsa_curve.EdDSACurve`.

pcapkit/vendor/hip/esp_transform_suite.py

@@ -2,7 +2,7 @@
 """ESP Transform Suite IDs
 =============================
 
-.. module:: pcapkit.const.hip.esp_transform_suite
+.. module:: pcapkit.vendor.hip.esp_transform_suite
 
 This module contains the vendor crawler for **ESP Transform Suite IDs**,
 which is automatically generating :class:`pcapkit.const.hip.esp_transform_suite.ESPTransformSuite`.

pcapkit/vendor/hip/group.py

@@ -2,7 +2,7 @@
 """Group IDs
 ===============
 
-.. module:: pcapkit.const.hip.group
+.. module:: pcapkit.vendor.hip.group
 
 This module contains the vendor crawler for **Group IDs**,
 which is automatically generating :class:`pcapkit.const.hip.group.Group`.

pcapkit/vendor/hip/hi_algorithm.py

@@ -2,7 +2,7 @@
 """HI Algorithm
 ==================
 
-.. module:: pcapkit.const.hip.hi_algorithm
+.. module:: pcapkit.vendor.hip.hi_algorithm
 
 This module contains the vendor crawler for **HI Algorithm**,
 which is automatically generating :class:`pcapkit.const.hip.hi_algorithm.HIAlgorithm`.

pcapkit/vendor/hip/hit_suite.py

@@ -2,7 +2,7 @@
 """HIT Suite ID
 ==================
 
-.. module:: pcapkit.const.hip.hit_suite
+.. module:: pcapkit.vendor.hip.hit_suite
 
 This module contains the vendor crawler for **HIT Suite ID**,
 which is automatically generating :class:`pcapkit.const.hip.hit_suite.HITSuite`.

pcapkit/vendor/hip/nat_traversal.py

@@ -2,7 +2,7 @@
 """HIP NAT Traversal Modes
 =============================
 
-.. module:: pcapkit.const.hip.nat_traversal
+.. module:: pcapkit.vendor.hip.nat_traversal
 
 This module contains the vendor crawler for **HIP NAT Traversal Modes**,
 which is automatically generating :class:`pcapkit.const.hip.nat_traversal.NATTraversal`.

pcapkit/vendor/hip/notify_message.py

@@ -2,7 +2,7 @@
 """Notify Message Types
 ==========================
 
-.. module:: pcapkit.const.hip.notify_message
+.. module:: pcapkit.vendor.hip.notify_message
 
 This module contains the vendor crawler for **Notify Message Types**,
 which is automatically generating :class:`pcapkit.const.hip.notify_message.NotifyMessage`.

pcapkit/vendor/hip/packet.py

@@ -2,7 +2,7 @@
 """HIP Packet Types
 ======================
 
-.. module:: pcapkit.const.hip.packet
+.. module:: pcapkit.vendor.hip.packet
 
 This module contains the vendor crawler for **HIP Packet Types**,
 which is automatically generating :class:`pcapkit.const.hip.packet.Packet`.

pcapkit/vendor/hip/parameter.py

@@ -2,7 +2,7 @@
 """HIP Parameter Types
 =========================
 
-.. module:: pcapkit.const.hip.parameter
+.. module:: pcapkit.vendor.hip.parameter
 
 This module contains the vendor crawler for **HIP Parameter Types**,
 which is automatically generating :class:`pcapkit.const.hip.parameter.Parameter`.

pcapkit/vendor/hip/registration.py

@@ -2,7 +2,7 @@
 """Registration Types
 ========================
 
-.. module:: pcapkit.const.hip.registration
+.. module:: pcapkit.vendor.hip.registration
 
 This module contains the vendor crawler for **Registration Types**,
 which is automatically generating :class:`pcapkit.const.hip.registration.Registration`.

pcapkit/vendor/hip/registration_failure.py

@@ -2,7 +2,7 @@
 """Registration Failure Types
 ================================
 
-.. module:: pcapkit.const.hip.registration_failure
+.. module:: pcapkit.vendor.hip.registration_failure
 
 This module contains the vendor crawler for **Registration Failure Types**,
 which is automatically generating :class:`pcapkit.const.hip.registration_failure.RegistrationFailure`.

pcapkit/vendor/hip/suite.py

@@ -2,7 +2,7 @@
 """Suite IDs
 ===============
 
-.. module:: pcapkit.const.hip.suite
+.. module:: pcapkit.vendor.hip.suite
 
 This module contains the vendor crawler for **Suite IDs**,
 which is automatically generating :class:`pcapkit.const.hip.suite.Suite`.

pcapkit/vendor/hip/transport.py

@@ -2,7 +2,7 @@
 """HIP Transport Modes
 =========================
 
-.. module:: pcapkit.const.hip.transport
+.. module:: pcapkit.vendor.hip.transport
 
 This module contains the vendor crawler for **HIP Transport Modes**,
 which is automatically generating :class:`pcapkit.const.hip.transport.Transport`.

pcapkit/vendor/ipv4/option_class.py

@@ -32,7 +32,7 @@
 class OptionClass(Vendor):
     """Option Classes"""
 
-    #: Value limit checker.s
+    #: Value limit checker.
     FLAG = 'isinstance(value, int) and 0 <= value <= 3'
 
     def request(self) -> 'dict[int, str]':  # type: ignore[override] # pylint: disable=arguments-differ