use the :func:`!signature`
function.
-.. function:: signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)
+.. function:: signature(callable, *, follow_wrapped=True, globals=None, locals=None, eval_str=False, annotation_format=Format.VALUE)
Return a :class:`Signature` object for the given *callable*:
*globals*, *locals*, and *eval_str* parameters are passed
into :func:`!annotationlib.get_annotations` when resolving the
annotations; see the documentation for :func:`!annotationlib.get_annotations`
- for instructions on how to use these parameters.
+ for instructions on how to use these parameters. A member of the
+ :class:`annotationlib.Format` enum can be passed to the
+ *annotation_format* parameter to control the format of the returned
+ annotations. For example, use
+ ``annotation_format=annotationlib.Format.STRING`` to return annotations in string
+ format.
Raises :exc:`ValueError` if no signature can be provided, and
:exc:`TypeError` if that type of object is not supported. Also,
the ``eval()`` call(s) to un-stringize the annotations in :func:`annotationlib.get_annotations`
could potentially raise any kind of exception.
- A slash(/) in the signature of a function denotes that the parameters prior
+ A slash (/) in the signature of a function denotes that the parameters prior
to it are positional-only. For more info, see
:ref:`the FAQ entry on positional-only parameters <faq-positional-only-arguments>`.
.. versionchanged:: 3.10
The *globals*, *locals*, and *eval_str* parameters were added.
+ .. versionchanged:: 3.14
+ The *annotation_format* parameter was added.
+
.. note::
Some callables may not be introspectable in certain implementations of
:class:`Signature` objects are also supported by the generic function
:func:`copy.replace`.
- .. method:: format(*, max_width=None)
+ .. method:: format(*, max_width=None, quote_annotation_strings=True)
Create a string representation of the :class:`Signature` object.
If the signature is longer than *max_width*,
all parameters will be on separate lines.
+ If *quote_annotation_strings* is False, :term:`annotations <annotation>`
+ in the signature are displayed without opening and closing quotation
+ marks if they are strings. This is useful if the signature was created with the
+ :attr:`~annotationlib.Format.STRING` format or if
+ ``from __future__ import annotations`` was used.
+
.. versionadded:: 3.13
+ .. versionchanged:: 3.14
+ The *unquote_annotations* parameter was added.
+
.. classmethod:: Signature.from_callable(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False)
Return a :class:`Signature` (or its subclass) object for a given callable
(Contributed by Yorik Hansen in :gh:`123430`.)
+inspect
+-------
+
+* :func:`inspect.signature` takes a new argument *annotation_format* to control
+ the :class:`annotationlib.Format` used for representing annotations.
+ (Contributed by Jelle Zijlstra in :gh:`101552`.)
+
+* :meth:`inspect.Signature.format` takes a new argument *unquote_annotations*.
+ If true, string :term:`annotations <annotation>` are displayed without surrounding quotes.
+ (Contributed by Jelle Zijlstra in :gh:`101552`.)
+
+
json
----
of the error.
(Contributed by Serhiy Storchaka in :gh:`122213`.)
+pydoc
+-----
+
+* :term:`Annotations <annotation>` in help output are now usually
+ displayed in a format closer to that in the original source.
+ (Contributed by Jelle Zijlstra in :gh:`101552`.)
+
+
symtable
--------
import abc
+from annotationlib import Format
from annotationlib import get_annotations # re-exported
import ast
import dis
args, varargs, varkw = getargs(frame.f_code)
return ArgInfo(args, varargs, varkw, frame.f_locals)
-def formatannotation(annotation, base_module=None):
+def formatannotation(annotation, base_module=None, *, quote_annotation_strings=True):
+ if not quote_annotation_strings and isinstance(annotation, str):
+ return annotation
if getattr(annotation, '__module__', None) == 'typing':
def repl(match):
text = match.group()
def _signature_from_function(cls, func, skip_bound_arg=True,
- globals=None, locals=None, eval_str=False):
+ globals=None, locals=None, eval_str=False,
+ *, annotation_format=Format.VALUE):
"""Private helper: constructs Signature for the given python function."""
is_duck_function = False
positional = arg_names[:pos_count]
keyword_only_count = func_code.co_kwonlyargcount
keyword_only = arg_names[pos_count:pos_count + keyword_only_count]
- annotations = get_annotations(func, globals=globals, locals=locals, eval_str=eval_str)
+ annotations = get_annotations(func, globals=globals, locals=locals, eval_str=eval_str,
+ format=annotation_format)
defaults = func.__defaults__
kwdefaults = func.__kwdefaults__
globals=None,
locals=None,
eval_str=False,
- sigcls):
+ sigcls,
+ annotation_format=Format.VALUE):
"""Private helper function to get signature for arbitrary
callable objects.
globals=globals,
locals=locals,
sigcls=sigcls,
- eval_str=eval_str)
+ eval_str=eval_str,
+ annotation_format=annotation_format)
if not callable(obj):
raise TypeError('{!r} is not a callable object'.format(obj))
# of a Python function (Cython functions, for instance), then:
return _signature_from_function(sigcls, obj,
skip_bound_arg=skip_bound_arg,
- globals=globals, locals=locals, eval_str=eval_str)
+ globals=globals, locals=locals, eval_str=eval_str,
+ annotation_format=annotation_format)
if _signature_is_builtin(obj):
return _signature_from_builtin(sigcls, obj,
return type(self)(name, kind, default=default, annotation=annotation)
def __str__(self):
+ return self._format()
+
+ def _format(self, *, quote_annotation_strings=True):
kind = self.kind
formatted = self._name
# Add annotation and default value
if self._annotation is not _empty:
- formatted = '{}: {}'.format(formatted,
- formatannotation(self._annotation))
+ annotation = formatannotation(self._annotation,
+ quote_annotation_strings=quote_annotation_strings)
+ formatted = '{}: {}'.format(formatted, annotation)
if self._default is not _empty:
if self._annotation is not _empty:
@classmethod
def from_callable(cls, obj, *,
- follow_wrapped=True, globals=None, locals=None, eval_str=False):
+ follow_wrapped=True, globals=None, locals=None, eval_str=False,
+ annotation_format=Format.VALUE):
"""Constructs Signature for the given callable object."""
return _signature_from_callable(obj, sigcls=cls,
follow_wrapper_chains=follow_wrapped,
- globals=globals, locals=locals, eval_str=eval_str)
+ globals=globals, locals=locals, eval_str=eval_str,
+ annotation_format=annotation_format)
@property
def parameters(self):
def __str__(self):
return self.format()
- def format(self, *, max_width=None):
+ def format(self, *, max_width=None, quote_annotation_strings=True):
"""Create a string representation of the Signature object.
If *max_width* integer is passed,
signature will try to fit into the *max_width*.
If signature is longer than *max_width*,
all parameters will be on separate lines.
+
+ If *quote_annotation_strings* is False, annotations
+ in the signature are displayed without opening and closing quotation
+ marks. This is useful when the signature was created with the
+ STRING format or when ``from __future__ import annotations`` was used.
"""
result = []
render_pos_only_separator = False
render_kw_only_separator = True
for param in self.parameters.values():
- formatted = str(param)
+ formatted = param._format(quote_annotation_strings=quote_annotation_strings)
kind = param.kind
rendered = '(\n {}\n)'.format(',\n '.join(result))
if self.return_annotation is not _empty:
- anno = formatannotation(self.return_annotation)
+ anno = formatannotation(self.return_annotation,
+ quote_annotation_strings=quote_annotation_strings)
rendered += ' -> {}'.format(anno)
return rendered
-def signature(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False):
+def signature(obj, *, follow_wrapped=True, globals=None, locals=None, eval_str=False,
+ annotation_format=Format.VALUE):
"""Get a signature object for the passed callable."""
return Signature.from_callable(obj, follow_wrapped=follow_wrapped,
- globals=globals, locals=locals, eval_str=eval_str)
+ globals=globals, locals=locals, eval_str=eval_str,
+ annotation_format=annotation_format)
class BufferFlags(enum.IntFlag):
import tokenize
import urllib.parse
import warnings
+from annotationlib import Format
from collections import deque
from reprlib import Repr
from traceback import format_exception_only
def _getargspec(object):
try:
- signature = inspect.signature(object)
+ signature = inspect.signature(object, annotation_format=Format.STRING)
if signature:
name = getattr(object, '__name__', '')
# <lambda> function are always single-line and should not be formatted
max_width = (80 - len(name)) if name != '<lambda>' else None
- return signature.format(max_width=max_width)
+ return signature.format(max_width=max_width, quote_annotation_strings=False)
except (ValueError, TypeError):
argspec = getattr(object, '__text_signature__', None)
if argspec:
--- /dev/null
+def f(x: undefined):
+ pass
+from annotationlib import Format, ForwardRef
import asyncio
import builtins
import collections
import types
import tempfile
import textwrap
-from typing import Unpack
import unicodedata
import unittest
import unittest.mock
from test.test_inspect import inspect_fodder as mod
from test.test_inspect import inspect_fodder2 as mod2
from test.test_inspect import inspect_stringized_annotations
+from test.test_inspect import inspect_deferred_annotations
# Functions tested in this suite:
expected_multiline,
)
+ def test_signature_format_unquote(self):
+ def func(x: 'int') -> 'str': ...
+
+ self.assertEqual(
+ inspect.signature(func).format(),
+ "(x: 'int') -> 'str'"
+ )
+ self.assertEqual(
+ inspect.signature(func).format(quote_annotation_strings=False),
+ "(x: int) -> str"
+ )
+
def test_signature_replace_parameters(self):
def test(a, b) -> 42:
pass
par('b', PORK, annotation=tuple),
)))
+ def test_signature_annotation_format(self):
+ ida = inspect_deferred_annotations
+ sig = inspect.Signature
+ par = inspect.Parameter
+ PORK = inspect.Parameter.POSITIONAL_OR_KEYWORD
+ for signature_func in (inspect.signature, inspect.Signature.from_callable):
+ with self.subTest(signature_func=signature_func):
+ self.assertEqual(
+ signature_func(ida.f, annotation_format=Format.STRING),
+ sig([par("x", PORK, annotation="undefined")])
+ )
+ self.assertEqual(
+ signature_func(ida.f, annotation_format=Format.FORWARDREF),
+ sig([par("x", PORK, annotation=ForwardRef("undefined"))])
+ )
+ with self.assertRaisesRegex(NameError, "undefined"):
+ signature_func(ida.f, annotation_format=Format.VALUE)
+ with self.assertRaisesRegex(NameError, "undefined"):
+ signature_func(ida.f)
+
def test_signature_none_annotation(self):
class funclike:
# Has to be callable, and have correct
class A(builtins.object)
| A(
- | arg1: collections.abc.Callable[[int, int, int], str],
+ | arg1: Callable[[int, int, int], str],
| arg2: Literal['some value', 'other value'],
| arg3: Annotated[int, 'some docs about this type']
| ) -> None
|
| __init__(
| self,
- | arg1: collections.abc.Callable[[int, int, int], str],
+ | arg1: Callable[[int, int, int], str],
| arg2: Literal['some value', 'other value'],
| arg3: Annotated[int, 'some docs about this type']
| ) -> None
self.assertEqual(doc, '''Python Library Documentation: function func in module %s
func(
- arg1: collections.abc.Callable[[typing.Annotated[int, 'Some doc']], str],
+ arg1: Callable[[Annotated[int, 'Some doc']], str],
arg2: Literal[1, 2, 3, 4, 5, 6, 7, 8]
) -> Annotated[int, 'Some other']
''' % __name__)
T = typing.TypeVar('T')
class C(typing.Generic[T], typing.Mapping[int, str]): ...
self.assertEqual(pydoc.render_doc(foo).splitlines()[-1],
- 'f\x08fo\x08oo\x08o(data: List[Any], x: int)'
- ' -> Iterator[Tuple[int, Any]]')
+ 'f\x08fo\x08oo\x08o(data: typing.List[typing.Any], x: int)'
+ ' -> typing.Iterator[typing.Tuple[int, typing.Any]]')
self.assertEqual(pydoc.render_doc(C).splitlines()[2],
'class C\x08C(collections.abc.Mapping, typing.Generic)')
--- /dev/null
+Add an *annoation_format* parameter to :func:`inspect.signature`. Add an
+*quote_annotation_strings* parameter to :meth:`inspect.Signature.format`. Use the
+new functionality to improve the display of annotations in signatures in
+:mod:`pydoc`. Patch by Jelle Zijlstra.
projects / thirdparty / Python / cpython.git / commitdiff
