diff --git a/docs/source/pcapkit/const/ipv6.rst b/docs/source/pcapkit/const/ipv6.rst index a029100f37..b0db583caf 100644 --- a/docs/source/pcapkit/const/ipv6.rst +++ b/docs/source/pcapkit/const/ipv6.rst @@ -10,7 +10,7 @@ enumerations include: .. list-table:: - * - :class:`IPv6_Extension_Header ` + * - :class:`IPv6_ExtensionHeader ` - IPv6 Extension Header Types [*]_ * - :class:`IPv6_Option ` - Destination Options and Hop-by-Hop Options [*]_ diff --git a/docs/source/pcapkit/const/reg.rst b/docs/source/pcapkit/const/reg.rst index b787d23118..66f0be84b4 100644 --- a/docs/source/pcapkit/const/reg.rst +++ b/docs/source/pcapkit/const/reg.rst @@ -15,7 +15,7 @@ implementations. Available enumerations include: - Ethertype IEEE 802 Numbers [*]_ * - :class:`TRANSTYPE ` - Transport Layer Protocol Numbers [*]_ - * - :class:`APPTYPE ` + * - :class:`APPTYPE ` - Application Layer Protocol Numbers (Service Name and Transport Protocol Port Number Registry) [*]_ Link-Layer Header Type Values diff --git a/docs/source/pcapkit/corekit/fields/field.rst b/docs/source/pcapkit/corekit/fields/field.rst index 054753331a..c0198ba409 100644 --- a/docs/source/pcapkit/corekit/fields/field.rst +++ b/docs/source/pcapkit/corekit/fields/field.rst @@ -3,6 +3,11 @@ Base Fields .. module:: pcapkit.corekit.fields.field +.. versionremoved:: 1.3.0 + + ``pcapkit.corekit.fields.field._Field``, renamed + :class:`~pcapkit.corekit.fields.field.FieldBase` with no alias left behind. + .. versionremoved:: 1.5.0 ``pcapkit.corekit.fields.field.NoValueType``, now diff --git a/docs/source/pcapkit/vendor/default.rst b/docs/source/pcapkit/vendor/default.rst index d5001577ec..16420b22dc 100644 --- a/docs/source/pcapkit/vendor/default.rst +++ b/docs/source/pcapkit/vendor/default.rst @@ -3,8 +3,8 @@ Base Crawler .. module:: pcapkit.vendor.default -:mod:`pcapkit.vendor.default` contains :class:`~pcapkit.vendor.default.Vendor` -only, which is the base meta class for all vendor crawlers. +:mod:`pcapkit.vendor.default` exports :class:`~pcapkit.vendor.default.Vendor` +only, which is the base class for all vendor crawlers. .. autoclass:: pcapkit.vendor.default.Vendor :no-members: diff --git a/docs/source/pcapkit/vendor/http.rst b/docs/source/pcapkit/vendor/http.rst index 1cc7edb28c..6b84c65ccf 100644 --- a/docs/source/pcapkit/vendor/http.rst +++ b/docs/source/pcapkit/vendor/http.rst @@ -19,7 +19,7 @@ vendor crawlers include: - HTTP/1.\* Method [*]_ * - :class:`HTTP_Setting ` - HTTP/2 Settings [*]_ - * - :class:`HTTP_Status ` + * - :class:`HTTP_StatusCode ` - HTTP/1.\* Status Code [*]_ HTTP/2 Error Code diff --git a/docs/source/pcapkit/vendor/ipv6.rst b/docs/source/pcapkit/vendor/ipv6.rst index 47f75c6057..e5bac60cb1 100644 --- a/docs/source/pcapkit/vendor/ipv6.rst +++ b/docs/source/pcapkit/vendor/ipv6.rst @@ -10,7 +10,7 @@ vendor crawlers include: .. list-table:: - * - :class:`IPv6_Extension_Header ` + * - :class:`IPv6_ExtensionHeader ` - IPv6 Extension Header Types [*]_ * - :class:`IPv6_Option ` - Destination Options and Hop-by-Hop Options [*]_ diff --git a/docs/source/pcapkit/vendor/ipx.rst b/docs/source/pcapkit/vendor/ipx.rst index d35de31d7b..a0999cd1fb 100644 --- a/docs/source/pcapkit/vendor/ipx.rst +++ b/docs/source/pcapkit/vendor/ipx.rst @@ -23,8 +23,14 @@ IPX Packet Types This module contains the vendor crawler for **IPX Packet Types**, which is automatically generating :class:`pcapkit.const.ipx.packet.Packet`. +.. note:: + + This crawler does not crawl. Its table is gone from the Wikipedia article, + so the data is maintained by hand in the ``DATA`` mapping of + :mod:`pcapkit.vendor.ipx.packet`, and the class defines no ``LINK``. + .. autoclass:: pcapkit.vendor.ipx.packet.Packet - :members: FLAG, LINK + :members: FLAG :show-inheritance: Socket Types diff --git a/docs/source/pcapkit/vendor/reg.rst b/docs/source/pcapkit/vendor/reg.rst index f9dcee1c98..f30e90985a 100644 --- a/docs/source/pcapkit/vendor/reg.rst +++ b/docs/source/pcapkit/vendor/reg.rst @@ -15,7 +15,7 @@ implementations. Available vendor crawlers include: - Ethertype IEEE 802 Numbers [*]_ * - :class:`TRANSTYPE ` - Transport Layer Protocol Numbers [*]_ - * - :class:`APPTYPE ` + * - :class:`APPTYPE ` - Application Layer Protocol Numbers (Service Name and Transport Protocol Port Number Registry) [*]_ Link-Layer Header Type Values diff --git a/pcapkit/const/ipv6/__init__.py b/pcapkit/const/ipv6/__init__.py index feb0759360..572385b5d4 100644 --- a/pcapkit/const/ipv6/__init__.py +++ b/pcapkit/const/ipv6/__init__.py @@ -11,7 +11,7 @@ .. list-table:: - * - :class:`IPv6_Extension_Header ` + * - :class:`IPv6_ExtensionHeader ` - IPv6 Extension Header Types [*]_ * - :class:`IPv6_Option ` - Destination Options and Hop-by-Hop Options [*]_ diff --git a/pcapkit/const/mh/__init__.py b/pcapkit/const/mh/__init__.py index fba0a0e22f..24f063f025 100644 --- a/pcapkit/const/mh/__init__.py +++ b/pcapkit/const/mh/__init__.py @@ -89,7 +89,7 @@ - Link-Layer Address (LLA) Option Code [*]_ * - :class:`MH_CGAType ` - CGA Extension Type Tags [*]_ - * - :class:`MH_CGAExtension ` + * - :class:`MH_CGAExtension ` - CGA Extension Type Values [*]_ * - :class:`MH_CGASec ` - CGA SEC [*]_ diff --git a/pcapkit/const/pcapng/option_type.py b/pcapkit/const/pcapng/option_type.py index 3e075b83a2..f2c42aeebb 100644 --- a/pcapkit/const/pcapng/option_type.py +++ b/pcapkit/const/pcapng/option_type.py @@ -24,7 +24,14 @@ class OptionType(EnumRegistry, StrEnum): - """[OptionType] Option Types""" + """[OptionType] Option Types + + .. versionchanged:: 1.1.0 + + A member converts with :class:`int` to its option code, and compares, + orders and hashes as that code. + + """ if TYPE_CHECKING: #: Short name of the option type. diff --git a/pcapkit/const/reg/apptype/apptype.py b/pcapkit/const/reg/apptype/apptype.py index 6f5142d737..c45069caf8 100644 --- a/pcapkit/const/reg/apptype/apptype.py +++ b/pcapkit/const/reg/apptype/apptype.py @@ -73,9 +73,9 @@ class TransportProtocol(EnumLookup, IntEnum): # any other one that happens to equal it. Treating every int as a whole is # exactly what that ruling above asks for, and it is also why this # renumbering changes what specific ints mean, not only what composed ones - # do: ``tcp | udp`` (``3``) used to name no registry and now resolves as + # do: ``tcp | udp`` (``3``) used to name no registry and resolves as # ``sctp``'s own value, and a bare, uncomposed ``4`` -- previously - # ``sctp``'s value -- now resolves as ``dccp``'s, silently, with no + # ``sctp``'s value -- resolves as ``dccp``'s, silently, with no # exception, since a real member sits at ``4`` either way. A caller holding # an integer under the old spacing (composed or not) can therefore land on a # different real transport's registry after this change, not merely be @@ -109,7 +109,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco here is already lower-case, so a lowered ``key`` still hits the base's exact ``_member_map_`` lookup. - Case folding is now the *only* thing this override adds. It used to + Case folding is the *only* thing this override adds. It used to convert the base's name-miss exception as well -- this class raised :exc:`ValueError` where the base raised :exc:`KeyError` -- and the ruling given in review of the work for :issue:`877`, implemented in GitHub issue @@ -125,7 +125,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco four transport registries, and they land there only because their own ``get()`` takes an :class:`int` port and never accepts a name at all, rather than from any name-miss policy. So there was no policy here to - preserve, and a name miss now reaches the caller as + preserve, and a name miss reaches the caller as :exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base. The maintainer's ruling given in review of the work for :issue:`808`, that :class:`TransportProtocol` is not to be extended at all, is untouched by @@ -179,8 +179,8 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco # TransportProtocol is not to be extended at all. A name that is not a # declared member used to mint a brand-new one here, at ``max_val + 1`` # (before that, ``max_val * 2``) -- an unbounded, ever-growing set of - # transport protocols nothing ever asked for. There is nothing left to walk - # now: it is simply refused, exactly like any other unrecognised name -- + # transport protocols nothing ever asked for. There is nothing left to walk: + # it is simply refused, exactly like any other unrecognised name -- # including one spelling a composite, e.g. ``'tcp|udp'``. ``'|'`` used to be # intercepted here on its own, so a composite in disguise never got minted # into a member whose own name lied about being a single transport; a @@ -233,6 +233,11 @@ class AppType(EnumRegistry, StrEnum): makes it subclassable at all, since :mod:`aenum` refuses to extend an enumeration that already has members. + .. versionchanged:: 1.1.1 + + A member converts with :class:`int` to its port number, and compares, + orders and hashes as that port. + .. versionchanged:: 1.5.0 Split by transport protocol (:issue:`732`): :mod:`pcapkit.const.reg.apptype` @@ -2583,7 +2588,7 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[ # cast is for mypy alone: ``dict.get`` accepts any hashable key at run # time regardless of its declared key type, but mypy holds ``.get`` to # the dict's own ``TransportProtocol`` keys, and does not know ``proto`` - # can genuinely be a bare :class:`int` here now that GitHub issue #808 + # can genuinely be a bare :class:`int` here, since GitHub issue #808 # dropped the ``IntFlag`` base -- see the annotation on ``proto`` above. subclass = cls.__registries__.get(cast('TransportProtocol', proto)) if subclass is not None: @@ -2600,10 +2605,10 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[ # here whenever it matches no real member's value, e.g. a stray bit like # ``17``. A composite built by hand used to reach here just as reliably, # since no combination of the old power-of-two bits ever equalled a - # single real member's value; that is no longer true under this class's - # current sequential numbering -- + # single real member's value; that is not true under this class's + # sequential numbering -- # ``TransportProtocol.tcp | TransportProtocol.udp`` (``3``) is - # ``sctp``'s own value now, so it resolves at the dict lookup above + # ``sctp``'s own value, so it resolves at the dict lookup above # instead of reaching this point at all. A composite used to get its own # :exc:`~pcapkit.utilities.exceptions.ProtocolError`, decoded through # :func:`~pcapkit.utilities.compat.show_flag_values` and naming every diff --git a/pcapkit/corekit/decorators.py b/pcapkit/corekit/decorators.py index 2ee0662183..c8fc680f7b 100644 --- a/pcapkit/corekit/decorators.py +++ b/pcapkit/corekit/decorators.py @@ -119,6 +119,10 @@ def beholder( See Also: :meth:`pcapkit.protocols.protocol.Protocol._decode_next_layer` + .. versionchanged:: 1.3.0 + + Logs the exception it absorbs, and prints its traceback in verbose mode. + :param func: decorated function :meta decorator: """ diff --git a/pcapkit/corekit/enum.py b/pcapkit/corekit/enum.py index bce15d46eb..990eb42a0f 100644 --- a/pcapkit/corekit/enum.py +++ b/pcapkit/corekit/enum.py @@ -215,6 +215,13 @@ def _validate_value(cls, value: 'Any') -> 'None': * :meth:`EnumRegistry.register`, before minting -- the one point at which a caller can introduce a value no member carries yet. + Of the registries that override :meth:`EnumRegistry.register` to mint + through a path of their own, + :meth:`OptionType.register ` + calls it at the same point and + :meth:`AppType.register ` + does not. + :meth:`EnumRegistry.register_alias` does not call it, and does not need to: it refuses any ``value`` that is not already registered, so the value it aliases has necessarily passed validation already. diff --git a/pcapkit/corekit/fields/field.py b/pcapkit/corekit/fields/field.py index a841933d64..536fc86a38 100644 --- a/pcapkit/corekit/fields/field.py +++ b/pcapkit/corekit/fields/field.py @@ -6,6 +6,11 @@ :mod:`pcapkit.corekit.fields.field` contains the base field classes. +.. versionremoved:: 1.3.0 + + ``pcapkit.corekit.fields.field._Field``, renamed + :class:`~pcapkit.corekit.fields.field.FieldBase` with no alias left behind. + .. versionremoved:: 1.5.0 ``pcapkit.corekit.fields.field.NoValueType``, now @@ -141,9 +146,8 @@ def _zero_pad_budget() -> 'Iterator[list[int]]': class FieldMeta(abc.ABCMeta, Generic[_T]): """Meta class to add dynamic support to :class:`FieldBase`. - This meta class is used to generate necessary attributes for the - :class:`FieldBase` class. It can be useful to reduce unnecessary - registry calls and simplify the customisation process. + It defines nothing of its own, so a field class is built exactly as by + :class:`abc.ABCMeta`. """ diff --git a/pcapkit/corekit/fields/ipaddress.py b/pcapkit/corekit/fields/ipaddress.py index c955180eaa..4f37010b56 100644 --- a/pcapkit/corekit/fields/ipaddress.py +++ b/pcapkit/corekit/fields/ipaddress.py @@ -132,9 +132,9 @@ def parse_ip_address(value: 'IPv4Address | IPv6Address | bytes | int | str', value: Address as the caller gave it -- an :mod:`ipaddress` object, which is returned unchanged, or anything :mod:`ipaddress` accepts. description: Human-readable description of what ``value`` is, used to - build the :exc:`FieldValueError` message. Callers in a protocol - should carry their usual context into it, e.g. - ``f'{self.alias}: [OptNo {type}] care-of address'``. + build the :exc:`~pcapkit.utilities.exceptions.FieldValueError` + message. Callers in a protocol should carry their usual context + into it, e.g. ``f'{self.alias}: [OptNo {type}] care-of address'``. version: IP version to demand, ``4`` or ``6``, or :obj:`None` to take whichever family ``value`` describes. Pass it where the wire format fixes the family, so that an :class:`int` is widened to the right @@ -176,7 +176,7 @@ def parse_ip_address(value: 'IPv4Address | IPv6Address | bytes | int | str', dispatch on the value's type, for the placement reason :issue:`469` gives and :func:`_reject_bool` repeats. - This raises :exc:`FieldValueError` and not + This raises :exc:`~pcapkit.utilities.exceptions.FieldValueError` and not :exc:`~pcapkit.utilities.exceptions.ProtocolError`, which is deliberate even though two sibling guards for the same mistake -- :meth:`MH._make_opt_mn_id diff --git a/pcapkit/corekit/fields/numbers.py b/pcapkit/corekit/fields/numbers.py index fb05c13453..dd99d35390 100644 --- a/pcapkit/corekit/fields/numbers.py +++ b/pcapkit/corekit/fields/numbers.py @@ -242,7 +242,8 @@ def __call__(self, packet: 'dict[str, Any]') -> 'Self': a bare, uncatchable :exc:`ValueError` (``negative shift count``) when ``bit_length`` was not supplied, before :attr:`~pcapkit.corekit.fields.field.FieldBase.length` (see - its own :exc:`ProtocolError` guard, :issue:`805`/:issue:`825`) + its own :exc:`~pcapkit.utilities.exceptions.ProtocolError` + guard, :issue:`805`/:issue:`825`) or :meth:`build_template` ever sees the value: this method sets ``self._bit_length`` from the resolved length eagerly, as a cache, and shifts by it immediately, so the crash happens on @@ -252,7 +253,8 @@ def __call__(self, packet: 'dict[str, Any]') -> 'Self': with a fixed ``bit_length`` *and* a callable ``length`` that resolves negative raises the identical message as one with no ``bit_length`` at all, rather than falling through to a - ``template='...-1s'`` :exc:`ProtocolError` from + ``template='...-1s'`` + :exc:`~pcapkit.utilities.exceptions.ProtocolError` from :attr:`~pcapkit.corekit.fields.field.FieldBase.length` later -- see GitHub issue :issue:`831`. A resolved length of exactly ``0`` is a legitimate empty field (e.g. ``len=4`` above @@ -349,7 +351,7 @@ def pre_process(self, value: 'int', packet: 'dict[str, Any]') -> 'int | bytes': A field packed without having been resolved -- so with ``_length`` still negative -- has its width derived from the value instead, and - that rebuild can land on a width :func:`struct` has a native + that rebuild can land on a width :mod:`struct` has a native integer code for. The flag is therefore consulted **after** the rebuild rather than before it, since deciding first and rebuilding second would let the template and the value being returned @@ -836,11 +838,13 @@ def _unregistered_member(namespace: 'Type[StdlibEnum] | Type[AenumEnum]', ` need this rather than :meth:`_pseudo_member`: the result answers ``isinstance(result, AppType)`` truthfully, - which matters to at least seven ``isinstance`` sites elsewhere in - :mod:`pcapkit.protocols` (see ``test_a_member_is_still_an_apptype`` - in ``tests/const/test_const_apptype_split_unit.py``), and a value - that fails all of them would be a second defect standing in for - the one this fix removes. + which :meth:`PortEnumField.pre_process` tests before reading + ``.port`` off it, and ``Transport._make_port`` in + :mod:`pcapkit.protocols.transport.transport` before passing it + through unchanged (see ``test_a_member_is_still_an_apptype`` in + ``tests/const/test_const_apptype_split_unit.py``); a value that + fails them would be a second defect standing in for the one this + fix removes. The member this returns is absent from ``_value2member_map_``, so a *value*-keyed lookup on it -- ``self._namespace(value)`` -- @@ -1033,7 +1037,7 @@ class PortEnumField(EnumField): Important: This class is specifically designed for :class:`~pcapkit.const.reg.apptype.apptype.AppType` - as it is actually a :class:`~enum.StrEnum` class. + as it is actually a :class:`~aenum.StrEnum` class. .. versionadded:: 1.5.0 @@ -1114,17 +1118,20 @@ def post_process(self, value: 'int | bytes', packet: 'dict[str, Any]') -> 'AppTy off it would raise :exc:`AttributeError` on a miss ``get`` resolves. A port outside this field's own width is rejected *before* any of - that, rather than being let through to :meth:`_missing_` and - caught alongside a genuine miss. Both are a bare :exc:`ValueError` - with nothing to tell them apart by type, and + that, rather than being let through to + :meth:`~pcapkit.const.reg.apptype.apptype.AppType._missing_`, which + raises a bare :exc:`ValueError` for it. That call sits inside an + ``except ValueError`` that absorbs a foreign miss, and :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` rejects the out-of-range case deliberately, so that it is never minted over -- a catch keyed on exception type alone cannot see the difference - between that and :mod:`aenum`'s own "no member has this value", - so it would absorb both and quietly turn the rejection into a - miss. Checking the width first needs no exception-based - distinction at all. ``self.length`` is the field's own declared byte - width (``2`` for every caller of this class, hence ``0``-``65535``) + between that and a "no member has this value", so it would quietly + turn the rejection into a miss. Within the width, ``_missing_`` + raises for no port of any of the four registries: it returns a + member for a documented span and :data:`None` otherwise. Checking + the width first needs no exception-based distinction at all. + ``self.length`` is the field's own declared byte width (``2`` for + every caller of this class, hence ``0``-``65535``) rather than a hard-coded ``65535`` borrowed from :meth:`~pcapkit.const.reg.apptype.apptype.AppType._missing_`'s own guard, so the two stay in lockstep by construction. @@ -1143,11 +1150,12 @@ def post_process(self, value: 'int | bytes', packet: 'dict[str, Any]') -> 'AppTy declared = owner._missing_(value) # pylint: disable=protected-access except ValueError as error: # NOTE: value is already known to be in-width here, so this - # ValueError is aenum's own "no member has this value" for an - # in-range but unassigned port -- a foreign miss, absorbed -- - # never the out-of-range rejection, which never reaches - # this branch. A pcapkit.utilities.exceptions error is still a - # deliberate registry decision and propagates unchanged. + # ValueError is never the out-of-range rejection, which never + # reaches this branch; it could only be a foreign "no member has + # this value", absorbed as a miss. AppType._missing_ raises + # neither for an in-width port: it answers a miss with None. A + # pcapkit.utilities.exceptions error is still a deliberate + # registry decision and propagates unchanged. if isinstance(error, BaseError): raise declared = None diff --git a/pcapkit/corekit/infoclass.py b/pcapkit/corekit/infoclass.py index 8e325afbf1..0ce2b840a8 100644 --- a/pcapkit/corekit/infoclass.py +++ b/pcapkit/corekit/infoclass.py @@ -317,6 +317,10 @@ class Info(Mapping[str, VT], Generic[VT], metaclass=InfoMeta): accessing such renamed keys, the original key name should always be used, i.e., such renaming is totally transparent to the user. + .. versionchanged:: 1.3.3 + + Iterating an instance skips the names listed in :attr:`__excluded__`. + """ if TYPE_CHECKING: diff --git a/pcapkit/corekit/version.py b/pcapkit/corekit/version.py index 133f05c76b..221d3ca943 100644 --- a/pcapkit/corekit/version.py +++ b/pcapkit/corekit/version.py @@ -15,7 +15,14 @@ class VersionInfo(collections.namedtuple('VersionInfo', ['major', 'minor'])): - """VersionInfo is alike :class:`sys.version_info`.""" + """VersionInfo is alike :class:`sys.version_info`. + + .. versionchanged:: 1.3.0 + + :class:`str` gives ``'major.minor'`` rather than the tuple's + :func:`repr`. + + """ __slots__ = () diff --git a/pcapkit/vendor/__init__.py b/pcapkit/vendor/__init__.py index 9e77892704..46d27a5f0e 100644 --- a/pcapkit/vendor/__init__.py +++ b/pcapkit/vendor/__init__.py @@ -6,7 +6,7 @@ .. module:: pcapkit.vendor This module contains all web crawlers of :mod:`pcapkit`, which are -automatically generating the :mod:`pcapkit.const` module's constant. +automatically generating the :mod:`pcapkit.const` module's constant enumerations. """ diff --git a/pcapkit/vendor/default.py b/pcapkit/vendor/default.py index dd85ae1b7f..2a2d73539b 100644 --- a/pcapkit/vendor/default.py +++ b/pcapkit/vendor/default.py @@ -4,8 +4,8 @@ .. module:: pcapkit.vendor.default -:mod:`pcapkit.vendor.default` contains :class:`~pcapkit.vendor.default.Vendor` -only, which is the base meta class for all vendor crawlers. +:mod:`pcapkit.vendor.default` exports :class:`~pcapkit.vendor.default.Vendor` +only, which is the base class for all vendor crawlers. """ import abc @@ -70,7 +70,7 @@ #: under ``[project.urls]`` in :file:`pyproject.toml`. PROJECT_URL = 'https://github.com/JarryShaw/PyPCAPKit' -#: Default constant template of enumerate registry from IANA CSV. +#: Default constant template of enumeration registry from IANA CSV. LINE = lambda NAME, DOCS, FLAG, ENUM, MISS, MODL: f'''\ # -*- coding: utf-8 -*- # pylint: disable=line-too-long,consider-using-f-string @@ -211,9 +211,8 @@ def stdin_is_interactive() -> 'bool': class VendorMeta(abc.ABCMeta): """Meta class to add dynamic support to :class:`Vendor`. - This meta class is used to generate necessary attributes for the - :class:`Vendor` class. It can be useful to reduce unnecessary - registry calls and simplify the customisation process. + It defines nothing of its own, so a crawler class is built exactly as by + :class:`abc.ABCMeta`. """ diff --git a/pcapkit/vendor/ftp/command.py b/pcapkit/vendor/ftp/command.py index 331af584d0..b31942fce9 100644 --- a/pcapkit/vendor/ftp/command.py +++ b/pcapkit/vendor/ftp/command.py @@ -36,7 +36,7 @@ 'h': 'ConformanceRequirement.H', } # type: dict[str, str] -#: Default constant template of enumerate registry from IANA CSV. +#: Default constant template of enumeration registry from IANA CSV. LINE = lambda NAME, DOCS, ENUM, FEAT, MODL: f'''\ # -*- coding: utf-8 -*- # mypy: disable-error-code=assignment diff --git a/pcapkit/vendor/http/__init__.py b/pcapkit/vendor/http/__init__.py index 1bc05e4a8f..0c67e94446 100644 --- a/pcapkit/vendor/http/__init__.py +++ b/pcapkit/vendor/http/__init__.py @@ -19,7 +19,7 @@ - HTTP/1.\* Method [*]_ * - :class:`HTTP_Setting ` - HTTP/2 Settings [*]_ - * - :class:`HTTP_Status ` + * - :class:`HTTP_StatusCode ` - HTTP/1.\* Status Code [*]_ .. [*] https://www.iana.org/assignments/http2-parameters/http2-parameters.xhtml#error-code diff --git a/pcapkit/vendor/http/method.py b/pcapkit/vendor/http/method.py index 52fabe8598..0b746a6522 100644 --- a/pcapkit/vendor/http/method.py +++ b/pcapkit/vendor/http/method.py @@ -20,7 +20,7 @@ __all__ = ['Method'] -#: Default constant template of enumerate registry from IANA CSV. +#: Default constant template of enumeration registry from IANA CSV. LINE = lambda NAME, DOCS, ENUM, MODL: f'''\ # -*- coding: utf-8 -*- # pylint: disable=line-too-long diff --git a/pcapkit/vendor/http/status_code.py b/pcapkit/vendor/http/status_code.py index 7faa39acc8..004356ebbd 100644 --- a/pcapkit/vendor/http/status_code.py +++ b/pcapkit/vendor/http/status_code.py @@ -21,7 +21,7 @@ __all__ = ['StatusCode'] -#: Default constant template of enumerate registry from IANA CSV. +#: Default constant template of enumeration registry from IANA CSV. LINE = lambda NAME, DOCS, FLAG, ENUM, MISS, MODL: f'''\ # -*- coding: utf-8 -*- # mypy: disable-error-code=assignment diff --git a/pcapkit/vendor/ipv4/__init__.py b/pcapkit/vendor/ipv4/__init__.py index 673143ddf7..3b3cfbf6da 100644 --- a/pcapkit/vendor/ipv4/__init__.py +++ b/pcapkit/vendor/ipv4/__init__.py @@ -33,6 +33,8 @@ - ToS (DS Field) Reliability * - :class:`IPv4_ToSThroughput ` - ToS (DS Field) Throughput + * - :class:`IPv4_TSFlag ` + - TS Flag .. [*] https://www.iana.org/assignments/ip-parameters/ip-parameters.xhtml#ip-parameters-1 .. [*] https://www.iana.org/assignments/ip-parameters/ip-parameters.xhtml#ipv4-router-alert-option-values diff --git a/pcapkit/vendor/ipv6/__init__.py b/pcapkit/vendor/ipv6/__init__.py index 90b765340b..14d39af341 100644 --- a/pcapkit/vendor/ipv6/__init__.py +++ b/pcapkit/vendor/ipv6/__init__.py @@ -11,7 +11,7 @@ .. list-table:: - * - :class:`IPv6_Extension_Header ` + * - :class:`IPv6_ExtensionHeader ` - IPv6 Extension Header Types [*]_ * - :class:`IPv6_Option ` - Destination Options and Hop-by-Hop Options [*]_ diff --git a/pcapkit/vendor/mh/__init__.py b/pcapkit/vendor/mh/__init__.py index bf6cfd61d5..5a5ce5b4b5 100644 --- a/pcapkit/vendor/mh/__init__.py +++ b/pcapkit/vendor/mh/__init__.py @@ -89,7 +89,7 @@ - Link-Layer Address (LLA) Option Code [*]_ * - :class:`MH_CGAType ` - CGA Extension Type Tags [*]_ - * - :class:`MH_CGAExtension ` + * - :class:`MH_CGAExtension ` - CGA Extension Type Values [*]_ * - :class:`MH_CGASec ` - CGA SEC [*]_ diff --git a/pcapkit/vendor/pcapng/option_type.py b/pcapkit/vendor/pcapng/option_type.py index 3f36452921..4b32647bbf 100644 --- a/pcapkit/vendor/pcapng/option_type.py +++ b/pcapkit/vendor/pcapng/option_type.py @@ -52,7 +52,14 @@ class {NAME}(EnumRegistry, StrEnum): - """[{NAME}] {DOCS}""" + """[{NAME}] {DOCS} + + .. versionchanged:: 1.1.0 + + A member converts with :class:`int` to its option code, and compares, + orders and hashes as that code. + + """ if TYPE_CHECKING: #: Short name of the option type. diff --git a/pcapkit/vendor/reg/apptype/apptype.py b/pcapkit/vendor/reg/apptype/apptype.py index bc626b183c..a0e48c51db 100644 --- a/pcapkit/vendor/reg/apptype/apptype.py +++ b/pcapkit/vendor/reg/apptype/apptype.py @@ -166,9 +166,9 @@ class TransportProtocol(EnumLookup, IntEnum): # any other one that happens to equal it. Treating every int as a whole is # exactly what that ruling above asks for, and it is also why this # renumbering changes what specific ints mean, not only what composed ones - # do: ``tcp | udp`` (``3``) used to name no registry and now resolves as + # do: ``tcp | udp`` (``3``) used to name no registry and resolves as # ``sctp``'s own value, and a bare, uncomposed ``4`` -- previously - # ``sctp``'s value -- now resolves as ``dccp``'s, silently, with no + # ``sctp``'s value -- resolves as ``dccp``'s, silently, with no # exception, since a real member sits at ``4`` either way. A caller holding # an integer under the old spacing (composed or not) can therefore land on a # different real transport's registry after this change, not merely be @@ -202,7 +202,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco here is already lower-case, so a lowered ``key`` still hits the base's exact ``_member_map_`` lookup. - Case folding is now the *only* thing this override adds. It used to + Case folding is the *only* thing this override adds. It used to convert the base's name-miss exception as well -- this class raised :exc:`ValueError` where the base raised :exc:`KeyError` -- and the ruling given in review of the work for :issue:`877`, implemented in GitHub issue @@ -218,7 +218,7 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco four transport registries, and they land there only because their own ``get()`` takes an :class:`int` port and never accepts a name at all, rather than from any name-miss policy. So there was no policy here to - preserve, and a name miss now reaches the caller as + preserve, and a name miss reaches the caller as :exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base. The maintainer's ruling given in review of the work for :issue:`808`, that :class:`TransportProtocol` is not to be extended at all, is untouched by @@ -272,8 +272,8 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco # TransportProtocol is not to be extended at all. A name that is not a # declared member used to mint a brand-new one here, at ``max_val + 1`` # (before that, ``max_val * 2``) -- an unbounded, ever-growing set of - # transport protocols nothing ever asked for. There is nothing left to walk - # now: it is simply refused, exactly like any other unrecognised name -- + # transport protocols nothing ever asked for. There is nothing left to walk: + # it is simply refused, exactly like any other unrecognised name -- # including one spelling a composite, e.g. ``'tcp|udp'``. ``'|'`` used to be # intercepted here on its own, so a composite in disguise never got minted # into a member whose own name lied about being a single transport; a @@ -326,6 +326,11 @@ class {NAME}(EnumRegistry, StrEnum): makes it subclassable at all, since :mod:`aenum` refuses to extend an enumeration that already has members. + .. versionchanged:: 1.1.1 + + A member converts with :class:`int` to its port number, and compares, + orders and hashes as that port. + .. versionchanged:: 1.5.0 Split by transport protocol (:issue:`732`): :mod:`pcapkit.const.reg.apptype` @@ -538,7 +543,7 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[ # cast is for mypy alone: ``dict.get`` accepts any hashable key at run # time regardless of its declared key type, but mypy holds ``.get`` to # the dict's own ``TransportProtocol`` keys, and does not know ``proto`` - # can genuinely be a bare :class:`int` here now that GitHub issue #808 + # can genuinely be a bare :class:`int` here, since GitHub issue #808 # dropped the ``IntFlag`` base -- see the annotation on ``proto`` above. subclass = cls.__registries__.get(cast('TransportProtocol', proto)) if subclass is not None: @@ -555,10 +560,10 @@ def _dispatch(cls, key: 'int', proto: 'TransportProtocol | str | int') -> 'Type[ # here whenever it matches no real member's value, e.g. a stray bit like # ``17``. A composite built by hand used to reach here just as reliably, # since no combination of the old power-of-two bits ever equalled a - # single real member's value; that is no longer true under this class's - # current sequential numbering -- + # single real member's value; that is not true under this class's + # sequential numbering -- # ``TransportProtocol.tcp | TransportProtocol.udp`` (``3``) is - # ``sctp``'s own value now, so it resolves at the dict lookup above + # ``sctp``'s own value, so it resolves at the dict lookup above # instead of reaching this point at all. A composite used to get its own # :exc:`~pcapkit.utilities.exceptions.ProtocolError`, decoded through # :func:`~pcapkit.utilities.compat.show_flag_values` and naming every diff --git a/pcapkit/vendor/reg/ethertype.py b/pcapkit/vendor/reg/ethertype.py index 24fe684d3a..62ff8cccb3 100644 --- a/pcapkit/vendor/reg/ethertype.py +++ b/pcapkit/vendor/reg/ethertype.py @@ -37,8 +37,9 @@ class EtherType(Vendor): #: nothing (``DEC Unassigned``), or a range the list says is dead/invalid #: outright -- rather than a proprietary protocol's real name. The owner's #: original ruling on :issue:`775`/:issue:`841` held these two out as the only rows to - #: convert to :meth:`~pcapkit.corekit.enum.EnumRegistry._unregistered_ - #: member`, on the theory that a proprietary protocol's company name IS + #: convert to + #: :meth:`~pcapkit.corekit.enum.EnumRegistry._unregistered_member`, on the + #: theory that a proprietary protocol's company name IS #: the final concrete name for every other row. :issue:`775`'s final round #: converts every row alike, so this set does not decide *whether* a #: row registers -- only *how its name is spelled*: these two keep the diff --git a/pcapkit/vendor/tcp/flags.py b/pcapkit/vendor/tcp/flags.py index 3e4662d7c3..c3862ebec3 100644 --- a/pcapkit/vendor/tcp/flags.py +++ b/pcapkit/vendor/tcp/flags.py @@ -33,7 +33,7 @@ 8: 'CWR', } -#: Default constant template of enumerate registry from IANA CSV. +#: Default constant template of enumeration registry from IANA CSV. LINE = lambda NAME, DOCS, FLAG, ENUM, MODL: f'''\ # -*- coding: utf-8 -*- # pylint: disable=line-too-long diff --git a/pcapkit/vendor/vlan/__init__.py b/pcapkit/vendor/vlan/__init__.py index 13fbc0bd43..c3dbc16108 100644 --- a/pcapkit/vendor/vlan/__init__.py +++ b/pcapkit/vendor/vlan/__init__.py @@ -11,7 +11,7 @@ .. list-table:: - * - :const:`VLAN_PriorityLevel ` + * - :const:`VLAN_PriorityLevel ` - Priority Levels [*]_ .. [*] https://en.wikipedia.org/wiki/IEEE_P802.1p#Priority_levels