@@ -69,25 +69,22 @@ def read_frame(self) -> str:
6969 def test_engine_subclass_registration_is_opt_in (self ) -> None :
7070 """Registration happens if and only if ``engine`` is given.
7171
72- This is the #514 opt-in contract. Before it, ``__init_subclass__`` fell
73- back to ``cls.name`` when the keyword was absent, so *every* subclass of
74- the public class was registered -- which is why no built-in could
75- subclass it and every one of them inherited :class:`EngineBase` under an
76- alias instead.
72+ This is the #514 opt-in contract. It guards against ``__init_subclass__``
73+ falling back to ``cls.name`` when the keyword is absent, which registers
74+ *every* subclass of the public class.
7775
7876 The ``Default`` case is the load-bearing half: it sets
79- ``__engine_name__``, so under the old fallback it registered under
80- ``'defaultengine'``. A class attribute is not a registry key, and it
77+ ``__engine_name__``, so a fallback to ``cls.name`` would register it under
78+ ``'defaultengine'``. A class attribute is not a registry key, so it
8179 registers nothing.
8280
83- No version guard, and that is the point of the rename. The keyword was
84- ``name`` when opt-in registration landed, which made this half of the test
85- unrunnable below Python 3.11 -- ``mcls``/``name``/``bases``/``namespace``
86- collide with :meth:`abc.ABCMeta.__new__`'s own parameters, which are
87- positional-or-keyword before 3.11 and positional-only from 3.11, so the
88- class statement failed in the metaclass before ``__init_subclass__`` ran.
89- ``engine`` is outside that set, so this runs everywhere. Verified on
90- 3.10.21 and 3.14.7.
81+ No version guard, and that is why the keyword is ``engine`` rather than
82+ ``name``: ``mcls``/``name``/``bases``/``namespace`` collide with
83+ :meth:`abc.ABCMeta.__new__`'s own parameters, which are
84+ positional-or-keyword before 3.11 and positional-only from 3.11, so below
85+ Python 3.11 such a class statement fails in the metaclass before
86+ ``__init_subclass__`` runs. ``engine`` is outside that set, so this runs
87+ everywhere. Verified on 3.10.21 and 3.14.7.
9188
9289 """
9390 from pcapkit .foundation .engines .engine import Engine
@@ -123,10 +120,9 @@ def test_engine_subclass_rejects_unrecognised_keyword(self) -> None:
123120
124121 ``Engine`` spells the registry key ``engine`` while ``Reassembly`` and
125122 ``TraceFlow`` spell the same idea ``protocol``, so guessing the wrong one
126- is the expected mistake. It used to land in ``**kwargs``, get dropped by
127- the bare ``super().__init_subclass__()``, and leave the class registered
128- under its own class name. With registration now opt-in the same typo
129- would instead skip registration silently, which is quieter still.
123+ is the expected mistake. Without the guard it lands in ``**kwargs``, is
124+ dropped by a bare ``super().__init_subclass__()``, and, registration being
125+ opt-in, the class silently goes unregistered.
130126
131127 Unguarded by version on purpose: ``protocol`` is not one of the four
132128 names that collide with :meth:`abc.ABCMeta.__new__` below Python 3.11, so
@@ -138,7 +134,7 @@ def test_engine_subclass_rejects_unrecognised_keyword(self) -> None:
138134 version-dependent: below 3.11 the metaclass collision fires before the
139135 guard, so it is a :exc:`TypeError` rather than an
140136 :exc:`~pcapkit.utilities.exceptions.UnsupportedCall`. Loud either way,
141- which is why the rename did not need to chase it.
137+ which is why the guard needs no special case for it.
142138
143139 """
144140 from pcapkit .foundation .engines .engine import Engine
@@ -179,17 +175,18 @@ def test_registration_is_not_inherited_by_a_subclass(self) -> None:
179175 ``final`` marker -- so that subclassing them again cannot register the
180176 subclass under a name nobody chose. That worked, but it is a property of
181177 *which base you inherited*, so it cannot be varied per subclass, and
182- under the old fallback a subclass of a registered class re-registered
183- itself under its own class name.
178+ under a ``cls.name`` fallback a subclass of a registered class
179+ re-registers itself under its own class name.
184180
185181 Keying registration on the keyword instead gives both properties at once:
186182 the parent stays registered, the subclass does not re-register, and a
187183 subclass that *wants* registering can still ask for it. Which is why
188184 ``HTTP``, ``L2TP`` and ``IP`` can be open to inheritance without the
189185 anti-re-registration guarantee being weakened.
190186
191- Runs on every supported version since the keyword became ``engine``;
192- it was skipped below 3.11 while the keyword was ``name``.
187+ Runs on every supported version: ``engine`` does not collide with
188+ :meth:`abc.ABCMeta.__new__`'s own parameters below 3.11, as ``name``
189+ would.
193190
194191 """
195192 from pcapkit .foundation .engines .engine import Engine
0 commit comments