Skip to content

Commit 9c2afa2

Browse files
committed
docs(const): move the TransportProtocol 1.5.0 note to the docs and restate get (#2315)
Problem: the apptype template's TransportProtocol comment kept a "Before 1.5.0 ..." release note, and TransportProtocol.get's docstring kept decision history ("So there was no policy here to preserve"), both mirrored in the generated module. Fix: drop the release note from the template and the generated module (edited identically, no re-crawl), carry its bare-``4``-resolves-as-``dccp`` hazard into the reg.rst ``versionchanged:: 1.5.0`` note, and restate get's exception passage as current behaviour. Test: the #1884 guard also refuses release-dated prose ("Before 1.5.0") in pcapkit/const and in vendor template text, and pins the moved note on reg.rst.
1 parent 7b57bb0 commit 9c2afa2

4 files changed

Lines changed: 61 additions & 33 deletions

File tree

‎docs/source/pcapkit/const/reg.rst‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,10 @@ registry is one enumeration per transport protocol sharing a memberless base.
8484
``aenum.IntEnum`` rather than an ``aenum.IntFlag`` (:issue:`808`), numbered
8585
sequentially: ``sctp`` is ``3`` and ``dccp`` is ``4``, where they were ``4``
8686
and ``8``, and no :class:`int` is decoded as a ``|`` composite
87-
(:issue:`860`). Its ``get()`` refuses a name no member declares, with
88-
:exc:`~pcapkit.utilities.exceptions.EnumKeyError`, rather than minting a
87+
(:issue:`860`). An :class:`int` kept from the old numbering, composed or
88+
not, is not refused but can resolve to a different transport: a bare ``4``
89+
is ``dccp``, not ``sctp``. Its ``get()`` refuses a name no member declares,
90+
with :exc:`~pcapkit.utilities.exceptions.EnumKeyError`, rather than minting a
8991
member for it (:issue:`808`, :issue:`923`).
9092

9193
.. autoclass:: pcapkit.const.reg.apptype.apptype.TransportProtocol

‎pcapkit/const/reg/apptype/apptype.py‎

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -58,10 +58,6 @@ class TransportProtocol(EnumLookup, IntEnum):
5858
# value it already is; a plain ``dict.get`` lookup cannot tell a composed
5959
# ``int`` from any other one that happens to equal it. So ``tcp | udp``
6060
# (``3``) resolves as ``sctp``'s own value, silently, with no exception.
61-
# Before 1.5.0 the class was an ``IntFlag`` with ``sctp`` at ``4`` and
62-
# ``dccp`` at ``8``, so an integer held from that numbering (composed or
63-
# not) can land on a different real transport's registry rather than
64-
# merely be refused: a bare ``4`` resolves as ``dccp``'s.
6561

6662
#: No transport protocol. ``TransportProtocol(0) is undefined`` and
6763
#: ``bool(undefined)`` is ``False``; it is the ``proto`` sentinel default
@@ -99,15 +95,13 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
9995
that the exception follows what stdlib's ``Enum`` would raise in the
10096
circumstances, :exc:`ValueError` or :exc:`KeyError` as the case may
10197
be, and comes from :mod:`pcapkit.utilities.exceptions` rather than
102-
being a builtin. A
103-
stdlib ``E['nosuch']`` raises :exc:`KeyError`, and :issue:`923`'s census
104-
found :class:`~pcapkit.corekit.enum.EnumLookup` subclasses answering a
105-
name miss that way. The exceptions were :class:`AppType` and its
106-
per-transport registries, and they answered with :exc:`ValueError` only
107-
because their own ``get()`` takes an :class:`int` port and never accepts
108-
a name at all, rather than from any name-miss policy. So there was no policy here to
109-
preserve, and a name miss reaches the caller as
110-
:exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base. The
98+
being a builtin. A stdlib ``E['nosuch']`` raises :exc:`KeyError`, so a
99+
name miss reaches the caller as
100+
:exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base.
101+
:class:`AppType` and its per-transport registries raise
102+
:exc:`ValueError` from their own ``get()`` because it takes an
103+
:class:`int` port and never accepts a name; that is not a name-miss
104+
policy, so it sets none for this class to follow. The
111105
maintainer's ruling given in review of the work for :issue:`808`, that
112106
:class:`TransportProtocol` is not to be extended at all, holds either
113107
way: the refusal is a refusal and mints nothing, whichever exception

‎pcapkit/vendor/reg/apptype/apptype.py‎

Lines changed: 7 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -150,10 +150,6 @@ class TransportProtocol(EnumLookup, IntEnum):
150150
# value it already is; a plain ``dict.get`` lookup cannot tell a composed
151151
# ``int`` from any other one that happens to equal it. So ``tcp | udp``
152152
# (``3``) resolves as ``sctp``'s own value, silently, with no exception.
153-
# Before 1.5.0 the class was an ``IntFlag`` with ``sctp`` at ``4`` and
154-
# ``dccp`` at ``8``, so an integer held from that numbering (composed or
155-
# not) can land on a different real transport's registry rather than
156-
# merely be refused: a bare ``4`` resolves as ``dccp``'s.
157153
158154
#: No transport protocol. ``TransportProtocol(0) is undefined`` and
159155
#: ``bool(undefined)`` is ``False``; it is the ``proto`` sentinel default
@@ -191,15 +187,13 @@ def get(cls, key: 'int | str', default: 'Any' = NO_DEFAULT) -> 'TransportProtoco
191187
that the exception follows what stdlib's ``Enum`` would raise in the
192188
circumstances, :exc:`ValueError` or :exc:`KeyError` as the case may
193189
be, and comes from :mod:`pcapkit.utilities.exceptions` rather than
194-
being a builtin. A
195-
stdlib ``E['nosuch']`` raises :exc:`KeyError`, and :issue:`923`'s census
196-
found :class:`~pcapkit.corekit.enum.EnumLookup` subclasses answering a
197-
name miss that way. The exceptions were :class:`AppType` and its
198-
per-transport registries, and they answered with :exc:`ValueError` only
199-
because their own ``get()`` takes an :class:`int` port and never accepts
200-
a name at all, rather than from any name-miss policy. So there was no policy here to
201-
preserve, and a name miss reaches the caller as
202-
:exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base. The
190+
being a builtin. A stdlib ``E['nosuch']`` raises :exc:`KeyError`, so a
191+
name miss reaches the caller as
192+
:exc:`~pcapkit.utilities.exceptions.EnumKeyError` from the base.
193+
:class:`AppType` and its per-transport registries raise
194+
:exc:`ValueError` from their own ``get()`` because it takes an
195+
:class:`int` port and never accepts a name; that is not a name-miss
196+
policy, so it sets none for this class to follow. The
203197
maintainer's ruling given in review of the work for :issue:`808`, that
204198
:class:`TransportProtocol` is not to be extended at all, holds either
205199
way: the refusal is a refusal and mints nothing, whichever exception

‎tests/project/test_no_version_directives_in_generated_tables_1884_unit.py‎

Lines changed: 43 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@
2020
checks on a sample module which literals count as template text.
2121
* :class:`TestDocsPages` pins the notes the docs pages carry for the tables (#1884).
2222
23+
The same holds for a release-versioned note written as prose rather than as a
24+
directive, such as "Before 1.5.0 the class was ..." (#2315), so both scans also
25+
refuse :data:`RELEASE_PROSE`.
26+
2327
This module is unit-tier and reads no capture.
2428
2529
"""
@@ -41,6 +45,11 @@
4145
#: A version directive, as Sphinx spells it: reST allows any whitespace after the ``..`` (#1902).
4246
DIRECTIVE = re.compile(r'\.\.\s+version(?:added|changed|removed)::.*')
4347

48+
#: A note dated to a release in prose (#2315): a lead-in such as ``Before`` and
49+
#: a three-part release number. Python versions are spelled with two parts here.
50+
RELEASE_PROSE = re.compile(r'\b(?:[Bb]efore|[Ss]ince|[Uu]ntil|[Aa]s of|[Pp]rior to)\s+'
51+
r'(?:(?:PyPCAPKit|pcapkit|version|release)\s+)?v?\d+\.\d+\.\d+')
52+
4453
#: The crawler modules #1884 names, whose templates must carry no directive.
4554
ISSUE_VENDORS = (
4655
'ftp/command.py',
@@ -65,6 +74,7 @@
6574
('reg.rst', 'versionchanged:: 1.1.1', 'port number'),
6675
('reg.rst', 'versionchanged:: 1.5.0', ':issue:`732`'),
6776
('reg.rst', 'versionchanged:: 1.5.0', ':issue:`808`'),
77+
('reg.rst', 'versionchanged:: 1.5.0', 'a bare ``4``'),
6878
('tcp.rst', 'versionchanged:: 1.5.0', '16-bit'),
6979
)
7080

@@ -127,11 +137,12 @@ def template_literals(tree: 'ast.Module', crawlers: 'frozenset[str]') -> 'list[a
127137
return literals
128138

129139

130-
def template_directives(tree: 'ast.Module', crawlers: 'frozenset[str]') -> 'list[tuple[int, str]]':
131-
"""Every directive in the template text, as ``(literal's first line, directive)``."""
140+
def template_directives(tree: 'ast.Module', crawlers: 'frozenset[str]',
141+
pattern: 're.Pattern[str]' = DIRECTIVE) -> 'list[tuple[int, str]]':
142+
"""Every ``pattern`` match in the template text, as ``(literal's first line, match)``."""
132143
return [(node.lineno, match.group().strip())
133144
for node in template_literals(tree, crawlers)
134-
for match in DIRECTIVE.finditer(node.value)]
145+
for match in pattern.finditer(node.value)]
135146

136147

137148
def _vendor_trees() -> 'dict[pathlib.Path, ast.Module]':
@@ -141,7 +152,7 @@ def _vendor_trees() -> 'dict[pathlib.Path, ast.Module]':
141152

142153

143154
class TestGeneratedModules(unittest.TestCase):
144-
"""No module under :mod:`pcapkit.const` carries a version directive."""
155+
"""No module under :mod:`pcapkit.const` carries a version note."""
145156

146157
def test_no_const_module_carries_a_directive(self) -> 'None':
147158
paths = sorted((ROOT / 'pcapkit' / 'const').rglob('*.py'))
@@ -154,9 +165,19 @@ def test_no_const_module_carries_a_directive(self) -> 'None':
154165
found.append(f'{path.relative_to(ROOT)}:{lineno}: {match.group().strip()}')
155166
self.assertEqual(found, [])
156167

168+
def test_no_const_module_dates_a_note_to_a_release(self) -> 'None':
169+
# #2315: "Before 1.5.0 ..." is a version note in prose.
170+
found = [] # type: list[str]
171+
for path in sorted((ROOT / 'pcapkit' / 'const').rglob('*.py')):
172+
for lineno, line in enumerate(path.read_text(encoding='utf-8').splitlines(), start=1):
173+
match = RELEASE_PROSE.search(line)
174+
if match is not None:
175+
found.append(f'{path.relative_to(ROOT)}:{lineno}: {match.group()}')
176+
self.assertEqual(found, [])
177+
157178

158179
class TestVendorTemplates(unittest.TestCase):
159-
"""No crawler's template text carries a version directive."""
180+
"""No crawler's template text carries a version note."""
160181

161182
def test_no_template_carries_a_directive(self) -> 'None':
162183
trees = _vendor_trees()
@@ -166,6 +187,23 @@ def test_no_template_carries_a_directive(self) -> 'None':
166187
for lineno, directive in template_directives(tree, crawlers)]
167188
self.assertEqual(found, [])
168189

190+
def test_no_template_dates_a_note_to_a_release(self) -> 'None':
191+
# #2315: "Before 1.5.0 ..." is a version note in prose.
192+
trees = _vendor_trees()
193+
crawlers = vendor_classes(trees.values())
194+
found = [f'{path.relative_to(ROOT)}:{lineno}: {match}'
195+
for path, tree in trees.items()
196+
for lineno, match in template_directives(tree, crawlers, RELEASE_PROSE)]
197+
self.assertEqual(found, [])
198+
199+
def test_release_prose_is_matched(self) -> 'None':
200+
for text in ('Before 1.5.0 the class', 'since PyPCAPKit 1.4.1', 'Prior to\nv1.3.0'):
201+
with self.subTest(text=text):
202+
self.assertIsNotNone(RELEASE_PROSE.search(text))
203+
for text in ('from 3.9 only', 'before 3.9', 'RFC 1.5'):
204+
with self.subTest(text=text):
205+
self.assertIsNone(RELEASE_PROSE.search(text))
206+
169207
def test_the_issue_templates_are_read(self) -> 'None':
170208
# Guards the scan above against passing because it read nothing.
171209
trees = _vendor_trees()

0 commit comments

Comments
 (0)