Skip to content

Commit 5b0e9fd

Browse files
committed
docs(foundation): type the verbose callback's result as Any (#1839)
- Type `VerboseHandler`'s return as `Any` rather than `object`, per the owner's preference on #1867: every caller discards the result, and `Any` accepts any two-argument callback, whatever it returns. - Rewrite the NOTE above the alias to give that reason. - Pin `Any` in the signature test; the exact comparison still fails on a return of `None` or `object`. Refs #1839
1 parent 817208c commit 5b0e9fd

2 files changed

Lines changed: 6 additions & 5 deletions

File tree

‎pcapkit/foundation/extraction.py‎

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

8787
Protocols = Union[str, ProtocolBase, Type[ProtocolBase]]
88-
# NOTE: every caller discards the callback's result. ``object`` rather than
89-
# ``None`` still accepts one that returns something, e.g.
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.
9090
# ``lambda e, f: sys.stdout.write(str(f))``.
91-
VerboseHandler = Callable[['Extractor', Packet], object]
91+
VerboseHandler = Callable[['Extractor', Packet], Any]
9292

9393
__all__ = ['Extractor']
9494

‎tests/project/test_extractor_vfunc_doc_comment_1839_unit.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,8 @@
99
1010
The annotation is the ``VerboseHandler`` alias, whose signature is pinned too:
1111
the frame parameter is the whole ``Packet`` union, and the return is
12-
:class:`object`, because every caller discards it.
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.
1314
1415
Every test reads source text and never imports the package. The one that asks
1516
Sphinx itself skips without it; the others run everywhere.
@@ -44,7 +45,7 @@
4445

4546
#: The alias that types the attribute, and the signature it should spell.
4647
ALIAS = 'VerboseHandler'
47-
SIGNATURE = "Callable[['Extractor', Packet], object]"
48+
SIGNATURE = "Callable[['Extractor', Packet], Any]"
4849

4950
#: A documentation comment line, as :mod:`sphinx.pycode.parser` matches it.
5051
COMMENT = re.compile(r'^\s*#: ?(.*)$')

0 commit comments

Comments
 (0)