Skip to content

Commit b6bd390

Browse files
committed
docs(tests): drop never-released names (IPv6_GenericExt and helpers)
Problem: docs and tests named IPv6_GenericExt, _PeekableStream, _TCPSegment and _can_seek, none of which is in any release tag. The no-re-export rule already forbids an old-path alias, so the mentions and the absence guards for them add nothing. Fix: remove the conventions page section on IPv6_GenericExt and RetiredNameTests; drop _PeekableStream and _TCPSegment from test docstrings and _TCPSegment from the hasattr loop; drop the _can_seek absence assertion and rename that test to test_can_seek_is_exported. Test: the edited test files, the conventions, docs, docstring-contract and tier-guard tests pass.
1 parent 91147a1 commit b6bd390

5 files changed

Lines changed: 22 additions & 72 deletions

File tree

‎docs/source/contributing/conventions/extension-header-subclassing.rst‎

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -137,23 +137,6 @@ RFC ground in the ``#:`` comment beside it. The test walks
137137
``IPv6_Ext.__subclasses__()`` rather than a hard-coded list, so any further header is
138138
held to the convention whether or not anyone remembers this page.
139139

140-
The Retired ``IPv6_GenericExt`` Name
141-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
142-
143-
The class arrived as ``IPv6_GenericExt``, a fallback parser for an unrecognised
144-
extension header (:issue:`891`), and
145-
:issue:`917` merged that role with
146-
the shared-base role into one class under the shorter name. No compatibility alias
147-
was left behind, and that was deliberate. The owner ruled that the
148-
``IPv6_GenericExt`` name goes for good: it was an intermediate state, and it was never
149-
released.
150-
151-
What makes that safe rather than merely decided: ``IPv6_GenericExt`` existed on
152-
``main`` from ``b3551cb63`` to ``93cf940b3``, under four hours on one day, and no release tag falls
153-
between the two commits -- ``git tag --contains`` names the same tags for both -- so it
154-
appears in **no** release and the break has no callers to inconvenience. Do not
155-
reintroduce it as an alias, and do not cite it as a former public name.
156-
157140
ESP's Two Facts
158141
~~~~~~~~~~~~~~~
159142

‎tests/corekit/test_io_advance_lying_pipe_2108_unit.py‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -106,12 +106,11 @@ class TestCanSeekIsPublic(unittest.TestCase):
106106
def setUp(self) -> None:
107107
reimport_once_per_class(self)
108108

109-
def test_can_seek_is_exported_and_the_private_name_is_gone(self) -> None:
110-
"""No alias keeps the old private name importable."""
109+
def test_can_seek_is_exported(self) -> None:
110+
"""``can_seek`` is listed in the module's ``__all__``."""
111111
from pcapkit.corekit import io as corekit_io # pylint: disable=import-outside-toplevel
112112

113113
self.assertIn('can_seek', corekit_io.__all__)
114-
self.assertFalse(hasattr(corekit_io, '_can_seek'))
115114

116115
def test_can_seek_tells_a_lying_pipe_from_a_seekable_stream(self) -> None:
117116
"""A pipe claiming to seek does not; a stream without a descriptor is trusted."""

