docs(corekit): version directives and render fixes (#1103)

docs/source/pcapkit/const/ipv6.rst

@@ -125,7 +125,7 @@ Simplified Multicast Forwarding Duplicate Packet Detection (``SMF_DPD``) Options
 
 .. module:: pcapkit.const.ipv6.smf_dpd_mode
 
-This module contains the constant enumeration for **Simplified Multicast Forwarding Duplicate Packet Detection (``SMF_DPD``) Options**,
+This module contains the constant enumeration for **Simplified Multicast Forwarding Duplicate Packet Detection (SMF_DPD) Options**,
 which is automatically generated from :class:`pcapkit.vendor.ipv6.smf_dpd_mode.SMFDPDMode`.
 
 .. autoclass:: pcapkit.const.ipv6.smf_dpd_mode.SMFDPDMode

docs/source/pcapkit/corekit/decorators.rst

@@ -8,11 +8,13 @@ decorators, including :func:`~pcapkit.corekit.decorators.seekset`,
 :func:`~pcapkit.corekit.decorators.beholder` and
 :func:`~pcapkit.corekit.decorators.prepare`.
 
-.. note::
+.. versionadded:: 1.5.0
 
-   This module was ``pcapkit.utilities.decorators`` until :issue:`1735` moved it
-   here, and :mod:`pcapkit.utilities` no longer exports the three decorators.
-   Nothing is left at the old path, so import them from this module.
+.. versionremoved:: 1.5.0
+
+   ``pcapkit.utilities.decorators``, now :mod:`pcapkit.corekit.decorators`
+   (:issue:`1735`). :mod:`pcapkit.utilities` does not export the three
+   decorators either.
 
 .. autodecorator:: pcapkit.corekit.decorators.seekset
 

docs/source/pcapkit/corekit/enum.rst

@@ -8,15 +8,17 @@ 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.
 
+.. versionadded:: 1.5.0
+
+   The ``get`` each :mod:`pcapkit.const` enumeration carried as generated text
+   moves onto :class:`EnumLookup`, and :class:`EnumRegistry` adds ``register``,
+   which is how a member is minted at runtime: outside ``CGAType``, looking up
+   an unknown value does not mint one (:issue:`775`).
+
 .. autoclass:: pcapkit.corekit.enum.EnumLookup
    :members:
    :show-inheritance:
 
-   .. automethod:: _validate_value
-
 .. autoclass:: pcapkit.corekit.enum.EnumRegistry
    :members:
    :show-inheritance:
-
-   .. automethod:: _extend
-   .. automethod:: _unregistered_member

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

@@ -8,6 +8,11 @@ a capture file's byte order out of the packet data. It is shared by the PCAP
 frame header (:mod:`~pcapkit.protocols.schema.misc.pcap.frame`) and the PCAP-NG
 blocks (:mod:`~pcapkit.protocols.schema.misc.pcapng`).
 
+.. versionadded:: 1.5.0
+
+   :func:`byteorder_callback` moves here from
+   :mod:`pcapkit.protocols.schema.misc.pcap.frame` (:issue:`1711`).
+
 Auxiliary Functions
 -------------------
 

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

@@ -3,25 +3,12 @@ Base Fields
 
 .. module:: pcapkit.corekit.fields.field
 
-.. versionremoved:: 1.5.0
-
-   Moved to :mod:`pcapkit.utilities.config` (:issue:`1726`):
-
-   * ``pcapkit.corekit.fields.field._MAX_ZERO_PAD_LENGTH``, now
-     :data:`pcapkit.utilities.config.MAX_ZERO_PAD_LENGTH`, set with
-     :envvar:`PCAPKIT_MAX_ZERO_PAD_LENGTH`;
-   * ``pcapkit.corekit.fields.field._MAX_ZERO_PAD_SHORTFALL``, now
-     :data:`pcapkit.utilities.config.MAX_ZERO_PAD_SHORTFALL`, set with
-     :envvar:`PCAPKIT_MAX_ZERO_PAD_SHORTFALL`;
-   * ``pcapkit.corekit.fields.field._ZERO_PAD_BUDGET_RATIO``, now
-     :data:`pcapkit.utilities.config.ZERO_PAD_BUDGET_RATIO`, set with
-     :envvar:`PCAPKIT_ZERO_PAD_BUDGET_RATIO`.
-
 .. versionremoved:: 1.5.0
 
    ``pcapkit.corekit.fields.field.NoValueType``, now
    :class:`pcapkit.corekit.sentinels.NoValueType` (:issue:`922`,
-   :issue:`1744`).
+   :issue:`1744`), and ``pcapkit.corekit.fields.field.NoValue``, now
+   :data:`pcapkit.corekit.sentinels.NO_VALUE` (:issue:`937`).
 
 .. autoclass:: pcapkit.corekit.fields.field.Field
    :members:

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

