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+
2327This module is unit-tier and reads no capture.
2428
2529"""
4145#: A version directive, as Sphinx spells it: reST allows any whitespace after the ``..`` (#1902).
4246DIRECTIVE = 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.
4554ISSUE_VENDORS = (
4655 'ftp/command.py' ,
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
137148def _vendor_trees () -> 'dict[pathlib.Path, ast.Module]' :
@@ -141,7 +152,7 @@ def _vendor_trees() -> 'dict[pathlib.Path, ast.Module]':
141152
142153
143154class 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
158179class 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\n v1.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