‎tests/corekit/test_io_stream_proxies_1516_unit.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,10 @@
44
:class:`~pcapkit.corekit.io.PeekableStream` gives a seekable stream without
55
``peek`` one, for :class:`~pcapkit.foundation.extraction.Extractor` (#1506,
66
#1509). :class:`~pcapkit.corekit.io.NamedStream` gives a stream the ``name``
7-
:func:`pcapfile.savefile.load_savefile` reads, for the PyPCAPFile engine. Both
8-
live beside :class:`~pcapkit.corekit.io.SeekableReader` (formerly the
9-
file-local ``_PeekableStream`` in :mod:`pcapkit.foundation.extraction` and
10-
``_NamedStream`` in :mod:`pcapkit.foundation.engines.pypcapfile`).
7+
:func:`pcapfile.savefile.load_savefile` reads, for the PyPCAPFile engine
8+
(formerly the file-local ``_NamedStream`` in
9+
:mod:`pcapkit.foundation.engines.pypcapfile`). Both live beside
10+
:class:`~pcapkit.corekit.io.SeekableReader`.
1111
1212
Every class is imported from :mod:`pcapkit.corekit.io` inside each test, after
1313
:func:`~tests._support.reimport_once_per_class`.

‎tests/project/test_conventions_doc_claims.py‎

Lines changed: 11 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
44
The *House Conventions* pages, under :file:`docs/source/contributing/conventions/`,
55
record the settled design rulings, and most of what they record is reasoning --
6-
which no test can check. Some of it is not: a per-class classification, a retired
7-
name, an exception type. Those are the parts that rot silently, because Sphinx
6+
which no test can check. Some of it is not: a per-class classification, a forbidden
7+
role, an exception type. Those are the parts that rot silently, because Sphinx
88
builds without ``-W`` and without ``nitpicky``, so a page whose every factual claim
99
has gone stale still renders and CI still passes.
1010
@@ -31,9 +31,6 @@
3131
against the declarations themselves. ``tests/protocols/internet/test_ipv6_ext_unit.py``
3232
already pins the *code* to the ruling; nothing pinned the *page* to the code, which is
3333
the half that goes stale when a new header lands.
34-
* :class:`RetiredNameTests` -- the #924 ruling that the ``IPv6_GenericExt`` name goes for
35-
good. A ruling that a name must not exist is exactly the kind a later change
36-
reintroduces without noticing.
3734
* :class:`FailedLookupExceptionTests` -- the worked example the page gives for a name
3835
miss, which names :exc:`~pcapkit.utilities.exceptions.EnumKeyError`, not the
3936
true but unspecific :exc:`KeyError` (#918).
@@ -48,13 +45,13 @@
4845
* :class:`AenumRoleExclusionTests` -- GitHub issue #934 part C's ruling that
4946
``aenum`` cannot be cross-referenced at all (``conf.py`` excludes it: its
5047
``objects.inv`` carries no ``py:`` objects), converted to plain literals rather
51-
than roles. A forbidden role needs a test or it comes back, exactly as
52-
:class:`RetiredNameTests` guards a retired name. Pins the other half of the same
53-
fix alongside it: the sentinel references #934 part B qualified stay
54-
qualified, since none of ``AbsentType``, ``NoValueType`` or ``ABSENT`` resolves
55-
unqualified outside :file:`docs/source/pcapkit/corekit/sentinels.rst`'s own module
56-
context. Both checks scan every split page rather than one file, since either
57-
could in principle land on any of them.
48+
than roles. A forbidden role needs a test or it comes back. Pins the other
49+
half of the same fix alongside it: the sentinel references #934 part B
50+
qualified stay qualified, since none of ``AbsentType``, ``NoValueType`` or
51+
``ABSENT`` resolves unqualified outside
52+
:file:`docs/source/pcapkit/corekit/sentinels.rst`'s own module context. Both
53+
checks scan every split page rather than one file, since either could in
54+
principle land on any of them.
5855
5956
* :class:`ProcessConventionTests` -- the *process* rulings #918 harvested onto
6057
:file:`process.rst`: what the ``all`` extra carries (#910), what a
@@ -370,9 +367,7 @@ def test_the_index_preamble_does_not_claim_to_be_a_ruling_page_itself(self) -> '
370367
never needs that phrase, since every true statement about ruling content
371368
here names a child page, or says "the pages below" / "here" for the set of
372369
them. Paired with a positive check that the standing-instruction phrase is
373-
present, rather than merely that the single-page one is absent, following
374-
:class:`RetiredNameTests`'s two-sided pattern for a retired name elsewhere
375-
in this module.
370+
present, rather than merely that the single-page one is absent.
376371
377372
"""
378373
text = INDEX.read_text(encoding='utf-8')
@@ -626,31 +621,6 @@ def test_the_page_agrees_with_the_test_that_pins_the_code(self) -> 'None':
626621
set(IPv6ExtSharedBaseContractTests.STANDALONE_MEMBERS))
627622

628623

629-
class RetiredNameTests(unittest.TestCase):
630-
"""#924's ruling that ``IPv6_GenericExt`` goes: an unreleased intermediate name."""
631-
632-
def test_the_retired_base_name_is_absent_from_the_package(self) -> 'None':
633-
"""A ruling that a name must not exist needs a test, or it comes back.
634-
635-
Checked over the package source rather than by import, because the failure
636-
this guards against is a *reintroduced alias* -- which would import perfectly
637-
well and satisfy any behavioural assertion.
638-
639-
"""
640-
offenders = [str(path.relative_to(ROOT))
641-
for path in sorted((ROOT / 'pcapkit').rglob('*.py'))
642-
if 'IPv6_GenericExt' in path.read_text(encoding='utf-8')]
643-
self.assertEqual(offenders, [],
644-
'the retired name is back; the ruling on GitHub pull request '
645-
'#924 is that it was an intermediate state and never released')
646-
647-
def test_the_shared_base_still_carries_the_name_the_ruling_left(self) -> 'None':
648-
"""The other half: the name was renamed, not simply removed."""
649-
from pcapkit.protocols.internet.ipv6_ext import IPv6_Ext
650-
651-
self.assertEqual(IPv6_Ext.__name__, 'IPv6_Ext')
652-
653-
654624
class FailedLookupExceptionTests(unittest.TestCase):
655625
"""The worked example the page gives for a lookup that does not resolve."""
656626

@@ -693,8 +663,7 @@ class AenumRoleExclusionTests(unittest.TestCase):
693663
B converted every such role this page carried to plain double-backtick
694664
literals rather than leaving them promising a link that can never exist. A
695665
forbidden role needs a test, or a later edit reintroduces one without
696-
noticing -- exactly the failure mode :class:`RetiredNameTests` guards a
697-
retired name against.
666+
noticing.
698667
699668
The other half of the same fix is pinned alongside it: the references to
700669
``AbsentType``, ``NoValueType`` and ``ABSENT`` that part B qualified to their

‎tests/toolkit/test_pcap_tcp_segment_public_1570_unit.py‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,10 @@
33
44
The helper the TCP adapters of :mod:`pcapkit.toolkit.pcap` and
55
:mod:`pcapkit.toolkit.pcapng` share was the private ``pcap._tcp_segment``, which
6-
``pcapng`` imported across modules, and its result type was the private
7-
``pcap._TCPSegment``. Under the rulings on #1519 a shared helper becomes public in
8-
the module both callers already import, as ``test_start_line`` did in #1525, so the
9-
two keep their names without the underscore and stay in ``pcap``, which ``pcapng``
10-
already imports. The adapters' end-to-end behaviour is covered by
6+
``pcapng`` imported across modules. Under the rulings on #1519 a shared helper
7+
becomes public in the module both callers already import, as ``test_start_line``
8+
did in #1525, so the helper and its result type are public and stay in ``pcap``,
9+
which ``pcapng`` already imports. The adapters' end-to-end behaviour is covered by
1110
``tests/toolkit/test_pcap_tcp_segment_unit.py``; these tests pin the public surface
1211
and that both toolkits read the segment through it.
1312
@@ -96,7 +95,7 @@ def test_callers_share_the_public_helper(self) -> None:
9695
from pcapkit.toolkit import pcap, pcapng
9796

9897
self.assertIs(pcapng.tcp_segment, pcap.tcp_segment)
99-
for module, name in ((pcap, '_tcp_segment'), (pcap, '_TCPSegment'), (pcapng, '_tcp_segment')):
98+
for module, name in ((pcap, '_tcp_segment'), (pcapng, '_tcp_segment')):
10099
with self.subTest(module=module.__name__, name=name):
101100
self.assertFalse(hasattr(module, name))
102101

0 commit comments

Comments
 (0)