@@ -3,6 +3,13 @@ IP Address Fields
 
 .. module:: pcapkit.corekit.fields.ipaddress
 
+.. versionchanged:: 1.5.0
+
+   Every field here rejects a :obj:`bool` with
+   :exc:`~pcapkit.utilities.exceptions.FieldValueError`, where an IPv4 field
+   packed :obj:`True` and :obj:`False` as ``0.0.0.1`` and ``0.0.0.0``
+   (:issue:`491`).
+
 IP Addresses
 ~~~~~~~~~~~~
 

docs/source/pcapkit/corekit/infoclass.rst

@@ -17,9 +17,6 @@ classes :class:`~pcapkit.corekit.infoclass.MultiInfo` and
    :param \*args: Arbitrary positional arguments.
    :param \*\*kwargs: Arbitrary keyword arguments.
 
-   .. automethod:: __init_subclass__
-   .. automethod:: __post_init__
-
    .. autoattribute:: __additional__
       :no-value:
    .. autoattribute:: __excluded__

docs/source/pcapkit/corekit/io.rst

@@ -10,12 +10,6 @@ I/O Objects
 stream, and :class:`~pcapkit.corekit.io.NamedStream`, which gives a stream a
 ``name``.
 
-.. versionremoved:: 1.5.0
-
-   ``pcapkit.corekit.io._READ_CHUNK``, now
-   :data:`pcapkit.utilities.config.READ_CHUNK`, set with
-   :envvar:`PCAPKIT_READ_CHUNK` (:issue:`1726`).
-
 .. autoclass:: pcapkit.corekit.io.SeekableReader
    :no-members:
    :show-inheritance:

docs/source/pcapkit/corekit/multidict.rst

@@ -35,6 +35,8 @@ values per key, based on the `Werkzeug`_ project.
    :no-special-members: __init__
    :show-inheritance:
 
+   .. automethod:: deepcopy
+
 Type Variables
 --------------
 

docs/source/pcapkit/corekit/sentinels.rst

@@ -11,6 +11,12 @@ caller might legitimately pass.
 All four are 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
+
+   :class:`NoValueType` moves here from :mod:`pcapkit.corekit.fields.field`
+   (:issue:`911`), and :data:`NO_VALUE` replaces its ``NoValue`` there
+   (:issue:`937`).
+
 .. autoclass:: pcapkit.corekit.sentinels.NullType
 .. autodata:: pcapkit.corekit.sentinels.NULL
 

docs/source/pcapkit/vendor/ipv6.rst

@@ -118,7 +118,7 @@ Simplified Multicast Forwarding Duplicate Packet Detection (``SMF_DPD``) Options
 
 .. module:: pcapkit.vendor.ipv6.smf_dpd_mode
 
-This module contains the vendor crawler for **Simplified Multicast Forwarding Duplicate Packet Detection (``SMF_DPD``) Options**,
+This module contains the vendor crawler for **Simplified Multicast Forwarding Duplicate Packet Detection (SMF_DPD) Options**,
 which is automatically generating :class:`pcapkit.const.ipv6.smf_dpd_mode.SMFDPDMode`.
 
 .. autoclass:: pcapkit.vendor.ipv6.smf_dpd_mode.SMFDPDMode

pcapkit/const/ftp/command.py

@@ -469,8 +469,9 @@ def _unregistered_member(cls, value: 'str', name: 'str') -> 'Command':
 
         Leaves :attr:`feat`, :attr:`desc`, :attr:`type` and :attr:`conf` at
         the same defaults :meth:`__new__` itself would, rather than missing
