diff --git a/pcapkit/protocols/schema/__init__.py b/pcapkit/protocols/schema/__init__.py index 360de9e1cf..9f573639bf 100644 --- a/pcapkit/protocols/schema/__init__.py +++ b/pcapkit/protocols/schema/__init__.py @@ -28,7 +28,7 @@ 'ARP', 'Ethernet', 'L2TP', - 'OSPF', 'OSPF_CrytographicAuthentication', + 'OSPF', 'OSPF_CrytographicAuthentication', # application layer 'VLAN', 'VLAN_TCI', # Internet Layer Protocols diff --git a/pcapkit/protocols/schema/application/httpv2.py b/pcapkit/protocols/schema/application/httpv2.py index 9fb6ae17f1..623117cacb 100644 --- a/pcapkit/protocols/schema/application/httpv2.py +++ b/pcapkit/protocols/schema/application/httpv2.py @@ -49,7 +49,7 @@ class FrameFlags(TypedDict): class StreamID(TypedDict): """Stream identifier.""" - #: Steam identifier. + #: Stream identifier. sid: int class StreamDependency(TypedDict): @@ -130,7 +130,7 @@ class Flags(EnumLookup, enum.IntFlag): Built on :class:`~pcapkit.corekit.enum.EnumLookup`, the lookup contract shared by every non-registry enumeration. The six concrete per-frame subclasses below each declare ``class Flags(FrameType.Flags):`` with no - base list of their own, so they inherit :class:`EnumLookup` + base list of their own, so they inherit :class:`~pcapkit.corekit.enum.EnumLookup` transitively rather than needing it repeated. """ diff --git a/pcapkit/protocols/schema/internet/hip.py b/pcapkit/protocols/schema/internet/hip.py index 3b78b6ec6a..ee55d1de4f 100644 --- a/pcapkit/protocols/schema/internet/hip.py +++ b/pcapkit/protocols/schema/internet/hip.py @@ -225,7 +225,7 @@ def two_octet_prefix_list_len(pkt: 'dict[str, Any]') -> 'int': two-octet ``reserved`` or ``port`` field with a list of items sized by the remainder of the parameter. - :class:`TransportFormatListParameter` looked like a fourth call site -- + :class:`TransportFormatListParameter` looks like a fourth call site -- same ``pkt['len'] - 2`` expression -- but is not: see :func:`transport_format_list_len` for why it has no such prefix to subtract. @@ -264,10 +264,9 @@ def transport_format_list_len(pkt: 'dict[str, Any]') -> 'int': | TF type #1 | TF type #2 / -- so the list's byte length *is* ``Length``, with nothing to subtract. - Subtracting 2 anyway (as a since-corrected revision of this module once - did, mirroring the three genuine two-octet-prefix sites) silently - dropped the trailing two octets of *every* non-empty list on parse, and - rejected the parameter's own legitimate empty-list encoding + Subtracting 2 anyway, as the three genuine two-octet-prefix sites do, + would drop the trailing two octets of *every* non-empty list on parse, + and reject the parameter's own legitimate empty-list encoding (``Length = 0``, ``formats = []``) as malformed. "2x number of TF types" also fixes each ``TF type`` entry's own width at @@ -277,10 +276,9 @@ def transport_format_list_len(pkt: 'dict[str, Any]') -> 'int': ``EnumField(length=2, ...)``, matching :class:`HIPTransportModeParameter`'s ``mode`` rather than the one-octet items of :func:`two_octet_prefix_list_len`'s other two call sites. This function only answers how many *bytes* the - list occupies; getting that number right and the item width wrong (as a - still-earlier revision did, at one octet) still corrupts every non-empty - list, just by reading twice as many entries as the wire holds instead of - dropping octets. + list occupies; getting that number right and the item width wrong (one + octet) would still corrupt every non-empty list, just by reading twice as + many entries as the wire holds instead of dropping octets. Args: pkt: Parameter unpacked schema. diff --git a/pcapkit/protocols/schema/internet/ipv4.py b/pcapkit/protocols/schema/internet/ipv4.py index 047726ca96..67da61353c 100644 --- a/pcapkit/protocols/schema/internet/ipv4.py +++ b/pcapkit/protocols/schema/internet/ipv4.py @@ -106,7 +106,7 @@ class QSNonce(TypedDict): def quick_start_option_length(schema: 'Type[QSOption]') -> 'int': """On-the-wire length, in octets, of a resolved Quick-Start (``QS``) suboption. - The Quick-Start suboption schemas re-declare the option's own ``type`` and + The Quick-Start suboption schemas carry the option's own ``type`` and ``length`` octets -- they inherit them from :class:`Option` -- so what :func:`quick_start_data_selector` has to hand the nested :class:`~pcapkit.corekit.fields.misc.SchemaField` is the length of the @@ -295,7 +295,7 @@ class LSROption(Option, code=Enum_OptionNumber.LSR): length=lambda pkt: pkt['pointer'] - 4, item_type=IPv4AddressField(), ) - #: Remaining data buffer0. + #: Remaining data buffer. remainder: 'bytes' = PaddingField( length=lambda pkt: pkt['length'] - pkt['pointer'] + 1, default=bytes(36), # a reasonable default @@ -481,7 +481,7 @@ class RROption(Option, code=Enum_OptionNumber.RR): length=lambda pkt: pkt['pointer'] - 4, item_type=IPv4AddressField(), ) - #: Remaining data buffer0. + #: Remaining data buffer. remainder: 'bytes' = PaddingField( length=lambda pkt: pkt['length'] - pkt['pointer'] + 1, default=bytes(36), # a reasonable default @@ -515,7 +515,7 @@ class SSROption(Option, code=Enum_OptionNumber.SSR): length=lambda pkt: pkt['pointer'] - 4, item_type=IPv4AddressField(), ) - #: Remaining data buffer0. + #: Remaining data buffer. remainder: 'bytes' = PaddingField( length=lambda pkt: pkt['length'] - pkt['pointer'] + 1, default=bytes(36), # a reasonable default @@ -608,7 +608,7 @@ def post_process(self, packet: 'dict[str, Any]') -> 'QSOption': class QSOption(Option, EnumSchema[Enum_QSFunction]): - """Header schema for IPV4 quick start (``QS``) options.""" + """Header schema for IPv4 quick start (``QS``) options.""" __enum__: 'DefaultDict[Enum_QSFunction, Type[QSOption]]' = collections.defaultdict(lambda: None) # type: ignore[return-value,arg-type] @@ -624,7 +624,7 @@ class QSOption(Option, EnumSchema[Enum_QSFunction]): @schema_final class QuickStartRequestOption(QSOption, code=Enum_QSFunction.Quick_Start_Request): - """Header schema for IPV4 quick start request options.""" + """Header schema for IPv4 quick start request options.""" #: QS time-to-live (TTL). ttl: 'int' = UInt8Field() @@ -640,7 +640,7 @@ def __init__(self, type: 'Enum_OptionNumber', length: 'int', flags: 'QuickStartF @schema_final class QuickStartReportOption(QSOption, code=Enum_QSFunction.Report_of_Approved_Rate): - """Header schema for IPV4 quick start report of approved rate options.""" + """Header schema for IPv4 quick start report of approved rate options.""" #: Not used. One octet, holding the place a Quick-Start Request fills with #: ``QS TTL``: :rfc:`4782#section-3.1` says in as many words that *"for a diff --git a/pcapkit/protocols/schema/internet/mh.py b/pcapkit/protocols/schema/internet/mh.py index 200122f03b..da71ebb493 100644 --- a/pcapkit/protocols/schema/internet/mh.py +++ b/pcapkit/protocols/schema/internet/mh.py @@ -600,7 +600,7 @@ def post_process(self, packet: 'dict[str, Any]') -> 'Option': Revised schema. """ - # for Pad1 option, length is always 1 + # for Pad1 option, length is always 0 if self.type == Enum_Option.Pad1: self.length = 0 return self @@ -1939,7 +1939,8 @@ class DynamicIPMulticastSelectorOption(Option, code=Enum_Option.Dynamic_IP_Multi :rfc:`3376#section-4.2` IGMP structures, which belong to those protocols rather than to the Mobility Header, so they are carried opaquely here. :attr:`protocol` says which of the two they are in -- ``143`` for MLDv2 - and ``131`` for MLDv1. + and ``131`` for MLDv1 [:rfc:`7028#section-5.1.2`], or ``0x12``, ``0x16`` + and ``0x22`` for IGMPv1 to IGMPv3 [:rfc:`7028#section-8`]. """ @@ -1990,7 +1991,7 @@ class ActiveMulticastSubscriptionIPv4Option( """ - #: IGMP message type identifying the context format: ``0x12`` for IGMPv1, + #: IGMP message type identifying the context format -- ``0x12`` for IGMPv1, #: ``0x16`` for IGMPv2 and ``0x22`` for IGMPv3. igmp_type: 'int' = UInt8Field() #: Multicast membership context. @@ -2014,7 +2015,7 @@ class ActiveMulticastSubscriptionIPv6Option( """ - #: MLD message type identifying the context format: ``143`` for MLDv2 and + #: MLD message type identifying the context format -- ``143`` for MLDv2 and #: ``131`` for MLDv1. mld_type: 'int' = UInt8Field() #: Multicast membership context. @@ -2216,7 +2217,7 @@ class MulticastMobilityOption(Option, code=Enum_Option.Multicast_Mobility_Option """ - #: Option code: ``1`` for IGMPv3, ``2`` for MLDv2, ``3`` for IGMPv3 in + #: Option code -- ``1`` for IGMPv3, ``2`` for MLDv2, ``3`` for IGMPv3 in #: IGMPv2 compatibility mode and ``4`` for MLDv2 in MLDv1 compatibility mode. code: 'int' = UInt8Field() #: Reserved. @@ -2242,7 +2243,7 @@ class MulticastAcknowledgementOption(Option, code=Enum_Option.Multicast_Acknowle #: Option code; always ``0``. code: 'int' = UInt8Field() - #: Status: ``1`` report payload type unsupported, ``2`` requested group + #: Status -- ``1`` report payload type unsupported, ``2`` requested group #: service unsupported, ``3`` requested group service administratively #: prohibited. status: 'int' = UInt8Field() diff --git a/pcapkit/protocols/schema/link/ethernet.py b/pcapkit/protocols/schema/link/ethernet.py index 861907e09b..45e962f0c5 100644 --- a/pcapkit/protocols/schema/link/ethernet.py +++ b/pcapkit/protocols/schema/link/ethernet.py @@ -34,14 +34,14 @@ def callback_payload(self: 'PayloadField', packet: 'dict[str, Any]') -> 'None': subscripting the registry. :attr:`Ethernet.__proto__ ` *is* :attr:`Link.__proto__ `, a - class-level :class:`collections.defaultdict`, so reading a missing key - inserted it -- every unregistered EtherType a parse saw was recorded as - though somebody had registered it, and - :meth:`Link.register ` - afterwards reported it as an overwrite. The helper reads the fallback - without recording it, and memoises a - :class:`~pcapkit.corekit.module.ModuleDescriptor` for a code that really - is registered, which this did not. + class-level :class:`collections.defaultdict`, so subscripting it with a + missing key would insert that key -- every unregistered EtherType a parse + saw would be recorded as though somebody had registered it, and + :meth:`Link.register ` would + afterwards report it as an overwrite. The helper reads the fallback + without recording it, and for a code that really is registered as a + :class:`~pcapkit.corekit.module.ModuleDescriptor` it writes the resolved + class back, so the import happens once. """ from pcapkit.protocols.link.ethernet import Ethernet # pylint: disable=import-outside-toplevel diff --git a/pcapkit/protocols/schema/misc/null.py b/pcapkit/protocols/schema/misc/null.py index ca560cef22..bbedb9d055 100644 --- a/pcapkit/protocols/schema/misc/null.py +++ b/pcapkit/protocols/schema/misc/null.py @@ -11,8 +11,9 @@ class NoPayload(Schema): """Schema for empty payload.""" - # NOTE: We add this method for both type annotation and to mark that this - # class accepts no arguments at runtime, since :class:`Schema` explicitly - # skipped those whose :attr:`__dict__` is empty :obj:`dict`. + # NOTE: Declared both for type annotation and to make this class accept no + # arguments at runtime: :func:`schema_final` generates an ``__init__`` only + # for a class that does not define one, so this one keeps the generated + # ``dict_``-taking constructor from displacing it. def __init__(self) -> 'None': # pylint: disable=super-init-not-called pass diff --git a/pcapkit/protocols/schema/misc/pcapng.py b/pcapkit/protocols/schema/misc/pcapng.py index 61a13f59b2..6c8a211fa6 100644 --- a/pcapkit/protocols/schema/misc/pcapng.py +++ b/pcapkit/protocols/schema/misc/pcapng.py @@ -81,7 +81,7 @@ class ByteorderTest(TypedDict): class ResolutionData(TypedDict): """Data for resolution.""" - #: Resolution type flag (0: 10-based, 1: 2-based). + #: Resolution type flag (``0`` for 10-based, ``1`` for 2-based). flag: int #: Resolution value. resolution: int @@ -412,8 +412,8 @@ def bounded_area(length: 'Callable[[dict[str, Any]], int]') -> 'Callable[[dict[s The nominal span goes through :func:`nonnegative` first here too. That closes a hole in this function's own arithmetic: a ``captured_len`` past the end of the block makes the span negative, and ``nominal <= available`` - below is then *true*, so the negative was returned unclamped and reached - a :mod:`struct` template as ``f'{-N}s'``. Measured on 200 Enhanced Packet + below is then *true*, so the negative would be returned unclamped and + reach a :mod:`struct` template as ``f'{-N}s'``. Measured on 200 Enhanced Packet Blocks declaring ``captured_len`` ``0xFFFFFF`` in 8,048 octets. """ @@ -709,7 +709,7 @@ def __init_subclass__(cls, /, code: 'Optional[Enum_OptionType | Iterable[Enum_Op than ``namespace`` because :meth:`abc.ABCMeta.__new__` names its own fourth parameter ``namespace``, and before Python 3.11 that parameter is positional-or-keyword rather than positional-only -- - so a class keyword literally called ``namespace`` bound it twice. + so a class keyword literally called ``namespace`` binds it twice. *args: Arbitrary positional arguments. **kwargs: Arbitrary keyword arguments. @@ -944,7 +944,7 @@ def pre_pack(self, packet: 'dict[str, Any]') -> 'None': def post_process(self, packet: 'dict[str, Any]') -> 'SectionHeaderBlock': """Revise ``schema`` data after unpacking process. - This method calculate the byteorder value based on + This method calculates the byteorder value based on the parsed schema. Args: diff --git a/pcapkit/protocols/schema/schema.py b/pcapkit/protocols/schema/schema.py index 53f0f8cf42..e323289b97 100644 --- a/pcapkit/protocols/schema/schema.py +++ b/pcapkit/protocols/schema/schema.py @@ -882,8 +882,9 @@ def unpack(cls, data: 'bytes | IO[bytes]', When this schema is nested -- unpacked through a :class:`~pcapkit.corekit.fields.misc.SchemaField` rather than directly -- ``packet`` is not the enclosing schema's own data, but - a context built by :func:`~pcapkit.corekit.fields.misc. - nested_packet_context`: a name this schema does not itself + a context built by + :func:`~pcapkit.corekit.fields.misc.nested_packet_context`: a name + this schema does not itself declare falls through to the enclosing schema, and the enclosing schema is also reachable unconditionally under a ``__packet__`` key. See that function for the exact lookup, write and iteration @@ -1043,8 +1044,8 @@ class _EnumRegistry(collections.defaultdict): The fallback itself is deliberate -- it is how an unknown option, chunk or block falls back to its ``Unknown*``/``Unassigned*`` schema -- so this subclass keeps returning it and just stops recording it. - :meth:`ProtocolBase.\ - _lookup_registry ` + :meth:`ProtocolBase._lookup_registry + ` does the same for the protocol-layer ``__proto__`` family. """ @@ -1059,7 +1060,7 @@ class EnumMeta(SchemaMeta, Generic[_ET]): """Meta class to add dynamic support for :class:`EnumSchema`. This meta class is used to generate necessary attributes for the - :class:`SchemaMeta` class. It can be useful to reduce runtime generation + :class:`EnumSchema` class. It can be useful to reduce runtime generation cost as well as caching already generated attributes. * :attr:`~EnumSchema.registry` is added to subclasses as an *immutable* @@ -1239,11 +1240,11 @@ def __init_subclass__(cls, /, code: 'Optional[_ET | Iterable[_ET]]' = None, *arg @classmethod def register(cls, code: '_ET', schema: 'Type[Self]') -> 'None': - """Register enumetaion to :attr:`__enum__` mapping. + """Register enumeration to :attr:`__enum__` mapping. Args: - code: Enumetaion code. - schema: Enumetaion schema. + code: Enumeration code. + schema: Enumeration schema. Warns: pcapkit.utilities.warnings.RegistryWarning: If ``code`` is already diff --git a/pcapkit/protocols/schema/transport/tcp.py b/pcapkit/protocols/schema/transport/tcp.py index cb2bf2e7e7..69c087ec3a 100644 --- a/pcapkit/protocols/schema/transport/tcp.py +++ b/pcapkit/protocols/schema/transport/tcp.py @@ -273,7 +273,7 @@ def mptcp_dss_ack_selector(pkt: 'dict[str, Any]') -> 'Field': ``struct.error: bad char in struct format``. Nothing here meets that only because :class:`Schema `'s ``pack`` and ``unpack`` - special-case ``ConditionalField`` by name and skip the wrapped field + special-case ``ConditionalField`` by type and skip the wrapped field outright before any ``length`` is read. A ``SwitchField`` needs no such special case: its selector always hands back an already-concrete field, :class:`~pcapkit.corekit.fields.misc.NoValueField` included, so its