diff --git a/docs/source/pcapkit/corekit/enum.rst b/docs/source/pcapkit/corekit/enum.rst new file mode 100644 index 0000000000..0f9225a482 --- /dev/null +++ b/docs/source/pcapkit/corekit/enum.rst @@ -0,0 +1,29 @@ +Enumeration Base +================ + +.. module:: pcapkit.corekit.enum + +:mod:`pcapkit.corekit.enum` contains the two bases every enumeration in this +library is meant to inherit from: :class:`EnumLookup`, the bare *lookup* half +shared by open registries and closed sets alike, and :class:`EnumRegistry`, +which adds the *mutating* half every generated enumeration under +:mod:`pcapkit.const` inherits. + +.. autoclass:: pcapkit.corekit.enum.EnumLookup + :members: + :show-inheritance: + + .. automethod:: _validate_value + +.. autoclass:: pcapkit.corekit.enum.EnumRegistry + :members: + :show-inheritance: + + .. automethod:: _extend + .. automethod:: _unregistered_member + +Auxiliaries +----------- + +.. autoclass:: pcapkit.corekit.enum.NoDefaultType +.. autodata:: pcapkit.corekit.enum.NO_DEFAULT diff --git a/docs/source/pcapkit/corekit/index.rst b/docs/source/pcapkit/corekit/index.rst index f19ffe30a4..d25939b7a4 100644 --- a/docs/source/pcapkit/corekit/index.rst +++ b/docs/source/pcapkit/corekit/index.rst @@ -10,15 +10,19 @@ class :class:`~pcapkit.corekit.infoclass.Info`, protocol collection class :class:`~pcapkit.corekit.protochain.ProtoChain`, and :class:`~pcapkit.corekit.multidict.MultiDict` family inspired from :mod:`Werkzeug` for multientry :obj:`dict` data mapping, the -:class:`~pcapkit.corekit.fields.field.Field` family for data parsing, and +:class:`~pcapkit.corekit.fields.field.Field` family for data parsing, the :class:`~pcapkit.corekit.context.ContextRegistry` channel for caller -supplied information that a protocol needs but the wire does not carry. +supplied information that a protocol needs but the wire does not carry, and +the :class:`~pcapkit.corekit.enum.EnumLookup`/ +:class:`~pcapkit.corekit.enum.EnumRegistry` bases every constant enumeration +inherits from. .. toctree:: :maxdepth: 2 fields/index context + enum infoclass io module diff --git a/docs/source/pcapkit/index.rst b/docs/source/pcapkit/index.rst index f93514f8d2..d7ce1afbeb 100644 --- a/docs/source/pcapkit/index.rst +++ b/docs/source/pcapkit/index.rst @@ -33,6 +33,16 @@ schema definitions as well as various customisable interfaces. const/index vendor/index +Package Metadata +================ + +.. autodata:: pcapkit.__version__ + + .. seealso:: + + :doc:`../contributing/releasing` for how this value is bumped and + consumed by the release pipeline. + Library Index ============= diff --git a/tests/corekit/test_sentinel_exports_unit.py b/tests/corekit/test_sentinel_exports_unit.py index 314a59dd52..f9865bc1c0 100644 --- a/tests/corekit/test_sentinel_exports_unit.py +++ b/tests/corekit/test_sentinel_exports_unit.py @@ -24,7 +24,7 @@ pins it so a later reading of the ruling cannot escalate into deleting the types. The population is **four**, not the three -:file:`docs/source/conventions.rst` documented -- ``_Absent`` / +:file:`docs/source/contributing/conventions.rst` documented -- ``_Absent`` / ``_AbsentType`` in :mod:`pcapkit.protocols.protocol` is the fourth, missed because a sweep filtered on capitalised names does not see a leading underscore. :class:`SentinelPopulationTests` pins the count and the doc together, so the next @@ -76,7 +76,7 @@ #: Every sentinel in the tree that follows the house ``Type`` convention, #: as ``(instance name, instance, type, module)``. Four, not the three -#: :file:`docs/source/conventions.rst` used to document -- see the module docstring. +#: :file:`docs/source/contributing/conventions.rst` used to document -- see the module docstring. SENTINELS = ( ('NULL', NULL, NullType, 'pcapkit.corekit.module'), ('NoValue', NoValue, NoValueType, 'pcapkit.corekit.fields.field'), @@ -124,7 +124,7 @@ def _star_import(module: 'str') -> 'dict[str, object]': def _sentinel_section() -> 'str': - """The "Naming a sentinel" section of :file:`docs/source/conventions.rst`. + """The "Naming a sentinel" section of :file:`docs/source/contributing/conventions.rst`. Sliced by its own section markers rather than by line number, so an edit elsewhere in the file -- or the move to @@ -167,7 +167,7 @@ def test_enum_exports_the_object_and_not_the_type(self) -> 'None': """``EnumLookup`` and ``EnumRegistry`` are not sentinels and stay. ``EnumLookup`` in particular: GitHub issue #906 split it out as a public - base and :file:`docs/source/conventions.rst` cites its ``get``, so dropping + base and :file:`docs/source/contributing/conventions.rst` cites its ``get``, so dropping it while removing the sentinel type next to it would break that reference. """ @@ -309,7 +309,7 @@ def test_the_sentinel_table_has_a_row_per_sentinel_and_no_more(self) -> 'None': class SentinelBehaviourTests(unittest.TestCase): - """The per-sentinel differences :file:`docs/source/conventions.rst` documents. + """The per-sentinel differences :file:`docs/source/contributing/conventions.rst` documents. Not part of the export change, and asserted here because the doc edit that goes with it makes claims about all four -- an undocumented ``__bool__`` or a missing diff --git a/tests/protocols/test_option_roundtrip_unit.py b/tests/protocols/test_option_roundtrip_unit.py index aa36845c30..5e48fcc928 100644 --- a/tests/protocols/test_option_roundtrip_unit.py +++ b/tests/protocols/test_option_roundtrip_unit.py @@ -113,8 +113,8 @@ class Gap(NamedTuple): #: #: Make it as specific as the message allows, because a fragment that matches #: half the tree does not pin anything: ``'invalid format'`` alone occurs 205 - #: times across 13 modules (31 in :file:`internet/hip.py`, 26 in - #: :file:`transport/tcp.py`), so it is satisfied by a regression at any of + #: times across 13 modules (31 in :file:`pcapkit/protocols/internet/hip.py`, 26 in + #: :file:`pcapkit/protocols/transport/tcp.py`), so it is satisfied by a regression at any of #: them. Prefer the alias and whatever bracketed code the message carries -- #: ``'TCP: [OptNo 28] invalid format'`` narrows those 26 sites to the one #: option that can print ``28``. The tuple form is for messages whose stable