-        entirely -- :meth:`~pcapkit.corekit.enum.EnumRegistry.
-        _unregistered_member` bypasses :meth:`__new__` (it calls
+        entirely --
+        :meth:`~pcapkit.corekit.enum.EnumRegistry._unregistered_member`
+        bypasses :meth:`__new__` (it calls
         :class:`str`'s directly), so those four 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

pcapkit/const/http/method.py

@@ -24,16 +24,14 @@
 class Method(EnumRegistry, StrEnum):
     """[Method] HTTP Method
 
-    .. note::
+    .. versionchanged:: 1.5.0
 
-       Neither ``_missing_`` nor ``get()`` mints any more. The owner ruled on
-       GitHub issue :issue:`860` that ``get`` should not mint: only IANA-registered
-       values are legitimate members, a new one is properly created through
-       :meth:`register`, and ``get`` is not given enough information to create
-       one. Concretely true here -- a bare wire method verb carries no
-       :attr:`safe`/:attr:`idempotent`, so minting one used to register a
-       permanent member with both hollowed out to their defaults;
-       :meth:`register` is the path that can actually supply them.
+       Neither ``_missing_`` nor ``get()`` mints a member, per the owner's
+       ruling on GitHub issue :issue:`860`: only IANA-registered values are
+       legitimate members, and a new one is created through :meth:`register`,
+       which can supply :attr:`safe` and :attr:`idempotent` where a bare wire
+       method verb carries neither. ``get()`` matches ``key`` case-sensitively,
+       as :rfc:`9110` makes the method token (:issue:`896`).
 
     """
 
@@ -263,8 +261,8 @@ def get(cls, key: 'str', default: 'Optional[str]' = None) -> 'Method':
         Args:
             key: Key to get enum item. Looked up case-**sensitively**,
                 per :rfc:`9110#section-9.1` -- the method token is
-                case-sensitive, unlike :meth:`~pcapkit.const.ftp.command.
-                Command.get`'s equivalent override, which stays
+                case-sensitive, unlike
+                :meth:`~pcapkit.const.ftp.command.Command.get`'s equivalent override, which stays
                 case-insensitive because :rfc:`959#section-5` says FTP
                 command codes are not. Checked against both member names
                 and values, via the base's own precedence -- name before

pcapkit/const/http/status_code.py

@@ -253,8 +253,9 @@ def _unregistered_member(cls, value: 'int', name: 'str') -> 'StatusCode':
         """Build a member absent from this registry's own lookup tables.
 
         Reconstructs :attr:`message` the same way :meth:`__new__` would,
-        rather than leaving it unset -- :meth:`~pcapkit.corekit.enum.
-        EnumRegistry._unregistered_member` bypasses :meth:`__new__` entirely
+        rather than leaving it unset --
+        :meth:`~pcapkit.corekit.enum.EnumRegistry._unregistered_member`
+        bypasses :meth:`__new__` entirely
         (it calls :class:`int`'s directly), so :attr:`message` would
         otherwise be missing from the result and :meth:`__str__` would raise
         on it.

pcapkit/const/ipv6/extension_header.py

@@ -18,7 +18,14 @@
 
 
 class ExtensionHeader(EnumRegistry, IntEnum):
-    """[ExtensionHeader] IPv6 Extension Header Types"""
+    """[ExtensionHeader] IPv6 Extension Header Types
+
+    .. versionchanged:: 1.5.0
+
+       Generated from IANA's *IPv6 Extension Header Types* registry, where it
+       was generated from the protocol-numbers registry (:issue:`925`).
+
+    """
 
     #: HOPOPT, IPv6 Hop-by-Hop Option [:rfc:`8200`]
     HOPOPT = 0

pcapkit/const/pcapng/tls_key_label.py

@@ -18,7 +18,13 @@
 
 
 class TLSKeyLabel(EnumRegistry, StrEnum):
-    """[TLSKeyLabel] TLS Key Log Labels"""
+    """[TLSKeyLabel] TLS Key Log Labels
+
+    .. versionadded:: 1.5.0
+
+       Moved here from ``pcapkit.protocols.misc.pcapng`` (:issue:`886`).
+
+    """
 
     #: NSS-historical: not a registered label of :rfc:`9850#section-4.2`'s "TLS
     #: SSLKEYLOGFILE Labels" registry. Defined by the Mozilla NSS

pcapkit/const/reg/apptype/apptype.py

@@ -148,8 +148,8 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
         Args:
             key: Key to get enum item.
             default: An already-registered value to fall back to when
-                ``key`` resolves to nothing. :data:`~pcapkit.corekit.enum.
-                NO_DEFAULT`, the default, means *no default* -- see
+                ``key`` resolves to nothing.
+                :data:`~pcapkit.corekit.sentinels.NO_DEFAULT`, the default, means *no default* -- see
                 :meth:`~pcapkit.corekit.enum.EnumLookup.get`.
 
         Raises:
@@ -2905,8 +2905,9 @@ def _unregistered_member(cls, value: 'int', name: 'str',
         caller-named path that still does.
 
         Reconstructs :attr:`svc`, :attr:`port` and :attr:`proto` the same way
-        :meth:`__new__` would: :meth:`~pcapkit.corekit.enum.
-        EnumRegistry._unregistered_member` bypasses :meth:`__new__` entirely
+        :meth:`__new__` would:
+        :meth:`~pcapkit.corekit.enum.EnumRegistry._unregistered_member`
+        bypasses :meth:`__new__` entirely
         (it builds through ``cls._member_type_.__new__`` directly), so this
         class's own three attributes would otherwise be missing and every
         method reading them (:meth:`__repr__`, :meth:`__str__`, :meth:`__int__`,

pcapkit/const/tcp/flags.py

@@ -17,7 +17,14 @@
 __all__ = ['Flags']
 
 class Flags(EnumRegistry, IntFlag):
-    """[Flags] TCP Header Flags"""
+    """[Flags] TCP Header Flags
+
+    .. versionchanged:: 1.5.0
+
+       A value outside the 16-bit field raises :exc:`ValueError`, where
+       :mod:`aenum` composed a pseudo-member for any integer.
+
+    """
 
     #: Reserved for future use [:rfc:`9293`]
     Reserved_4 = 1 << 4

pcapkit/corekit/decorators.py

@@ -15,6 +15,14 @@
 so they live with the packet model rather than in :mod:`pcapkit.utilities`
 (:issue:`1735`).
 
+.. versionadded:: 1.5.0
+
+.. versionremoved:: 1.5.0
+
+   ``pcapkit.utilities.decorators``, now :mod:`pcapkit.corekit.decorators`
+   (:issue:`1735`). :mod:`pcapkit.utilities` does not export the three
+   decorators either.
+
 """
 import functools
 import io

pcapkit/corekit/enum.py

@@ -86,6 +86,13 @@
 guessed; ``register_alias`` (and ``register_aliases``) adds further alias names
 to a given member's mapping.
 
+.. versionadded:: 1.5.0
+
+   The ``get`` each :mod:`pcapkit.const` enumeration carried as generated text
+   moves onto :class:`EnumLookup`, and :class:`EnumRegistry` adds ``register``,
+   which is how a member is minted at runtime: outside ``CGAType``, looking up
+   an unknown value does not mint one (:issue:`775`).
+
 """
 from typing import TYPE_CHECKING
 
@@ -269,8 +276,8 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'Self':
         constructor would let a mere ``get()`` call mint a permanent member
         where it should just raise. Defensive rather than observed: none of
         the ``str``-valued registries that reach this method
-        (:class:`~pcapkit.const.ftp.command.Command`, :class:`~pcapkit.const.
-        ftp.command.FEATCode`, :class:`~pcapkit.const.http.method.Method`,
+        (:class:`~pcapkit.const.ftp.command.Command`,
+        :class:`~pcapkit.const.ftp.command.FEATCode`, :class:`~pcapkit.const.http.method.Method`,
         :class:`~pcapkit.const.pcapng.option_type.OptionType`,
         :class:`~pcapkit.const.reg.apptype.apptype.AppType` and its four
         transport subclasses :class:`~pcapkit.const.reg.apptype.tcp.TCP`,

pcapkit/corekit/fields/byteorder.py

@@ -10,6 +10,11 @@
 nested schema, so it lives with the fields rather than with either schema
 (:issue:`1711`).
 
+.. versionadded:: 1.5.0
+
+   :func:`byteorder_callback` moves here from
+   :mod:`pcapkit.protocols.schema.misc.pcap.frame` (:issue:`1711`).
+
 """
 
 import sys

pcapkit/corekit/fields/collections.py

@@ -412,6 +412,12 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list
             ProtocolError: If an option that begins with octets present reads
                 past the end of the data.
 
+        .. versionchanged:: 1.5.0
+
+           An option that begins with octets present and reads past the end of
+           the data raises :exc:`~pcapkit.utilities.exceptions.ProtocolError`,
+           where it was parsed from zero-filled octets (:issue:`1325`).
+
         """
         length = self._length
         if isinstance(buffer, bytes):
@@ -432,9 +438,9 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list
         #
         # Remembering where the previous option ended gives the loop a measure of
         # progress that does not depend on what a schema reports, and one octet of
-        # it per iteration is what bounds the iteration count. ``length`` is still
-        # decremented by ``len(data)``, so that an option area which parses today
-        # parses identically.
+        # it per iteration is what bounds the iteration count. ``length`` is
+        # decremented by ``len(data)`` as well, so the guard changes nothing for
+        # an option area that parses.
         #
         # ``start`` is where the option area itself begins. The comparison needs
         # stream positions, but the diagnostic wants an offset into the area, and