Thanks to visit codestin.com
Credit goes to github.com

Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Dec 2, 2023
Merged

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

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
97091c2
gh-112316: Improve docs of `inspect.signature` and `Signature.from_ca…
sobolevn Nov 22, 2023
5b03593
Address review
sobolevn Dec 2, 2023
fea57a9
Apply suggestions from code review
sobolevn Dec 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 18 additions & 19 deletions Doc/library/inspect.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -620,7 +620,7 @@ function.

.. 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
>>> def foo(a, *, b:int, **kwargs):
Expand All @@ -646,29 +646,30 @@ function.
For objects defined in modules using stringized annotations
(``from __future__ import annotations``), :func:`signature` will
attempt to automatically un-stringize the annotations using
:func:`inspect.get_annotations()`. The
``global``, ``locals``, and ``eval_str`` parameters are passed
into :func:`inspect.get_annotations()` when resolving the
annotations; see the documentation for :func:`inspect.get_annotations()`
:func:`get_annotations`. The
*global*, *locals*, and *eval_str* parameters are passed
into :func:`get_annotations` when resolving the
annotations; see the documentation for :func:`get_annotations`
for instructions on how to use these parameters.

Raises :exc:`ValueError` if no signature can be provided, and
:exc:`TypeError` if that type of object is not supported. Also,
if the annotations are stringized, and ``eval_str`` is not false,
the ``eval()`` call(s) to un-stringize the annotations could
potentially raise any kind of exception.
if the annotations are stringized, and *eval_str* is not false,
the ``eval()`` call(s) to un-stringize the annotations in :func:`get_annotations`
could potentially raise any kind of exception.

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

.. versionadded:: 3.5
``follow_wrapped`` parameter. Pass ``False`` to get a signature of
``callable`` specifically (``callable.__wrapped__`` will not be used to
.. versionchanged:: 3.5
The *follow_wrapped* parameter was added.
Pass ``False`` to get a signature of
*callable* specifically (``callable.__wrapped__`` will not be used to
unwrap decorated callables.)

.. versionadded:: 3.10
``globals``, ``locals``, and ``eval_str`` parameters.
.. versionchanged:: 3.10
The *globals*, *locals*, and *eval_str* parameters were added.

.. note::

Expand Down Expand Up @@ -752,12 +753,10 @@ function.
Signature objects are also supported by generic function
: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
``obj``. Pass ``follow_wrapped=False`` to get a signature of ``obj``
without unwrapping its ``__wrapped__`` chain. ``globalns`` and
``localns`` will be used as the namespaces when resolving annotations.
*obj*.

This method simplifies subclassing of :class:`Signature`::

Expand All @@ -770,8 +769,8 @@ function.

.. versionadded:: 3.5

.. versionadded:: 3.10
``globalns`` and ``localns`` parameters.
.. versionchanged:: 3.10
The *globals*, *locals*, and *eval_str* parameters were added.


.. class:: Parameter(name, kind, *, default=Parameter.empty, annotation=Parameter.empty)
Expand Down