Skip to content

Commit 7b40f7a

Browse files
authored
Merge pull request #1867 from JarryShaw/docs/1839-vfunc-annotation
2 parents 44ed96f + 5b0e9fd commit 7b40f7a

8 files changed

Lines changed: 188 additions & 9 deletions

File tree

‎pcapkit/foundation/engines/dpkt.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -456,7 +456,7 @@ def run(self) -> 'None':
456456
if ext._flag_v:
457457
from pcapkit.toolkit.dpkt import packet2chain # isort:skip
458458
ext._vfunc = lambda e, f: print(
459-
f'Frame {e._frnum:>3d}: {packet2chain(f)}' # pylint: disable=protected-access
459+
f'Frame {e._frnum:>3d}: {packet2chain(cast("DPKTPacket", f))}' # pylint: disable=protected-access
460460
)
461461

462462
# extract global header

‎pcapkit/foundation/engines/pcap_ct.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -402,7 +402,7 @@ def run(self) -> 'None':
402402
if ext._flag_v:
403403
from pcapkit.toolkit.pcap_ct import packet2chain # isort:skip
404404
ext._vfunc = lambda e, f: print(
405-
f'Frame {e._frnum:>3d}: {packet2chain(f[1], data_link=self._dlink)}' # pylint: disable=protected-access
405+
f'Frame {e._frnum:>3d}: {packet2chain(cast("RawFrame", f)[1], data_link=self._dlink)}' # pylint: disable=protected-access
406406
) # pylint: disable=logging-fstring-interpolation
407407

408408
# extract & analyse file

‎pcapkit/foundation/engines/pypcap.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -315,7 +315,7 @@ def run(self) -> 'None':
315315
if ext._flag_v:
316316
from pcapkit.toolkit.pypcap import packet2chain # isort:skip
317317
ext._vfunc = lambda e, f: print(
318-
f'Frame {e._frnum:>3d}: {packet2chain(f[1], data_link=self._dlink)}' # pylint: disable=protected-access
318+
f'Frame {e._frnum:>3d}: {packet2chain(cast("RawFrame", f)[1], data_link=self._dlink)}' # pylint: disable=protected-access
319319
) # pylint: disable=logging-fstring-interpolation
320320

321321
# extract & analyse file

‎pcapkit/foundation/engines/pypcapfile.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -223,7 +223,7 @@ def run(self) -> 'None':
223223
if ext._flag_v:
224224
from pcapkit.toolkit.pypcapfile import packet2chain # isort:skip
225225
ext._vfunc = lambda e, f: print(
226-
f'Frame {e._frnum:>3d}: {packet2chain(f, data_link=self._dlink)}' # pylint: disable=protected-access
226+
f'Frame {e._frnum:>3d}: {packet2chain(cast("PCAPFilePacket", f), data_link=self._dlink)}' # pylint: disable=protected-access
227227
) # pylint: disable=logging-fstring-interpolation
228228

229229
# extract & analyse file

‎pcapkit/foundation/engines/pyshark.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -258,7 +258,7 @@ def run(self) -> 'None':
258258
if ext._flag_v:
259259
ext._vfunc = lambda e, f: print(
260260
f'Frame {e._frnum:>3d}: ' # pylint: disable=protected-access
261-
f'{cast("BaseLayer", _frame_layer(f)).protocols}'
261+
f'{cast("BaseLayer", _frame_layer(cast("PySharkPacket", f))).protocols}'
262262
)
263263

264264
# extract global header

‎pcapkit/foundation/engines/scapy.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -386,7 +386,7 @@ def run(self) -> 'None':
386386
if ext._flag_v:
387387
from pcapkit.toolkit.scapy import packet2chain # isort:skip
388388
ext._vfunc = lambda e, f: print(
389-
f'Frame {e._frnum:>3d}: {packet2chain(f)}' # pylint: disable=protected-access
389+
f'Frame {e._frnum:>3d}: {packet2chain(cast("ScapyPacket", f))}' # pylint: disable=protected-access
390390
)
391391

392392
# extract global header

‎pcapkit/foundation/extraction.py‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,9 @@
8585
PCAPFilePacket, tuple[float, bytes]]
8686

8787
Protocols = Union[str, ProtocolBase, Type[ProtocolBase]]
88+
# NOTE: every caller discards the callback's result, so it is typed ``Any``:
89+
# any two-argument callback is accepted, whatever it returns, e.g.
90+
# ``lambda e, f: sys.stdout.write(str(f))``.
8891
VerboseHandler = Callable[['Extractor', Packet], Any]
8992

9093
__all__ = ['Extractor']
@@ -178,7 +181,7 @@ class Extractor(Generic[_P]):
178181
_flag_s: 'bool'
179182

