|
| 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