diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 72b27e2cb..f6ff3f0bb 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -22,6 +22,7 @@ Tick the [commit type](https://github.com/JarryShaw/PyPCAPKit/blob/main/CONTRIBU - [ ] `ci` — workflows or build tooling - [ ] `release` — bumps the version or rolls up a distribution - [ ] `chore` — anything else +- [ ] `const` — regenerates constant or registry tables, members keeping their numeric values --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8ff23fd61..24d47a992 100755 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -205,8 +205,8 @@ BLANK LINE footer (optional) ``` -`type` is one of `feat`, `fix`, `docs`, `test`, `perf`, `refactor`, `ci`, `chore` or `release` — -those are the ones in use. `scope` names the part of the package affected — `tcp`, `corekit`, +`type` is one of `feat`, `fix`, `docs`, `test`, `perf`, `refactor`, `ci`, `chore`, `release` or +`const` — those are the ones in use. `scope` names the part of the package affected — `tcp`, `corekit`, `schema`, `ipv4`, `vendor` — and several are separated by commas inside the parentheses, as in `fix(link,internet):` or `test(utilities,foundation):`. The scope may be omitted where nothing narrower than the whole project applies, as in `docs:`. diff --git a/pcapkit/protocols/protocol.py b/pcapkit/protocols/protocol.py index 3678cedd4..75b04a49f 100644 --- a/pcapkit/protocols/protocol.py +++ b/pcapkit/protocols/protocol.py @@ -720,7 +720,8 @@ def context(self) -> 'ContextRegistry': See Also: :mod:`pcapkit.corekit.context` for what this channel is for, and - :meth:`self._get_context ` for how a + :meth:`self._get_context + ` for how a protocol implementation reaches its own entry. """ @@ -1264,7 +1265,8 @@ def __init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Optional see the note below. packet: Packet context of the enclosing layer, a :obj:`dict` as handed over by - :meth:`self._import_next_layer `. + :meth:`self._import_next_layer + `. While parsing, it is republished as ``__packet__`` so that :meth:`self.unpack ` -- and through it the schema -- can see it; see the note below. @@ -1277,7 +1279,8 @@ def __init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Optional It is consumed here rather than being forwarded to :meth:`self.read `, and is propagated to nested layers by - :meth:`self._import_next_layer `. + :meth:`self._import_next_layer + `. **kwargs: Arbitrary keyword arguments. Raises: @@ -1298,7 +1301,8 @@ def __init__(self, file: 'Optional[IO[bytes] | bytes]' = None, length: 'Optional each of a protocol's producers passes through. That is deliberate, and the normalisation below relies on it: fixing a spelling here fixes it for the engines, for every - :meth:`_import_next_layer ` + :meth:`_import_next_layer + ` implementation, and for any third party protocol that copied their shape, rather than one call site at a time. @@ -1734,7 +1738,8 @@ def __hash__(self) -> 'int': def _get_context(self, cls: 'Optional[Type[_CTX]]' = None) -> 'Optional[_CTX]': """Get the caller supplied context for this protocol, if any. - The lookup is keyed on :meth:`self.id `, so a + The lookup is keyed on :meth:`self.id + `, so a protocol finds its own context without knowing how the caller spelled the registry. @@ -2225,10 +2230,11 @@ def _lookup_registry(registry: 'DefaultDict[Any, _VT]', code: 'Any') -> '_VT': Arguments: registry: dispatch registry to read, i.e. :attr:`self.__proto__ - ` or one of the per-protocol - ``__option__`` / ``__chunk__`` / ``__block__`` family. Passed in - rather than read from the class, so that a caller reaching the - registry through an instance keeps doing so. + ` or one of the + per-protocol ``__option__`` / ``__chunk__`` / ``__block__`` + family. Passed in rather than read from the class, so that a + caller reaching the registry through an instance keeps doing + so. code: registry key to look up, i.e. the wire code being dispatched on Returns: @@ -2261,9 +2267,9 @@ def _lookup_next_layer(registry: 'DefaultDict[int, ModuleDescriptor[ProtocolBase Arguments: registry: next layer protocol registry, i.e. :attr:`self.__proto__ - `. Passed in rather than read from the - class, so that a caller reaching the registry through an - instance keeps doing so. + `. Passed in + rather than read from the class, so that a caller reaching the + registry through an instance keeps doing so. proto: next layer protocol index Returns: @@ -2273,15 +2279,17 @@ def _lookup_next_layer(registry: 'DefaultDict[int, ModuleDescriptor[ProtocolBase Important: The lookup itself is :meth:`self._lookup_registry - `, so a miss does not grow the shared - registry. What this adds is the next-layer-specific resolution step: - the entry found -- registered, or the fallback -- may be a + `, so a miss + does not grow the shared registry. What this adds is the + next-layer-specific resolution step: the entry found -- + registered, or the fallback -- may be a :class:`~pcapkit.corekit.module.ModuleDescriptor` rather than a class, and it is resolved to the class it names. Nothing is written back, on a hit or a miss. A miss has no key to write under, and recording one would be exactly the insertion - :meth:`self._lookup_registry ` exists + :meth:`self._lookup_registry + ` exists to avoid. A hit memoised under ``proto`` would retain a class that :func:`importlib.reload` then makes stale, and would make parsing mutate a registry shared by the whole process (:issue:`1559`). The @@ -2398,8 +2406,10 @@ def _parse_next_layer(klass: 'Type[ProtocolBase]', file_: 'bytes', length: 'int' The captured octets are the first ``length`` of ``file_``, or all of it when it holds fewer, as a truncated capture does. They are short of the header when there are fewer than the next layer's - :meth:`__length_hint__ `, unless the - header it parsed, :attr:`length ` octets long, fits + :meth:`__length_hint__ + `, unless the + header it parsed, :attr:`length + ` octets long, fits in them anyway: for a variable-length header such as :class:`~pcapkit.protocols.link.l2tpv2.L2TPv2` the hint is the longest form rather than the shortest. A next layer that reports no hint is diff --git a/pcapkit/protocols/transport/transport.py b/pcapkit/protocols/transport/transport.py index e6d4031fe..0449ded00 100644 --- a/pcapkit/protocols/transport/transport.py +++ b/pcapkit/protocols/transport/transport.py @@ -185,8 +185,8 @@ def analyze(cls, ports: 'tuple[Enum_AppType, Enum_AppType]', payload: 'bytes', * Nothing is written back on a miss either way, so a payload on an unregistered port does not grow a process-wide registry -- see - :meth:`ProtocolBase._lookup_registry - `. + :meth:`Protocol._lookup_registry + `. .. versionchanged:: 1.5.0 diff --git a/tests/project/test_conventions_doc_claims.py b/tests/project/test_conventions_doc_claims.py index 0505b19da..2372c18c9 100644 --- a/tests/project/test_conventions_doc_claims.py +++ b/tests/project/test_conventions_doc_claims.py @@ -1316,8 +1316,8 @@ def test_the_page_names_every_commit_type_the_template_ticks(self) -> 'None': :file:`.github/PULL_REQUEST_TEMPLATE.md` is where a contributor actually meets the list, so it is the ground truth rather than a list retyped into this file. - Note the label set is a **superset**: ``const`` is a type-ish label with no - tickbox, so this is a one-way check by design. + The check runs one way, template to page, by design: it would not catch a page + label gaining no tickbox, only a tickbox naming no label. """ types = re.findall(r'^- \[ \] `([a-z]+)` ', self.TEMPLATE.read_text(encoding='utf-8'),