diff --git a/docs/source/pcapkit/corekit/context.rst b/docs/source/pcapkit/corekit/context.rst index f59061384e..92da6f5467 100644 --- a/docs/source/pcapkit/corekit/context.rst +++ b/docs/source/pcapkit/corekit/context.rst @@ -18,7 +18,7 @@ and known only to the caller. Rather than adding protocol-specific keyword arguments to :class:`~pcapkit.foundation.extraction.Extractor`, such information is passed as a :class:`~pcapkit.corekit.context.ContextRegistry` -- a mapping of protocol -index ID (c.f. :meth:`Protocol.id `) to +index ID (cf. :meth:`Protocol.id `) to a :class:`~pcapkit.corekit.context.ProtocolContext` instance. It is handed to :class:`~pcapkit.foundation.extraction.Extractor` once and propagated down the protocol stack by diff --git a/docs/source/pcapkit/corekit/version.rst b/docs/source/pcapkit/corekit/version.rst index 996b9d2957..60feaadb4f 100644 --- a/docs/source/pcapkit/corekit/version.rst +++ b/docs/source/pcapkit/corekit/version.rst @@ -5,7 +5,7 @@ Version Info :mod:`pcapkit.corekit.version` contains the :obj:`tuple`-like class :class:`~pcapkit.corekit.version.VersionInfo`, modelled on -:class:`sys.version_info`. +:data:`sys.version_info`. .. autoclass:: pcapkit.corekit.version.VersionInfo :no-members: diff --git a/pcapkit/const/reg/apptype/apptype.py b/pcapkit/const/reg/apptype/apptype.py index 99981c4f75..d8a447c571 100644 --- a/pcapkit/const/reg/apptype/apptype.py +++ b/pcapkit/const/reg/apptype/apptype.py @@ -2846,10 +2846,12 @@ def register_alias(cls, port: 'int', name: 'str') -> 'AppType': # pylint: disab GitHub issue :issue:`807`'s third ask, deliberately scoped to **this** per-transport registry: ``TCP.register_alias(...)`` never touches - :class:`UDP`'s members, which is what keeps an alias registered on one - transport from leaking onto a transport IANA never assigned it -- e.g. - registering ``www`` as an alias of ``http`` on :class:`TCP` and - :class:`UDP` leaves it absent from :class:`SCTP`'s port 80, exactly as + :class:`~pcapkit.const.reg.apptype.udp.UDP`'s members, which is what + keeps an alias registered on one transport from leaking onto a + transport IANA never assigned it -- e.g. registering ``www`` as an alias + of ``http`` on :class:`~pcapkit.const.reg.apptype.tcp.TCP` and + :class:`~pcapkit.const.reg.apptype.udp.UDP` leaves it absent from + :class:`~pcapkit.const.reg.apptype.sctp.SCTP`'s port 80, exactly as IANA itself never registered it there. No new storage: the new member simply joins :data:`__registry__` at diff --git a/pcapkit/const/reg/apptype/dccp.py b/pcapkit/const/reg/apptype/dccp.py index fd3281396a..6632a75e25 100644 --- a/pcapkit/const/reg/apptype/dccp.py +++ b/pcapkit/const/reg/apptype/dccp.py @@ -50,7 +50,7 @@ class DCCP(AppType): __registry__: 'MultiDict[int, DCCP]' = MultiDict() #: The canonical service for each port IANA assigns more than one to, i.e. - #: what :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` answers with. + #: what ``AppType.get()`` answers with. #: Taken from :file:`/etc/services`, which is what #: :func:`socket.getservbyport` reads -- IANA names no precedence among the #: services it registers on one port, and registry row order does not supply diff --git a/pcapkit/const/reg/apptype/sctp.py b/pcapkit/const/reg/apptype/sctp.py index 34846a022d..d7e010e55f 100644 --- a/pcapkit/const/reg/apptype/sctp.py +++ b/pcapkit/const/reg/apptype/sctp.py @@ -54,7 +54,7 @@ class SCTP(AppType): __registry__: 'MultiDict[int, SCTP]' = MultiDict() #: The canonical service for each port IANA assigns more than one to, i.e. - #: what :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` answers with. + #: what ``AppType.get()`` answers with. #: Taken from :file:`/etc/services`, which is what #: :func:`socket.getservbyport` reads -- IANA names no precedence among the #: services it registers on one port, and registry row order does not supply diff --git a/pcapkit/const/reg/apptype/tcp.py b/pcapkit/const/reg/apptype/tcp.py index e133d05d94..e2f528d157 100644 --- a/pcapkit/const/reg/apptype/tcp.py +++ b/pcapkit/const/reg/apptype/tcp.py @@ -906,7 +906,7 @@ class TCP(AppType): __registry__: 'MultiDict[int, TCP]' = MultiDict() #: The canonical service for each port IANA assigns more than one to, i.e. - #: what :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` answers with. + #: what ``AppType.get()`` answers with. #: Taken from :file:`/etc/services`, which is what #: :func:`socket.getservbyport` reads -- IANA names no precedence among the #: services it registers on one port, and registry row order does not supply diff --git a/pcapkit/const/reg/apptype/udp.py b/pcapkit/const/reg/apptype/udp.py index 22a910d4cc..883a39c77e 100644 --- a/pcapkit/const/reg/apptype/udp.py +++ b/pcapkit/const/reg/apptype/udp.py @@ -373,7 +373,7 @@ class UDP(AppType): __registry__: 'MultiDict[int, UDP]' = MultiDict() #: The canonical service for each port IANA assigns more than one to, i.e. - #: what :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` answers with. + #: what ``AppType.get()`` answers with. #: Taken from :file:`/etc/services`, which is what #: :func:`socket.getservbyport` reads -- IANA names no precedence among the #: services it registers on one port, and registry row order does not supply diff --git a/pcapkit/corekit/context.py b/pcapkit/corekit/context.py index fee9fcf174..386ec160d1 100644 --- a/pcapkit/corekit/context.py +++ b/pcapkit/corekit/context.py @@ -20,7 +20,7 @@ Rather than adding protocol specific keyword arguments to :class:`~pcapkit.foundation.extraction.Extractor`, such information is passed as a :class:`ContextRegistry` -- a mapping of protocol index ID -(c.f. :meth:`Protocol.id `) +(cf. :meth:`Protocol.id `) to a :class:`ProtocolContext` instance. The registry is handed to :class:`~pcapkit.foundation.extraction.Extractor` once, and is then propagated down the protocol stack by diff --git a/pcapkit/corekit/decorators.py b/pcapkit/corekit/decorators.py index 517ca02594..af2f56be5d 100644 --- a/pcapkit/corekit/decorators.py +++ b/pcapkit/corekit/decorators.py @@ -180,7 +180,7 @@ def behold(*args: 'P.args', **kwargs: 'P.kwargs') -> 'R_beholder': # NOTE: ``alias=proto`` matches what ``_import_next_layer`` passes, so # a payload that failed to parse still reports the code it arrived # with, which is what ``Data_Raw.protocol`` means. A plain integer has - # no ``name`` and still renders as ``Raw`` in the protochain, c.f. + # no ``name`` and still renders as ``Raw`` in the protochain, cf. # ``Raw.__post_init__``, so this only adds a name where the registry # key is an enumeration. # @@ -289,7 +289,7 @@ def unpack(*args: 'P.args', **kwargs: 'P.kwargs') -> 'R_prepare': if length == 0 and not declared_length: # Quiet: this is the frame reader's ordinary "no more packets" # signal, caught as such by - # ``pcapkit.foundation.extraction.Extractor`` and friends -- c.f. + # ``pcapkit.foundation.extraction.Extractor`` and friends -- cf. # ``pcapkit.protocols.protocol.ProtocolBase._read_unpack``'s # ``StructError(..., quiet=True, eof=True)`` for the same pattern. raise StreamEOFError('prepare: end of stream', quiet=True) diff --git a/pcapkit/corekit/enum.py b/pcapkit/corekit/enum.py index 4daf1b2565..fea478722b 100644 --- a/pcapkit/corekit/enum.py +++ b/pcapkit/corekit/enum.py @@ -372,10 +372,10 @@ def get(cls, key: 'Any', default: 'Any' = NO_DEFAULT) -> 'Self': -- the interpreter's own, unless an earlier loud error installed :mod:`pcapkit`'s. The name miss is :exc:`~pcapkit.utilities.exceptions.EnumKeyError` with - ``quiet=True``, because it is in-library control flow -- at - :meth:`~pcapkit.const.http.method.Method.get` it is part of a - *successful* call, since that override catches it in order to build - an unregistered member. The value miss is quiet through the block + ``quiet=True``, because it is in-library control flow -- in the + ``get`` override of :class:`~pcapkit.const.http.method.Method` it is + part of a *successful* call, since that override catches it in order + to build an unregistered member. The value miss is quiet through the block described above, as ruled on :issue:`1845` on the ground that this method is mostly called from protocol parsing: a value it cannot resolve is input for the caller to handle, not a fault to report. A diff --git a/pcapkit/corekit/fields/__init__.py b/pcapkit/corekit/fields/__init__.py index 6da4929fe0..92225e15d8 100644 --- a/pcapkit/corekit/fields/__init__.py +++ b/pcapkit/corekit/fields/__init__.py @@ -5,7 +5,7 @@ .. module:: pcapkit.corekit.fields -:mod:`pcapkit.corekit.fields` is collection of protocol fields, +:mod:`pcapkit.corekit.fields` is a collection of protocol fields, descriptive of the structure of protocol headers. """ diff --git a/pcapkit/corekit/fields/collections.py b/pcapkit/corekit/fields/collections.py index 9d12671f5e..efa19b1d57 100644 --- a/pcapkit/corekit/fields/collections.py +++ b/pcapkit/corekit/fields/collections.py @@ -208,7 +208,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'byte # of :exc:`~pcapkit.utilities.exceptions.ProtocolError` from # :meth:`TCP._read_mode_sack # `, depending on - # unrelated things that ran earlier in the same process. C.f. #525. + # unrelated things that ran earlier in the same process. Cf. #525. # Importing at module level, once, for the life of this module object, # closes that off: ``SchemaField`` then stays whatever class this # module resolved at its own import time, regardless of what happens to @@ -224,7 +224,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'byte # ``SACK`` option declaring more octets than the option area holds leaves # ``sack``'s ``ListField`` reading ``SACKBlock`` off an exhausted stream. # Remembering where the previous item ended is what bounds the iteration - # count, since it does not depend on what the schema reports. C.f. #431, + # count, since it does not depend on what the schema reports. Cf. #431, # which is the same defect in the ``OptionField`` subclass. # # ``start`` is where the field itself begins. The comparison needs stream @@ -306,7 +306,7 @@ class OptionField(ListField, Generic[_TS]): does not depend on packet data the shortcut has not read. All of that is true of every ``OptionField`` declared in this package. A - base schema registered from outside it -- c.f. + base schema registered from outside it -- cf. :mod:`pcapkit.foundation.registry` -- need not satisfy it, and is **not** rejected: such a base schema is unpacked in full. It parses correctly and pays the cost of the second parse. Only the shortcut is withheld, so a base schema whose type field @@ -434,7 +434,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list # over-reads leaves ``length`` above zero with ``file`` already exhausted, # every field of the next option reads ``b''``, and an option that read # nothing reports ``len(data) == 0`` and leaves ``length`` untouched -- - # which spins forever, with no exception and no diagnostic. C.f. #431. + # which spins forever, with no exception and no diagnostic. Cf. #431. # # 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 @@ -481,7 +481,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> 'list # octets with zeros, so the option would rebuild octets that were never # there: a HIP ``ACK`` declaring 256 octets with 4 present, or an MH # ``PadN`` declaring 3 with none. Nothing downstream can tell, because - # the schema records the zeros as values. C.f. #1325. + # the schema records the zeros as values. Cf. #1325. # # So the stream is read through a proxy that notes any short read, and # an option that began with at least one octet present and then read diff --git a/pcapkit/corekit/fields/field.py b/pcapkit/corekit/fields/field.py index 536fc86a38..e270849b1a 100644 --- a/pcapkit/corekit/fields/field.py +++ b/pcapkit/corekit/fields/field.py @@ -430,7 +430,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> '_T': # cannot recover data that was never in the buffer, only zero-fill for # it, and no field this large is legitimate to begin with. Honouring it # would allocate and zero-fill up to ``length`` octets on nothing but - # the packet's own say-so. C.f. #554. + # the packet's own say-so. Cf. #554. ceiling = config.MAX_ZERO_PAD_LENGTH if ceiling != -1 and length > ceiling and len(buffer) < length: raise FieldValueError( @@ -442,7 +442,7 @@ def unpack(self, buffer: 'bytes | IO[bytes]', packet: 'dict[str, Any]') -> '_T': # declared length just under :data:`~pcapkit.utilities.config.MAX_ZERO_PAD_LENGTH` passes it every # time it is declared, so 200 of them amplify 4,800 wire octets into # 50.0 MiB of retained zeros with the ceiling doing exactly what it was - # written to do. C.f. #573. + # written to do. Cf. #573. # # ``max(length, 0)`` is defensive rather than a case anything is known to # reach. :attr:`length` here resolves through :func:`struct.calcsize`, so diff --git a/pcapkit/corekit/fields/ipaddress.py b/pcapkit/corekit/fields/ipaddress.py index db432b18c7..a10fd35c09 100644 --- a/pcapkit/corekit/fields/ipaddress.py +++ b/pcapkit/corekit/fields/ipaddress.py @@ -103,7 +103,7 @@ def _reject_bool(value: 'object', description: str) -> 'None': :class:`~ipaddress.IPv4Address`'s version mismatches -- and that asymmetry is exactly what let this slip past :issue:`469`'s otherwise equivalent guard for :meth:`MH._make_opt_mn_id - ` (c.f. + ` (cf. :issue:`491`). Every caller checks this *before* dispatching on the value's type, @@ -114,7 +114,7 @@ def _reject_bool(value: 'object', description: str) -> 'None': ``_make_*`` that must know the address family before it can build the schema converts the argument itself and so never hands this module a :obj:`bool` at all. :func:`parse_ip_address` is where those callers - reach this guard (c.f. :issue:`508`). + reach this guard (cf. :issue:`508`). """ if isinstance(value, bool): @@ -145,7 +145,7 @@ def parse_ip_address(value: 'IPv4Address | IPv6Address | bytes | int | str', The converted address. Raises: - FieldValueError: If ``value`` is a :obj:`bool` (c.f. + FieldValueError: If ``value`` is a :obj:`bool` (cf. :func:`_reject_bool`), is not a valid IP address, or is not of ``version``. @@ -260,7 +260,7 @@ def pre_process(self, value: '_AT | bytes | int | str', packet: 'dict[str, Any]' Processed field value. Raises: - FieldValueError: If ``value`` is a :obj:`bool` (c.f. + FieldValueError: If ``value`` is a :obj:`bool` (cf. :func:`_reject_bool`), is not a valid IP address, or is the wrong IP version for this field. @@ -373,7 +373,7 @@ class _RawMaskIPv4Interface(ipaddress.IPv4Interface): in :attr:`netmask`, so :meth:`IPv4InterfaceField.pre_process` writes them back unchanged. - :func:`str`, :func:`repr` and :mod:`pickle` use the ``address/mask`` + :class:`str`, :func:`repr` and :mod:`pickle` use the ``address/mask`` form, which :meth:`IPv4InterfaceField.pre_process` packs back to the same octets. The mask is dotted, except when it is hostmask-shaped (ones, then zeros, read from the low bit): :func:`ipaddress.ip_interface` would read @@ -389,7 +389,7 @@ class _RawMaskIPv4Interface(ipaddress.IPv4Interface): and the prefix length all describe the address alone (``/32``); only :attr:`netmask`, :attr:`hostmask`, :attr:`with_netmask` and :attr:`with_hostmask` carry the mask. :attr:`with_netmask` is always - dotted, so it is not the round-trip form; :func:`str` is. + dotted, so it is not the round-trip form; :class:`str` is. """ @@ -467,7 +467,7 @@ def _is_hostmask(mask: 'IPv4Address') -> 'bool': return not value & (value + 1) -#: Hex spelling of a literal mask, as :func:`str` writes a hostmask-shaped one. +#: Hex spelling of a literal mask, as :class:`str` writes a hostmask-shaped one. _HEX_MASK = re.compile(r'0[xX][0-9a-fA-F]{8}') @@ -584,7 +584,7 @@ def pre_process(self, value: 'IPv4Interface | bytes | int | str', packet: 'dict[ Processed field value. Raises: - FieldValueError: If ``value`` is a :obj:`bool` (c.f. + FieldValueError: If ``value`` is a :obj:`bool` (cf. :func:`_reject_bool`), is not a valid IP interface, or is the wrong IP version for this field. @@ -595,7 +595,7 @@ def pre_process(self, value: 'IPv4Interface | bytes | int | str', packet: 'dict[ taken literally: a dotted mask that is neither a netmask nor a hostmask, such as ``'10.0.0.1/255.0.255.0'``, or eight hex digits, such as ``'10.0.0.1/0x000000ff'``. Those are the forms - :func:`str` gives a :class:`_RawMaskIPv4Interface`. + :class:`str` gives a :class:`_RawMaskIPv4Interface`. """ _reject_bool(value, 'invalid IP interface') @@ -689,7 +689,7 @@ def pre_process(self, value: 'IPv6Interface | bytes | int | str', packet: 'dict[ Processed field value. Raises: - FieldValueError: If ``value`` is a :obj:`bool` (c.f. + FieldValueError: If ``value`` is a :obj:`bool` (cf. :func:`_reject_bool`), is not a valid IP interface, or is the wrong IP version for this field. diff --git a/pcapkit/corekit/fields/numbers.py b/pcapkit/corekit/fields/numbers.py index f7ff4174bc..b29f2fbb05 100644 --- a/pcapkit/corekit/fields/numbers.py +++ b/pcapkit/corekit/fields/numbers.py @@ -355,7 +355,7 @@ def pre_process(self, value: 'int', packet: 'dict[str, Any]') -> 'int | bytes': 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 - disagree. C.f. :issue:`591`. + disagree. Cf. :issue:`591`. That width is a **ceiling** of the bit length over eight, and it is written as one. ``math.ceil(value.bit_length() // 8)`` is not a @@ -850,9 +850,8 @@ def _unregistered_member(namespace: 'Type[StdlibEnum] | Type[AenumEnum]', still raises. Nothing on the parse or reconstruction path does that to a value it just resolved this way, which is what keeps this safe to return from - ``post_process``. A direct call to - :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` for the same port - does not come through here, and it does not mint either: it + ``post_process``. A direct call to ``AppType.get()`` for the same + port does not come through here, and it does not mint either: it builds an unregistered member of its own, through the registry's ``_unregistered_member`` -- measured on this tree, ``AppType.get(54321, proto=tcp)`` returns @@ -1090,8 +1089,7 @@ def post_process(self, value: 'int | bytes', packet: 'dict[str, Any]') -> 'AppTy the port itself, when the registry declares none. Notes: - This peeks at what - :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` itself would + This peeks at what ``AppType.get()`` itself would consult -- the per-port rows via ``__registry__.getlist``, then the documented IANA spans via :meth:`~pcapkit.const.reg.apptype.apptype.AppType._missing_` -- and @@ -1121,8 +1119,8 @@ def post_process(self, value: 'int | bytes', packet: 'dict[str, Any]') -> 'AppTy :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 + ``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 a "no member has this value", so it would quietly turn the rejection into a miss. Within the width, ``_missing_`` diff --git a/pcapkit/corekit/infoclass.py b/pcapkit/corekit/infoclass.py index 8ea28c2aa7..c6f7042516 100644 --- a/pcapkit/corekit/infoclass.py +++ b/pcapkit/corekit/infoclass.py @@ -6,7 +6,7 @@ :mod:`pcapkit.corekit.infoclass` contains :obj:`dict` like class :class:`~pcapkit.corekit.infoclass.Info`, which is originally -designed to work alike :func:`dataclasses.dataclass` as introduced +designed to work like :func:`dataclasses.dataclass` as introduced in :pep:`557`, and the immutable multi-mapping classes :class:`~pcapkit.corekit.infoclass.MultiInfo` and :class:`~pcapkit.corekit.infoclass.OrderedMultiInfo` that a finalised diff --git a/pcapkit/corekit/io.py b/pcapkit/corekit/io.py index 40454aa5ff..9818b236fa 100644 --- a/pcapkit/corekit/io.py +++ b/pcapkit/corekit/io.py @@ -416,12 +416,12 @@ def readlines(self, hint: 'int' = -1, /) -> 'list[bytes]': def seek(self, offset: 'int', whence: 'int' = io.SEEK_SET, /) -> 'int': """Change the stream position to the given byte ``offset``. ``offset`` is interpreted relative to the position indicated by ``whence``. The default value for ``whence`` is - :data:`~io.SEEK_SET`. Values for ``whence`` are: + :data:`~os.SEEK_SET`. Values for ``whence`` are: - * :data:`~io.SEEK_SET` or ``0`` - start of the stream (the default); ``offset`` should + * :data:`~os.SEEK_SET` or ``0`` - start of the stream (the default); ``offset`` should be zero or positive - * :data:`~io.SEEK_CUR` or ``1`` - current stream position; ``offset`` may be negative - * :data:`~io.SEEK_END` or ``2`` - end of the stream; ``offset`` is usually negative + * :data:`~os.SEEK_CUR` or ``1`` - current stream position; ``offset`` may be negative + * :data:`~os.SEEK_END` or ``2`` - end of the stream; ``offset`` is usually negative Return the new absolute position. @@ -435,7 +435,7 @@ def seek(self, offset: 'int', whence: 'int' = io.SEEK_SET, /) -> 'int': error. The negative check applies to every ``whence``, rather than only - :data:`~io.SEEK_SET` looking at its offset. An absolute position below zero + :data:`~os.SEEK_SET` looking at its offset. An absolute position below zero cannot exist under any of them, and it is not the same failure as a position that has merely slid out of the window -- which is ordinary, and recoverable with ``buffer_save=True``. Reporting the first as ``negative seek value`` keeps @@ -443,7 +443,7 @@ def seek(self, offset: 'int', whence: 'int' = io.SEEK_SET, /) -> 'int': the window, it holds with a saved buffer as well, which is exempt from the window check and would otherwise return a negative position as if the seek had worked. - A non-seekable stream has no end until it is over, so :data:`~io.SEEK_END` is + A non-seekable stream has no end until it is over, so :data:`~os.SEEK_END` is as far as :meth:`_read_ahead` reads past the position: ``_read_ahead_size`` octets, a buffer's worth by default, or to the real end if that comes first. The frame readers measure what is left this way, and the engines set that size @@ -451,7 +451,7 @@ def seek(self, offset: 'int', whence: 'int' = io.SEEK_SET, /) -> 'int': edge will not do as the end: once the buffer has filled it is just how far the stream has been read, so the first record ending there would be taken for the end of the capture (:issue:`1586`). The read slides the buffer, so a position before - the one :data:`~io.SEEK_END` was sought from may then be refused, as + the one :data:`~os.SEEK_END` was sought from may then be refused, as :meth:`_read_ahead` says. """ diff --git a/pcapkit/corekit/multidict.py b/pcapkit/corekit/multidict.py index c06ea27e2c..d92649c12d 100644 --- a/pcapkit/corekit/multidict.py +++ b/pcapkit/corekit/multidict.py @@ -131,7 +131,7 @@ class MultiDict(dict, Generic[_KT, _VT]): only return the first value when multiple values for one key are found. See Also: - The class is inspired from and based on the `Werkzeug`_ project (c.f. + The class is inspired from and based on the `Werkzeug`_ project (cf. ``werkzeug.datastructures.MultiDict``). """ diff --git a/pcapkit/corekit/packet.py b/pcapkit/corekit/packet.py index 7161ea0e52..1390533f73 100644 --- a/pcapkit/corekit/packet.py +++ b/pcapkit/corekit/packet.py @@ -53,7 +53,7 @@ class DeferredPacket: A mixin for :class:`~pcapkit.corekit.infoclass.Info` subclasses; see :mod:`pcapkit.corekit.packet` for the contract a subclass keeps. Reading ``packet`` -- as an attribute, as ``x['packet']``, or through - :meth:`to_dict`, :func:`str` or :func:`repr` -- resolves a placeholder once + :meth:`to_dict`, :class:`str` or :func:`repr` -- resolves a placeholder once and keeps the result. ``'packet' in x``, :func:`len` and iteration report the field by name without resolving it. diff --git a/pcapkit/corekit/sentinels.py b/pcapkit/corekit/sentinels.py index ab4f2ad82f..73d3e4b216 100644 --- a/pcapkit/corekit/sentinels.py +++ b/pcapkit/corekit/sentinels.py @@ -201,7 +201,7 @@ class Sentinel(metaclass=SentinelMeta): :func:`copyreg._reconstructor` and so call :meth:`object.__new__` directly. * :meth:`__repr__` returns ``_name`` itself, as ``repr(None)`` is - ``'None'``. :func:`str` gives the same, since nothing here overrides + ``'None'``. :class:`str` gives the same, since nothing here overrides :meth:`object.__str__`. * :meth:`__setattr__` and :meth:`__delattr__` raise :exc:`AttributeError` for every name, as ``None.x = 1`` does, and @@ -554,7 +554,7 @@ def __bool__(self) -> 'Literal[False]': #: :func:`pcapkit.protocols.protocol._declared_keywords` to read a class's #: own ``__keywords__`` out of its :attr:`~object.__dict__`, where #: :obj:`None` is itself a meaningful value -- the opt-out that says the -#: class cannot enumerate its keywords, c.f. +#: class cannot enumerate its keywords, cf. #: :attr:`ProtocolBase.__keywords__ #: `. Never leaves #: :mod:`pcapkit.protocols.protocol`, which imports it from here for exactly diff --git a/pcapkit/corekit/version.py b/pcapkit/corekit/version.py index 221d3ca943..8f8ed845a8 100644 --- a/pcapkit/corekit/version.py +++ b/pcapkit/corekit/version.py @@ -6,7 +6,7 @@ :mod:`pcapkit.corekit.version` contains :obj:`tuple` like class :class:`~pcapkit.corekit.version.VersionInfo`, -which is originally designed alike :class:`sys.version_info`. +modelled on :data:`sys.version_info`. """ import collections @@ -15,7 +15,7 @@ class VersionInfo(collections.namedtuple('VersionInfo', ['major', 'minor'])): - """VersionInfo is alike :class:`sys.version_info`. + """VersionInfo is modelled on :data:`sys.version_info`. .. versionchanged:: 1.3.0 diff --git a/pcapkit/vendor/ipv4/ts_flag.py b/pcapkit/vendor/ipv4/ts_flag.py index 126a90d423..971f788de6 100644 --- a/pcapkit/vendor/ipv4/ts_flag.py +++ b/pcapkit/vendor/ipv4/ts_flag.py @@ -20,7 +20,7 @@ __all__ = ['TSFlag'] -#: TS flag registry [:rfc:`719#section-3.1`]. +#: TS flag registry [:rfc:`791#section-3.1`]. DATA = { 0: 'Timestamp Only', 1: 'IP with Timestamp', @@ -38,7 +38,7 @@ def request(self) -> 'dict[int, str]': # type: ignore[override] # pylint: disab """Fetch registry data. Returns: - Registry data (:data:`~pcapkit.vendor.ipv4.tos_pre.DATA`). + Registry data (:data:`~pcapkit.vendor.ipv4.ts_flag.DATA`). """ return DATA diff --git a/pcapkit/vendor/ipx/packet.py b/pcapkit/vendor/ipx/packet.py index af777b0037..0429758bf9 100644 --- a/pcapkit/vendor/ipx/packet.py +++ b/pcapkit/vendor/ipx/packet.py @@ -86,7 +86,7 @@ #: Every value below is independently corroborated by Wireshark's IPX dissector, #: ``epan/dissectors/packet-ipx.h`` (fetched 2026-09-19), which defines #: ``IPX_PACKET_TYPE_IPX 0``, ``_RIP 1``, ``_ECHO 2``, ``_ERROR 3``, ``_PEP 4``, -#: ``_SPX 5``, ``_NCP 17`` and ``_WANBCAST 20`` -- the same eight values in the +#: ``_SPX 5``, ``_NCP 17`` and ``_WANBCAST 20`` -- the same values in the #: same order. Types 1-5 are inherited from Xerox XNS IDP, which IPX was derived #: from; no RFC assigns them, and the notes below say so where that is the case. DATA = { diff --git a/pcapkit/vendor/ipx/socket.py b/pcapkit/vendor/ipx/socket.py index 4aca94d58e..20a5e6cb4d 100644 --- a/pcapkit/vendor/ipx/socket.py +++ b/pcapkit/vendor/ipx/socket.py @@ -100,12 +100,12 @@ # registration procedure reads "Not assigned by IANA". # * That standard itself, Appendix D, "Assigned well-known socket numbers", # scanned at http://www.bitsavers.org/pdf/xerox/xns/standards/XSIS_028112-Internet_Transport_Protocols_198112.pdf - # -- the same three functions, under a column headed "Well-Known Socket + # -- the same functions, under a column headed "Well-Known Socket # (octal)". # # The *names* are a different matter, and are the archived revision's own. # Both sources call socket 3 "Router Error" rather than "Error Handling - # Packet", and neither appends "Packet" to any of the three. That suffix + # Packet", and neither appends "Packet" to any of them. That suffix # looks like the adjacent packet-type registry bleeding in -- XSIS Appendix # E, "Assigned internet packet types", and the second table on the same IANA # page, which do use 1 Routing Information / 2 Echo / 3 Error as *packet* @@ -258,7 +258,7 @@ #: of this set on that test, because a proprietary protocol may expose no name #: of its own, so the company name serves as its name. :issue:`775`'s final round #: converts it too, so this set does not decide *whether* a range registers -- -#: only *how its name is spelled*: these four keep the bare label with no hex +#: only *how its name is spelled*: these keep the bare label with no hex #: suffix, since the label itself already says nothing was assigned, while #: ``Registered by Xerox`` keeps the hex-suffixed name it always rendered. UNASSIGNED_RANGE_NAMES = frozenset({ diff --git a/pcapkit/vendor/l2tp/type.py b/pcapkit/vendor/l2tp/type.py index ff920116de..4f20aca662 100644 --- a/pcapkit/vendor/l2tp/type.py +++ b/pcapkit/vendor/l2tp/type.py @@ -38,7 +38,7 @@ def request(self) -> 'dict[int, str]': # type: ignore[override] # pylint: disab """Fetch registry data. Returns: - TCP checksum options, i.e. :data:`~pcapkit.vendor.tcp.checksum.DATA`. + L2TP packet types, i.e. :data:`~pcapkit.vendor.l2tp.type.DATA`. """ return DATA diff --git a/pcapkit/vendor/mh/binding_error.py b/pcapkit/vendor/mh/binding_error.py index 9cfd309f92..d862d6a55e 100644 --- a/pcapkit/vendor/mh/binding_error.py +++ b/pcapkit/vendor/mh/binding_error.py @@ -37,7 +37,7 @@ def request(self) -> 'dict[int, str]': # type: ignore[override] # pylint: disab """Fetch registry data. Returns: - Registry data (:data:`~pcapkit.vendor.ipv4.qs_function.DATA`). + Registry data (:data:`~pcapkit.vendor.mh.binding_error.DATA`). """ return DATA diff --git a/pcapkit/vendor/mh/lla_code.py b/pcapkit/vendor/mh/lla_code.py index 9f93cf57c2..81bbed9713 100644 --- a/pcapkit/vendor/mh/lla_code.py +++ b/pcapkit/vendor/mh/lla_code.py @@ -30,7 +30,7 @@ 2: 'MN', #: Link-Layer Address of the NAR (i.e., Proxied Originator). 3: 'NAR', - #: Link-Layer Address of the source of RtSolPr or PrRtAdv. + #: Link-Layer Address of the source of RtSolPr or PrRtAdv #: message. 4: 'RtSolPr or PrRtAdv', #: The access point identified by the LLA belongs to the @@ -56,7 +56,7 @@ def request(self) -> 'dict[int, str]': # type: ignore[override] # pylint: disab """Fetch registry data. Returns: - Registry data (:data:`~pcapkit.vendor.ipv4.qs_function.DATA`). + Registry data (:data:`~pcapkit.vendor.mh.lla_code.DATA`). """ return DATA diff --git a/pcapkit/vendor/reg/apptype/apptype.py b/pcapkit/vendor/reg/apptype/apptype.py index d8f035c114..248f456bd4 100644 --- a/pcapkit/vendor/reg/apptype/apptype.py +++ b/pcapkit/vendor/reg/apptype/apptype.py @@ -49,7 +49,7 @@ #: The canonical service for each port IANA assigns more than one to, per #: transport protocol, as ``{transport: {port: service name}}``. #: -#: IANA genuinely registers three services on TCP/80 -- ``http``, ``www`` and +#: IANA genuinely registers more than one service on TCP/80 -- ``http``, ``www`` and #: ``www-http`` -- and gives no precedence among them, so the registry cannot #: derive which one a port lookup should answer with. Registry row order does not #: supply it either: taken alone it answers many of these pairs differently @@ -800,10 +800,12 @@ def register_alias(cls, port: 'int', name: 'str') -> '{NAME}': # pylint: disabl GitHub issue :issue:`807`'s third ask, deliberately scoped to **this** per-transport registry: ``TCP.register_alias(...)`` never touches - :class:`UDP`'s members, which is what keeps an alias registered on one - transport from leaking onto a transport IANA never assigned it -- e.g. - registering ``www`` as an alias of ``http`` on :class:`TCP` and - :class:`UDP` leaves it absent from :class:`SCTP`'s port 80, exactly as + :class:`~pcapkit.const.reg.apptype.udp.UDP`'s members, which is what + keeps an alias registered on one transport from leaking onto a + transport IANA never assigned it -- e.g. registering ``www`` as an alias + of ``http`` on :class:`~pcapkit.const.reg.apptype.tcp.TCP` and + :class:`~pcapkit.const.reg.apptype.udp.UDP` leaves it absent from + :class:`~pcapkit.const.reg.apptype.sctp.SCTP`'s port 80, exactly as IANA itself never registered it there. No new storage: the new member simply joins :data:`__registry__` at @@ -998,7 +1000,7 @@ class {NAME}(AppType): __registry__: 'MultiDict[int, {NAME}]' = MultiDict() #: The canonical service for each port IANA assigns more than one to, i.e. - #: what :meth:`~pcapkit.const.reg.apptype.apptype.AppType.get` answers with. + #: what ``AppType.get()`` answers with. #: Taken from :file:`/etc/services`, which is what #: :func:`socket.getservbyport` reads -- IANA names no precedence among the #: services it registers on one port, and registry row order does not supply diff --git a/pcapkit/vendor/reg/ethertype.py b/pcapkit/vendor/reg/ethertype.py index 62ff8cccb3..a622e2e6bd 100644 --- a/pcapkit/vendor/reg/ethertype.py +++ b/pcapkit/vendor/reg/ethertype.py @@ -36,13 +36,13 @@ class EtherType(Vendor): #: carrying no real assignment -- a company holding the block but naming #: 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 + #: original ruling on :issue:`775`/:issue:`841` held these 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 #: 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 + #: row registers -- only *how its name is spelled*: these keep the #: bare label with no hex suffix, since the label itself already says #: nothing was assigned, while every other row keeps the hex-suffixed #: name it always rendered.