diff --git a/Doc/library/inspect.rst b/Doc/library/inspect.rst index 6568e94..5a4858f 100644 --- a/Doc/library/inspect.rst +++ b/Doc/library/inspect.rst @@ -386,6 +386,261 @@ Retrieving source code onwards is removed. Also, all tabs are expanded to spaces. +.. _inspect-signature-object: + +Introspecting callables with Signature Object +--------------------------------------------- + +Signature object represents the call signature of a callable object and its +return annotation. To get a Signature object use the :func:`signature` +function. + + +.. versionadded:: 3.3 + +.. seealso:: + + :pep:`362` - Function Signature Object. + The detailed specification, implementation details and examples. + + +.. function:: signature(callable) + + Returns a :class:`Signature` object for the given ``callable``:: + + >>> def foo(a, *, b:int, **kwargs): + ... pass + + >>> sig = signature(foo) + + >>> str(sig) + '(a, *, b:int, **kwargs)' + + >>> str(sig.parameters['b']) + 'b:int' + + >>> sig.parameters['b'].annotation + + + Accepts a wide range of python callables, from plain functions and classes + to :func:`functools.partial` objects. + + .. note:: + + Some callables may not be introspectable in certain implementations + of Python. For example, in CPython, built-in functions defined in C + provide no metadata about their arguments. + + +.. class:: Signature + + A Signature object represents the call signature of a function and its + return annotation. For each parameter accepted by the function it + stores a :class:`Parameter` object in its :attr:`parameters` collection. + + Signature objects are *immutable*. Use :meth:`Signature.replace` to make + a modified copy + + .. attribute:: return_annotation + + The "return" annotation for the callable. If the callable has + no "return" annotation, this attribute is set to + :attr:`Signature.empty`. + + .. attribute:: parameters + + An ordered mapping of parameters' names to the corresponding + :class:`Parameter` objects. + + .. method:: bind(*args, **kwargs) + + Creates a mapping from positional and keyword arguments to parameters. + Returns :class:`BoundArguments` if ``*args`` and ``**kwargs`` match + the signature, or raises a :exc:`TypeError`. + + .. method:: bind_partial(*args, **kwargs) + + Works the same way as :meth:`Signature.bind`, but allows the + omission of some required arguments (mimics :func:`functools.partial` + behavior.) Returns :class:`BoundArguments`, or raises a :exc:`TypeError` + if the passed arguments do not match the signature. + + .. method:: replace([parameters], *, [return_annotation]) + + Creates a new Signature instance based on the instance replace was + invoked on. It is possible to pass different ``parameters`` and/or + ``return_annotation`` to override the corresponding properties of + the base signature. To remove return_annotation from the copied + Signature, pass in :attr:`Signature.empty`. + + Example:: + + >>> def test(a, b): pass + >>> sig = signature(test) + >>> new_sig = sig.replace(return_annotation="new return anno") + >>> str(new_sig) + "(a, b) -> 'new return anno'" + + .. attribute:: empty + + A special class-level marker to specify absence of a return annotation. + + +.. class:: Parameter + + Parameter objects are *immutable*. Instead of modifying a Parameter object, + you can use :meth:`Parameter.replace` to create a modified copy. + + .. attribute:: name + + The name of the parameter as a string. Must be a valid python identifier + name (with the exception of ``POSITIONAL_ONLY`` parameters, which can + have it set to ``None``.) + + .. attribute:: default + + The default value for the parameter. If the parameter has no default + value, this attribute is set to :attr:`Parameter.empty`. + + .. attribute:: annotation + + The annotation for the parameter. If the parameter has no annotation, + this attribute is set to :attr:`Parameter.empty`. + + .. attribute:: kind + + Describes how argument values are bound to the parameter. + Possible values (accessible via :class:`Parameter`, like + ``Parameter.KEYWORD_ONLY``): + + +-------------------------+----------------------------------------------+ + | POSITIONAL_ONLY | Value must be supplied as a positional | + | | argument. | + | | | + | | Python has no explicit syntax for defining | + | | positional-only parameters, but many built-in| + | | and extension module functions (especially | + | | those that accept only one or two parameters)| + | | accept them. | + +-------------------------+----------------------------------------------+ + | POSITIONAL_OR_KEYWORD | Value may be supplied as either a keyword or | + | | positional argument (this is the standard | + | | binding behaviour for functions implemented | + | | in Python.) | + +-------------------------+----------------------------------------------+ + | VAR_POSITIONAL | A tuple of positional arguments that aren't | + | | bound to any other parameter. This | + | | corresponds to a ``*args`` parameter in a | + | | Python function definition. | + +-------------------------+----------------------------------------------+ + | KEYWORD_ONLY | Value must be supplied as a keyword argument.| + | | Keyword only parameters are those which | + | | appear after a ``*`` or ``*args`` entry in a | + | | Python function definition. | + +-------------------------+----------------------------------------------+ + | VAR_KEYWORD | A dict of keyword arguments that aren't bound| + | | to any other parameter. This corresponds to a| + | | ``**kwargs`` parameter in a Python function | + | | definition. | + +-------------------------+----------------------------------------------+ + + **Example** + + Print all keyword-only arguments without default values:: + + >>> def foo(a, b, *, c, d=10): + ... pass + + >>> sig = signature(foo) + >>> for param in sig.parameters.values(): + ... if (param.kind == param.KEYWORD_ONLY and + ... param.default is param.empty): + ... print('Parameter:', param) + Parameter: c + + .. method:: replace(*, [name], [kind], [default], [annotation]) + + Creates a new Parameter instance based on the instance replaced was + invoked on. To override a :class:`Parameter` attribute, pass the + corresponding argument. To remove a default value or/and an annotation + from a Parameter, pass :attr:`Parameter.empty`. + + :: + + >>> param = Parameter('foo', Parameter.KEYWORD_ONLY, default=42) + >>> str(param) + 'foo=42' + + >>> str(param.replace()) # Will create a shallow copy of 'param' + 'foo=42' + + >>> str(param.replace(default=Parameter.empty, annotation='spam')) + "foo:'spam'" + + .. attribute:: empty + + A special class-level marker to specify absence of default + values and annotations. + + +.. class:: BoundArguments + + Result of a :meth:`Signature.bind` or :meth:`Signature.bind_partial` call. + Holds the mapping of arguments to the function's parameters. + + .. attribute:: arguments + + An ordered, mutable mapping (:class:`collections.OrderedDict`) of + parameters' names to arguments' values. Contains only explicitly + bound arguments. Changes in :attr:`arguments` will reflect in + :attr:`args` and :attr:`kwargs`. + + Should be used in conjunction with :attr:`Signature.parameters` for + any arguments processing purposes. + + .. note:: + + Arguments for which :meth:`Signature.bind` or + :meth:`Signature.bind_partial` relied on a default value are skipped. + However, if needed, it's easy to include them:: + + >>> def foo(a, b=10): + pass + + >>> sig = signature(foo) + >>> ba = sig.bind(5) + + >>> ba.args, ba.kwargs + ((5,), {}) + + >>> for param in sig.parameters.values(): + ... if param.name not in ba.arguments: + ... ba.arguments[param.name] = param.default + + >>> ba.args, ba.kwargs + ((5, 10), {}) + + + .. attribute:: args + + Tuple of positional arguments values. Dynamically computed + from the :attr:`arguments` attribute. + + .. attribute:: kwargs + + Dict of keyword arguments values. Dynamically computed + from the :attr:`arguments` attribute. + + :attr:`args` and :attr:`kwargs` properties can be used to invoke functions:: + + def test(a, *, b): + ... + + sig = signature(test) + ba = sig.bind(10, b=20) + test(*ba.args, **ba.kwargs) + + .. _inspect-classes-functions: Classes and functions @@ -434,6 +689,10 @@ Classes and functions The first four items in the tuple correspond to :func:`getargspec`. + .. note:: + Consider using the new :ref:`Signature Object ` + interface, which provides a better way of introspecting functions. + .. function:: getargvalues(frame) @@ -496,6 +755,9 @@ Classes and functions .. versionadded:: 3.2 + .. note:: + Consider using the new :meth:`Signature.bind` instead. + .. function:: getclosurevars(func)