Skip to content

Commit ebbe2ea

Browse files
committed
Merge commit '0c0794097' into fold17
2 parents 285a838 + 0c07940 commit ebbe2ea

230 files changed

Lines changed: 8727 additions & 3467 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/experimental.yml‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -334,11 +334,13 @@ jobs:
334334
# - #1963: util/pytest_shards.py runs pytest once per shard `SHARDS`
335335
# names, a directory or a glob of one directory's entries, then once
336336
# over the rest, so every run starts its workers afresh and none
337-
# outlives its heap. Each shard is sized by its largest live heap after
338-
# a full GC on GraalPy. The script runs inside the timeout, scope and
339-
# watcher below, so they hold over the whole tier; on the timeout's
340-
# SIGINT no later run starts. Each shard's run writes a JUnit file of
341-
# its own beside junit.xml.
337+
# outlives its heap. #2713: the shards that lost workers are split by
338+
# their tests' JUnit seconds on GraalPy, each to run in under 5
339+
# minutes; the run over the rest is left whole, as it took about 6.7
340+
# minutes in job 125639681253 and lost no worker. The script runs
341+
# inside the timeout, scope and watcher below, so they hold over the
342+
# whole tier; on the timeout's SIGINT no later run starts. Each shard's
343+
# run writes a JUnit file of its own beside junit.xml.
342344
# - `timeout` sends SIGINT at 110 minutes, under the step's cap, so pytest
343345
# still writes the JUnit XML, and exits 124; SIGKILL 3 minutes on.
344346
# #2020: GNU's `timeout`, which Ubuntu 26.04 installs as `gnutimeout`:
@@ -394,7 +396,10 @@ jobs:
394396
SHARDS: >-
395397
${{ startsWith(matrix.python-version, 'graalpy') && 'tests/const
396398
tests/corekit/test_fields_n* tests/corekit/test_[a-h]* tests/corekit/test_i* tests/corekit
397-
tests/foundation tests/protocols/internet tests/protocols/[a-m]* tests/protocols
399+
tests/foundation/reassembly tests/foundation/test_* tests/foundation
400+
tests/protocols/internet/test_ipv4* tests/protocols/internet/test_ipv6* tests/protocols/internet
401+
tests/protocols/application tests/protocols/link tests/protocols/misc/test_pcapng* tests/protocols/misc
402+
tests/protocols/transport/test_tcp* tests/protocols/transport tests/protocols/test_t* tests/protocols
398403
tests/toolkit' || '' }}
399404
GH_TOKEN: ${{ github.token }}
400405
WATCHER: ${{ steps.watcher.outcome }}

‎docs/source/contributing/conventions/documentation.rst‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,19 @@ while a gerund or infinitive phrase is a noun phrase and needs only re-casing --
4444
been named for sat well below, leaving the page's most navigable artefact
4545
unfindable from the table of contents.
4646

47+
**A module docstring's** ``=`` **title underline runs six past the title**, so the
48+
heading reads balanced. The title is measured as written, inline markup included,
49+
which is how the crawler templates under :mod:`pcapkit.vendor` compute it. Ruled on
50+
:issue:`2718`; :file:`tests/project/test_docs_module_title_underline_2718_unit.py`
51+
fails on an underline of any other length.
52+
53+
.. code-block:: python
54+
55+
"""Some Module
56+
=================
57+
58+
"""
59+
4760
Renaming a Heading
4861
~~~~~~~~~~~~~~~~~~
4962

‎docs/source/contributing/conventions/index.rst‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ House Conventions
1414
questions have mostly arisen;
1515
* :ref:`sentinel-convention` -- :mod:`pcapkit.corekit`;
1616
* :ref:`registry-protocol` -- :mod:`pcapkit.const` again, the registration
17-
wrappers of :mod:`pcapkit.foundation.registry`, and the value a protocol's
17+
wrappers of :mod:`pcapkit.foundation.registry`, how a ``make()`` field holding
18+
an enumeration resolves, and the value a protocol's
1819
:meth:`~pcapkit.protocols.protocol.Protocol.__index__` returns;
1920
* :ref:`extension-header-subclassing` -- a protocol class hierarchy;
2021
* :ref:`protocol-family-grouping` -- how a protocol family's base and members
@@ -28,8 +29,9 @@ House Conventions
2829
reference, rather than any code at all;
2930
* :ref:`test-coverage` -- what the test suite has to prove;
3031
* :ref:`utilities-or-corekit` -- which of :mod:`pcapkit.utilities` and
31-
:mod:`pcapkit.corekit` a support module belongs in, and where a context
32-
variable lives;
32+
:mod:`pcapkit.corekit` a support module belongs in, where a context
33+
variable lives, and where a schema helper used outside the schema layer or
34+
outside its own protocol lives;
3335
* :ref:`reassembly-integration` -- :mod:`pcapkit.foundation.reassembly` and what a
3436
new engine there needs from :mod:`pcapkit.toolkit` and
3537
:mod:`pcapkit.foundation.analysis`;

‎docs/source/contributing/conventions/registry-protocol.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -878,6 +878,43 @@ above, and each type's layout is a
878878
:class:`~pcapkit.protocols.schema.link.radiotap.RadiotapField` subclass, whose fields
879879
are the type's subfields and whose ``__align__`` is its alignment.
880880

881+
.. _registry-protocol-make-fields:
882+
883+
Enumeration Fields of ``make()``
884+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
885+
886+
**A** ``make()`` **field that holds an enumeration takes the member or an**
887+
:class:`int` **code, resolved with the enumeration's**
888+
:meth:`~pcapkit.corekit.enum.EnumLookup.get`. Ruled in review of :pr:`2593`
889+
(:issue:`2489`), for every ``make()`` and every ``_make_*`` maker. Nothing inside
890+
``make()`` turns a :obj:`str` into a member: a name is refused, and a caller holding
891+
one resolves it first with :meth:`Protocol.resolve_index
892+
<pcapkit.protocols.protocol.Protocol.resolve_index>`, which takes the name, a
893+
default, the namespace and whether a :obj:`dict` namespace maps names to codes. No
894+
such field takes an ``X_default``, ``X_namespace`` or ``X_reversed`` keyword beside
895+
it, and none is kept as a shim, ruled on :issue:`2594`.
896+
897+
* **Resolve through** :meth:`~pcapkit.protocols.protocol.Protocol._make_index`, giving
898+
the enumeration and the field's width in bits. It checks the code as
899+
``_make_uint()`` checks an integer -- a :obj:`bool` passes only for a one-bit
900+
field, and a negative or too wide code is refused -- and each refusal is
901+
:exc:`~pcapkit.utilities.exceptions.ProtocolError`, never a masked or wrapped
902+
code, by :issue:`2617`'s ruling. The field's width decides what is refused, not
903+
the enumeration's range, so every code the field carries builds and parses
904+
back. It returns what ``get`` resolves, which is a minted ``Unassigned`` member
905+
for most registries' unassigned codes. Where ``get`` raises :exc:`ValueError` for
906+
a code the field carries, it returns the code itself as an :class:`int`.
907+
* **An option, a sub-option or a chunk given as a** ``(code, arguments)`` **pair
908+
resolves its code the same way**, before anything reads it, so that a
909+
:obj:`bool` is refused rather than read as a padding code.
910+
* **The enumeration is named at the call**, never read from the caller's frame or
911+
from its arguments' defaults: that inference is what :issue:`2356` and
912+
:issue:`2394` broke.
913+
914+
:file:`tests/project/test_make_keyword_groups_2594_unit.py` fails on a maker taking
915+
an ``X_default``, ``X_namespace`` or ``X_reversed`` parameter, on a ``_make_index``
916+
call without the field's width, and on the resolver reaching a frame.
917+
881918
.. _registry-protocol-index:
882919

883920
The Registry Index

‎docs/source/contributing/conventions/utilities-or-corekit.rst‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,46 @@ checks that. What needs IPv4 and IPv6 stays beside
5454
module per checksum family, so a new family sits beside
5555
:mod:`~pcapkit.corekit.checksum.internet`.
5656

57+
Shared Schema Helpers
58+
~~~~~~~~~~~~~~~~~~~~~
59+
60+
**A helper that code outside the schema layer calls lives in**
61+
:mod:`pcapkit.corekit.schema`, one module per group, rather than in the module that
62+
first needed it; the schema layer is :mod:`pcapkit.corekit.fields` and
63+
:mod:`pcapkit.protocols.schema`. It keeps no re-export at its old path. Ruled by the
64+
owner in session, on :issue:`2674`, who grouped these helpers in one package instead
65+
of placing each by the questions above. So
66+
:func:`~pcapkit.corekit.schema.padding.pad_length` is in
67+
:mod:`pcapkit.corekit.schema.padding`, and
68+
:func:`~pcapkit.corekit.schema.shortread.keep_short_read` and
69+
:func:`~pcapkit.corekit.schema.shortread.replay_short_read` in
70+
:mod:`pcapkit.corekit.schema.shortread`. :mod:`pcapkit.corekit.schema` is not the
71+
header schema framework, which stays :mod:`pcapkit.protocols.schema` and its
72+
:class:`~pcapkit.protocols.schema.schema.Schema`; it holds only the helpers shared
73+
across the layer.
74+
75+
**A helper in one protocol's own schema module moves there too once code outside that
76+
protocol uses it and it is generic enough to reuse**, so that another implementor can
77+
find it; a helper only its own protocol calls stays beside the schema. Ruled on
78+
:issue:`2674`. A protocol's own modules are its protocol, data and schema modules. So
79+
:func:`~pcapkit.corekit.schema.jumbogram.jumbo_payload_length`, which the IPv6
80+
pseudo-header and the Scapy toolkit read as well as IPv6 itself, is in
81+
:mod:`pcapkit.corekit.schema.jumbogram`, while
82+
:func:`~pcapkit.protocols.schema.internet.ipv6.jumbogram_error`, which only IPv6
83+
calls, stays in :mod:`pcapkit.protocols.schema.internet.ipv6`. The IPv6 option
84+
helpers in :mod:`pcapkit.protocols.schema.internet.ipv6_option` belong to the HOPOPT
85+
and IPv6-Opts headers that share them, and stay there too.
86+
87+
The field modules and the protocols import these helpers, so a helper module imports
88+
neither of them, nor :mod:`pcapkit.foundation`, outside an ``if TYPE_CHECKING:``
89+
block; the package's ``__init__.py`` imports none of its modules, so a field module
90+
loads only the group it asks for.
91+
:file:`tests/project/test_schema_helpers_boundary_2674_unit.py` fails on a helper
92+
module that does, on a module outside the layer that refers to a function defined in
93+
a field module or in :mod:`pcapkit.protocols.schema.schema`, and on a module outside
94+
a protocol that refers to a function defined in that protocol's schema module, by
95+
import or as an attribute of the module.
96+
5797
Context Variables
5898
~~~~~~~~~~~~~~~~~
5999

‎docs/source/contributing/pep.rst‎

Lines changed: 57 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -991,70 +991,59 @@ since ESP has already laid the groundwork.
991991
Deterministic Construction Arguments
992992
------------------------------------
993993

994-
This is meant to open a broader run of proposals for the construction
995-
(``make()``) workflow in general rather than stand alone -- more will be added
996-
under that heading as they get scoped, and the concrete item ready to write
997-
down now is making a ``make()`` call's own argument list deterministic.
998-
999-
:meth:`~pcapkit.protocols.protocol.Protocol._make_index` is where that is not
1000-
currently true. A number of ``make()`` methods accept a plain ``str``
1001-
enum-member name for a field and resolve it by frame-introspecting the
1002-
caller's locals for a conventional four-argument group -- ``X``,
1003-
``X_default``, ``X_namespace`` and ``X_reversed`` -- looking for the one
1004-
argument whose own default is an enum member, and taking that member's class
1005-
as the namespace to search. The actual contract of a ``make()`` call is
1006-
therefore not fully visible from its own signature: knowing what a bare
1007-
string resolves against means knowing the convention and trusting that every
1008-
call site followed it exactly, rather than reading it off the call itself.
1009-
That gap is exactly how this round's bug family happened. :issue:`2356` is
1010-
the walk coming up empty because the relevant argument's own default is
1011-
``None``, leaving nothing to anchor a namespace to; :issue:`2394` is the same
1012-
inference failing by a different route -- the name is a loop variable over a
1013-
*list* parameter rather than a scalar argument, so the walk's
1014-
``isinstance(value, str)`` check can never see it. Both were fixed narrowly,
1015-
by naming the correct enum explicitly at each affected call site rather than
1016-
touching the inference, so the mechanism is exactly as fragile as it was
1017-
before and just as liable to the same shape of defect at the next call site
1018-
that does not fit its assumptions precisely.
1019-
1020-
The owner's proposed direction -- recorded here, and explicitly **not**
1021-
scheduled for 1.5.0 -- removes the inference rather than patching it again.
1022-
``make()`` would require an actual enum value, or an ``int`` where one is
1023-
already accepted, for these fields, with no implicit string-to-enum
1024-
resolution performed inside ``make()`` itself. In its place, a small public
1025-
wrapper would take the same four-argument group explicitly -- name, default,
1026-
namespace, reversed -- and *resolve* a string name to its enum member on
1027-
request, so a caller holding a bare string calls that helper first and passes
1028-
the resolved value into ``make()``. That mirrors how a finalised
1029-
:class:`~pcapkit.corekit.infoclass.Info` or
1030-
:class:`~pcapkit.protocols.schema.schema.Schema` already settles its
1031-
constructor's keyword set once, when
1032-
:func:`~pcapkit.corekit.infoclass.info_final` or
1033-
:func:`~pcapkit.protocols.schema.schema.schema_final` is applied at
1034-
class-definition time, rather than inferring it afresh at every call --
994+
This opens a broader run of proposals for the construction (``make()``)
995+
workflow in general -- more go under this heading as they get scoped -- and
996+
its first item, making a ``make()`` call's own argument list deterministic, is
997+
**done for 1.6.0** (:issue:`2594`).
998+
999+
Inferring a namespace from the caller's frame, for a conventional
1000+
four-argument group -- ``X``, ``X_default``, ``X_namespace`` and
1001+
``X_reversed`` -- leaves a call's contract invisible from its signature:
1002+
knowing what a bare string resolves against means knowing the convention and
1003+
trusting that every call site follows it exactly. :issue:`2356` and
1004+
:issue:`2394` are that inference failing, the first because an argument's own
1005+
default is ``None``, leaving nothing to anchor a namespace to, the second
1006+
because the name is a loop variable over a *list* parameter, which an
1007+
``isinstance(value, str)`` check on the arguments cannot see. Naming the enum
1008+
at each affected call site fixes an instance and leaves the mechanism as
1009+
fragile as it is.
1010+
1011+
So no ``make()`` infers a member from a string, ruled in review of :pr:`2593`
1012+
(:issue:`2489`): a field holding an enumeration takes the member or an
1013+
``int``, resolved with the enumeration's
1014+
:meth:`~pcapkit.corekit.enum.EnumLookup.get`. That settles a call's contract
1015+
at the signature, the way :func:`~pcapkit.corekit.infoclass.info_final` and
1016+
:func:`~pcapkit.protocols.schema.schema.schema_final` settle a constructor's
1017+
keyword set once at class-definition time, and
10351018
:attr:`~pcapkit.protocols.protocol.Protocol.__own_make_keywords__`
1036-
(:issue:`2286`) settles the same kind of question explicitly rather than
1037-
inferring it, though for a different question: which keywords a ``make()``
1038-
override owns, not what the names passed to it resolve against.
1039-
1040-
The trade-off is real and worth stating rather than glossed over. Accepting a
1041-
bare string for these fields is a pattern used throughout the docs and the
1042-
examples, so dropping the inference is a likely-breaking change at every
1043-
``make()`` call site that currently relies on it -- not a one-line fix.
1044-
Deciding that scope -- which call sites change, whether string acceptance is
1045-
dropped outright or only the silent-inference path behind it, and what the
1046-
wrapper is named and where it lives -- is itself design work, which is
1047-
exactly why this belongs on this page rather than as a quick issue. Done, it
1048-
removes the root cause of the :issue:`2356`/:issue:`2394` family rather than
1049-
leaving its next instance to be found and patched the same way.
1050-
1051-
**Scoped for 1.6.0.** The owner took this direction for every ``make()``, ruled
1052-
in review of :pr:`2593` (:issue:`2489`): a field holding an enum takes the member
1053-
or an ``int``, resolved with the enumeration's ``get`` rather than inferred from
1054-
the caller's frame. The shipped ``X_default``, ``X_namespace`` and ``X_reversed``
1055-
keywords go in 1.6.0 with no deprecation period, ruled on :issue:`2594`, which
1056-
carries the change across :file:`pcapkit/protocols/` in one pass and leaves the
1057-
helper's name and module to it.
1019+
(:issue:`2286`) which keywords a ``make()`` override owns. The pieces:
1020+
1021+
* :meth:`~pcapkit.protocols.protocol.Protocol._make_index` takes the value, the
1022+
enumeration and the field's width, and returns what ``get`` resolves. A
1023+
name, a :obj:`bool` for a field wider than one bit, and a code the field
1024+
cannot carry raise :exc:`~pcapkit.utilities.exceptions.ProtocolError`, so
1025+
every caller gets the range check :issue:`2617` asks for, with no masking.
1026+
An option, a sub-option or a chunk given as a ``(code, arguments)`` pair
1027+
resolves its code the same way.
1028+
* The ``X_default``, ``X_namespace`` and ``X_reversed`` keywords are removed
1029+
in 1.6.0 with no deprecation period and no shim, ruled on :issue:`2594`;
1030+
each class that shipped them records them under ``versionremoved``.
1031+
* The public wrapper is :meth:`Protocol.resolve_index
1032+
<pcapkit.protocols.protocol.Protocol.resolve_index>`, which takes the group
1033+
explicitly -- name, default, namespace, reversed -- so a caller holding a
1034+
bare string resolves it first and passes the result to ``make()``. It is a
1035+
static method every protocol inherits, beside
1036+
:meth:`~pcapkit.protocols.protocol.Protocol.decode` and
1037+
:meth:`~pcapkit.protocols.protocol.Protocol.unquote`, rather than a module of
1038+
its own, since it serves ``make()`` alone.
1039+
1040+
The trade-off: a bare string for these fields is a pattern the docs and the
1041+
examples relied on, so the change breaks every ``make()`` call site that
1042+
relies on the inference. That is why it is one change across
1043+
:file:`pcapkit/protocols/` rather than folded into the next defect fix on this
1044+
family, and it removes the root cause of the :issue:`2356`/:issue:`2394`
1045+
family rather than leaving its next instance to be found and patched the same
1046+
way.
10581047

10591048
Release Plan — 1.5.0 in Two Steps
10601049
---------------------------------
@@ -1387,10 +1376,9 @@ as are IGMP's and GRE's (:issue:`2618`).
13871376
the parsing and the constructing path, rather than a back-reference from a
13881377
parsed protocol to its parent.
13891378

1390-
**Scoped for 1.6.0 — deterministic construction arguments** (:issue:`2594`). See
1379+
**Deterministic construction arguments — done** (:issue:`2594`). See
13911380
`Deterministic Construction Arguments`_ above: every ``make()`` takes an enum
1392-
field as the member or an ``int``, dropping the implicit string-to-enum inference
1393-
and the ``X_default``, ``X_namespace`` and ``X_reversed`` keywords behind it, and
1394-
an explicit helper resolves a bare string. That breaks every call site relying on
1395-
the inference, so it lands as one change rather than folded into the next defect
1396-
fix on this family.
1381+
field as the member or an ``int``, with no string-to-enum inference and no
1382+
``X_default``, ``X_namespace`` and ``X_reversed`` keywords behind it, and
1383+
:meth:`Protocol.resolve_index <pcapkit.protocols.protocol.Protocol.resolve_index>`
1384+
resolves a bare string first.

0 commit comments

Comments
 (0)