180183
#: Verbose callback function.
181-
#_vfunc: 'VerboseHandler'
184+
_vfunc: 'VerboseHandler'
182185

183186
#: Frame number.
184187
_frnum: 'int'
@@ -1284,9 +1287,11 @@ def __init__(self,
12841287
# user-facing output on stdout, not diagnostics -- the frame
12851288
# chains are a feature of the tool, so they stay on ``print``
12861289
# rather than becoming log records a consumer has to configure
1287-
# a handler to see (and on a different stream at that).
1290+
# a handler to see (and on a different stream at that). Of the
1291+
# built-in engines only PCAP and PCAPNG keep this callback, so
1292+
# its frame is theirs; the others install their own.
12881293
self._vfunc = lambda e, f: print(
1289-
f'Frame {e._frnum:>3d}: {f.protochain}' # pylint: disable=protected-access
1294+
f'Frame {e._frnum:>3d}: {cast("Frame | PCAPNG", f).protochain}' # pylint: disable=protected-access
12901295
)
12911296
else:
12921297
self._vfunc = lambda e, f: None
Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
1+
# -*- coding: utf-8 -*-
2+
"""Pins the documentation comment and the type of :attr:`Extractor._vfunc`.
3+
4+
GitHub issue #1839: :file:`docs/source/pcapkit/foundation/extraction.rst` asks
5+
for ``.. autoattribute:: _vfunc``, but the annotation under its ``#:`` comment
6+
had been commented out. Sphinx attaches a ``#:`` comment only to the assignment
7+
or annotation directly below it, so the page rendered a bare name with no type
8+
and no description.
9+
10+
The annotation is the ``VerboseHandler`` alias, whose signature is pinned too:
11+
the frame parameter is the whole ``Packet`` union, and the return is
12+
:data:`~typing.Any`, because every caller discards it. The comparison is exact,
13+
so it fails on a return of ``None`` or :class:`object` as well.
14+
15+
Every test reads source text and never imports the package. The one that asks
16+
Sphinx itself skips without it; the others run everywhere.
17+
18+
"""
19+
20+
from __future__ import annotations
21+
22+
import ast
23+
import pathlib
24+
import re
25+
import unittest
26+
from typing import TYPE_CHECKING
27+
28+
from tests.project.test_docs_ambiguous_xrefs_1775_unit import HAS_SPHINX
29+
30+
if TYPE_CHECKING:
31+
from typing import Iterable, Iterator, Optional, Union
32+
33+
Binding = Union[ast.Assign, ast.AnnAssign]
34+
35+
ROOT = pathlib.Path(__file__).resolve().parents[2]
36+
37+
#: The module that declares the attribute, by name and by path.
38+
MODULE = 'pcapkit.foundation.extraction'
39+
SOURCE = ROOT / 'pcapkit' / 'foundation' / 'extraction.py'
40+
41+
#: The documented attribute, and the description its page should render.
42+
CLASS = 'Extractor'
43+
ATTR = '_vfunc'
44+
TEXT = 'Verbose callback function.'
45+
46+
#: The alias that types the attribute, and the signature it should spell.
47+
ALIAS = 'VerboseHandler'
48+
SIGNATURE = "Callable[['Extractor', Packet], Any]"
49+
50+
#: A documentation comment line, as :mod:`sphinx.pycode.parser` matches it.
51+
COMMENT = re.compile(r'^\s*#: ?(.*)$')
52+
53+
54+
def scope_statements(body: 'Iterable[ast.stmt]') -> 'Iterator[ast.stmt]':
55+
"""Yield every statement of a module or class body, including nested blocks.
56+
57+
An ``if TYPE_CHECKING:`` block declares names of the scope it sits in, so the
58+
walk goes into compound statements; it stops at a function or class, which
59+
opens a new scope.
60+
61+
"""
62+
for stmt in body:
63+
if isinstance(stmt, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
64+
continue
65+
yield stmt
66+
for field in ('body', 'orelse', 'finalbody'):
67+
yield from scope_statements(getattr(stmt, field, []))
68+
for handler in getattr(stmt, 'handlers', []):
69+
yield from scope_statements(handler.body)
70+
71+
72+
def bindings(body: 'Iterable[ast.stmt]', name: 'str') -> 'list[Binding]':
73+
"""Return every assignment or annotation of ``name`` in a scope, in order."""
74+
found = [] # type: list[Binding]
75+
for stmt in scope_statements(body):
76+
if isinstance(stmt, ast.AnnAssign):
77+
targets = [stmt.target] # type: list[ast.expr]
78+
elif isinstance(stmt, ast.Assign):
79+
targets = stmt.targets
80+
else:
81+
continue
82+
if any(isinstance(target, ast.Name) and target.id == name for target in targets):
83+
found.append(stmt)
84+
return found
85+
86+
87+
def class_body(tree: 'ast.Module', cls: 'str') -> 'list[ast.stmt]':
88+
"""Return the body of the class ``cls`` defined anywhere in ``tree``."""
89+
classes = [node for node in ast.walk(tree)
90+
if isinstance(node, ast.ClassDef) and node.name == cls]
91+
if not classes:
92+
raise AssertionError(f'no class {cls!r} in {SOURCE}')
93+
return classes[0].body
94+
95+
96+
def doc_comment(source: 'str', cls: 'str', attr: 'str') -> 'Optional[list[str]]':
97+
"""Return the ``#:`` lines Sphinx would attach to ``cls.attr``.
98+
99+
These are the consecutive ``#:`` lines directly above the first assignment
100+
or annotation of ``attr`` in the body of ``cls``. The result is :obj:`None`
101+
when the class body neither assigns nor annotates ``attr``.
102+
103+
"""
104+
found = bindings(class_body(ast.parse(source), cls), attr)
105+
if not found:
106+
return None
107+
108+
lines = [] # type: list[str]
109+
for line in reversed(source.splitlines()[:found[0].lineno - 1]):
110+
match = COMMENT.match(line)
111+
if match is None:
112+
break
113+
lines.append(match.group(1))
114+
return lines[::-1]
115+
116+
117+
class VerboseCallbackDocCommentTests(unittest.TestCase):
118+
"""The ``#:`` comment above :attr:`Extractor._vfunc` attaches to it."""
119+
120+
source = ''
121+
122+
@classmethod
123+
def setUpClass(cls) -> 'None':
124+
cls.source = SOURCE.read_text(encoding='utf-8')
125+
126+
def test_comment_sits_directly_above_the_annotation(self) -> 'None':
127+
comment = doc_comment(self.source, CLASS, ATTR)
128+
self.assertIsNotNone(comment, f'{CLASS} neither annotates nor assigns {ATTR}')
129+
self.assertIn(TEXT, ' '.join(comment or []))
130+
131+
@unittest.skipUnless(HAS_SPHINX, 'Sphinx and sphinx-autodoc-typehints are not installed')
132+
def test_sphinx_attaches_the_comment(self) -> 'None':
133+
from sphinx.pycode import ModuleAnalyzer # pylint: disable=import-outside-toplevel
134+
135+
docs = ModuleAnalyzer.for_string(self.source, MODULE).find_attr_docs()
136+
lines = docs.get((CLASS, ATTR))
137+
self.assertIsNotNone(lines, f'Sphinx attaches no comment to {CLASS}.{ATTR}')
138+
found = '\n'.join(lines or []).strip()
139+
self.assertIn(TEXT, found)
140+
# The first test reads the comment the same way, so it is measuring this.
141+
self.assertEqual('\n'.join(doc_comment(self.source, CLASS, ATTR) or []).strip(), found)
142+
143+
144+
class VerboseHandlerSignatureTests(unittest.TestCase):
145+
""":attr:`Extractor._vfunc` is typed by the precise ``VerboseHandler`` alias."""
146+
147+
source = ''
148+
tree = ast.parse('')
149+
150+
@classmethod
151+
def setUpClass(cls) -> 'None':
152+
cls.source = SOURCE.read_text(encoding='utf-8')
153+
cls.tree = ast.parse(cls.source)
154+
155+
def test_attribute_is_annotated_with_the_alias(self) -> 'None':
156+
annotations = [ast.literal_eval(stmt.annotation)
157+
for stmt in bindings(class_body(self.tree, CLASS), ATTR)
158+
if isinstance(stmt, ast.AnnAssign)]
159+
self.assertEqual(annotations, [ALIAS])
160+
161+
def test_alias_spells_the_precise_signature(self) -> 'None':
162+
found = bindings(self.tree.body, ALIAS)
163+
self.assertEqual(len(found), 1, f'{ALIAS} is not bound exactly once in {SOURCE}')
164+
value = found[0].value
165+
if value is None:
166+
self.fail(f'{ALIAS} is annotated but never assigned')
167+
# Compared as trees, so spacing and quoting do not matter.
168+
expected = ast.parse(SIGNATURE, mode='eval').body
169+
self.assertEqual(ast.dump(value), ast.dump(expected),
170+
f'{ALIAS} = {ast.get_source_segment(self.source, value)}')
171+
172+
173+
if __name__ == '__main__':
174+
unittest.main()

0 commit comments

Comments
 (0)