languages/cpython
languages/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython synced 2024-09-16 04:39:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

gh-112316: Improve docs of inspect.signature and Signature.from_callable (#112317)

Browse source 
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
This commit is contained in:
Nikita Sobolev 2023-12-02 16:13:44 +03:00 committed by GitHub
parent 939fc6d6ea
commit a74daba7ca
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 18 additions and 19 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

37
Doc/library/inspect.rst
View file

@ -620,7 +620,7 @@ 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)
Return a :class:`Signature` object for the given ``callable``:: Return a :class:`Signature` object for the given *callable*::
>>> from inspect import signature >>> from inspect import signature
>>> def foo(a, *, b:int, **kwargs): >>> def foo(a, *, b:int, **kwargs):
@ -646,29 +646,30 @@ function.
For objects defined in modules using stringized annotations For objects defined in modules using stringized annotations
(``from __future__ import annotations``), :func:`signature` will (``from __future__ import annotations``), :func:`signature` will
attempt to automatically un-stringize the annotations using attempt to automatically un-stringize the annotations using
:func:`inspect.get_annotations()`. The :func:`get_annotations`. The
``global``, ``locals``, and ``eval_str`` parameters are passed *global*, *locals*, and *eval_str* parameters are passed
into :func:`inspect.get_annotations()` when resolving the into :func:`get_annotations` when resolving the
annotations; see the documentation for :func:`inspect.get_annotations()` annotations; see the documentation for :func:`get_annotations`
for instructions on how to use these parameters. for instructions on how to use these parameters.
Raises :exc:`ValueError` if no signature can be provided, and Raises :exc:`ValueError` if no signature can be provided, and
:exc:`TypeError` if that type of object is not supported. Also, :exc:`TypeError` if that type of object is not supported. Also,
if the annotations are stringized, and ``eval_str`` is not false, if the annotations are stringized, and *eval_str* is not false,
the ``eval()`` call(s) to un-stringize the annotations could the ``eval()`` call(s) to un-stringize the annotations in :func:`get_annotations`
potentially raise any kind of exception. 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 to it are positional-only. For more info, see
:ref:`the FAQ entry on positional-only parameters <faq-positional-only-arguments>`. :ref:`the FAQ entry on positional-only parameters <faq-positional-only-arguments>`.
.. versionadded:: 3.5 .. versionchanged:: 3.5
``follow_wrapped`` parameter. Pass ``False`` to get a signature of The *follow_wrapped* parameter was added.
``callable`` specifically (``callable.__wrapped__`` will not be used to Pass ``False`` to get a signature of
*callable* specifically (``callable.__wrapped__`` will not be used to
unwrap decorated callables.) unwrap decorated callables.)
.. versionadded:: 3.10 .. versionchanged:: 3.10
``globals``, ``locals``, and ``eval_str`` parameters. The *globals*, *locals*, and *eval_str* parameters were added.
.. note:: .. note::
@ -752,12 +753,10 @@ function.
Signature objects are also supported by generic function Signature objects are also supported by generic function
:func:`copy.replace`. :func:`copy.replace`.
.. classmethod:: Signature.from_callable(obj, *, follow_wrapped=True, globalns=None, localns=None) .. 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 Return a :class:`Signature` (or its subclass) object for a given callable
``obj``. Pass ``follow_wrapped=False`` to get a signature of ``obj`` *obj*.
without unwrapping its ``__wrapped__`` chain. ``globalns`` and
``localns`` will be used as the namespaces when resolving annotations.
This method simplifies subclassing of :class:`Signature`:: This method simplifies subclassing of :class:`Signature`::
@ -770,8 +769,8 @@ function.
.. versionadded:: 3.5 .. versionadded:: 3.5
.. versionadded:: 3.10 .. versionchanged:: 3.10
``globalns`` and ``localns`` parameters. The *globals*, *locals*, and *eval_str* parameters were added.
.. class:: Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty) .. class:: Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)