@@ -991,70 +991,59 @@ since ESP has already laid the groundwork.
991991Deterministic 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
10591048Release Plan — 1.5.0 in Two Steps
10601049---------------------------------
@@ -1387,10 +1376,9 @@ as are IGMP's and GRE's (:issue:`2618`).
13871376the parsing and the constructing path, rather than a back-reference from a
13881377parsed 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