python-peps/pep-0362.txt

PEP: 362
Title: Function Signature Object
Version: $Revision$
Last-Modified: $Date$
Author: Brett Cannon <brett@python.org>, Jiwon Seo <seojiwon@gmail.com>,
        Yury Selivanov <yselivanov@sprymix.com>, Larry Hastings <larry@hastings.org>
Status: Draft
Type: Standards Track
Content-Type: text/x-rst
Created: 21-Aug-2006
Python-Version: 3.3
Post-History: 04-Jun-2012


Abstract
========

Python has always supported powerful introspection capabilities,
including introspecting functions and methods.  (For the rest of
this PEP, "function" refers to both functions and methods).  By
examining a function object you can fully reconstruct the function's
signature.  Unfortunately this information is stored in an inconvenient
manner, and is spread across a half-dozen deeply nested attributes.

This PEP proposes a new representation for function signatures.
The new representation contains all necessary information about a function
and its parameters, and makes introspection easy and straightforward.

However, this object does not replace the existing function
metadata, which is used by Python itself to execute those
functions.  The new metadata object is intended solely to make
function introspection easier for Python programmers.


Signature Object
================

A Signature object represents the overall signature of a function.
It stores a `Parameter object`_ for each parameter accepted by the
function, as well as information specific to the function itself.

A Signature object has the following public attributes and methods:

* name : str
    Name of the function.
* qualname : str
    Fully qualified name of the function.
* return_annotation : object
    The annotation for the return type of the function if specified.
    If the function has no annotation for its return type, this
    attribute is not set.
* parameters : OrderedDict
    An ordered mapping of parameters' names to the corresponding
    Parameter objects (keyword-only arguments are in the same order
    as listed in ``code.co_varnames``).
* bind(\*args, \*\*kwargs) -> BoundArguments
    Creates a mapping from positional and keyword arguments to
    parameters.

Once a Signature object is created for a particular function,
it's cached in the ``__signature__`` attribute of that function.

Changes to the Signature object, or to any of its data members,
do not affect the function itself.


Parameter Object
================

Python's expressive syntax means functions can accept many different
kinds of parameters with many subtle semantic differences.  We
propose a rich Parameter object designed to represent any possible
function parameter.

The structure of the Parameter object is:

* name : str
    The name of the parameter as a string.
* default : object
    The default value for the parameter if specified.  If the
    parameter has no default value, this attribute is not set.
* annotation : object
    The annotation for the parameter if specified.  If the
    parameter has no annotation, this attribute is not set.
* is_keyword_only : bool
    True if the parameter is keyword-only, else False.
* is_args : bool
    True if the parameter accepts variable number of arguments
    (``\*args``-like), else False.
* is_kwargs : bool
    True if the parameter accepts variable number of keyword
    arguments (``\*\*kwargs``-like), else False.
* is_implemented : bool
    True if the parameter is implemented for use.  Some platforms
    implement functions but can't support specific parameters
    (e.g. "mode" for os.mkdir).  Passing in an unimplemented
    parameter may result in the parameter being ignored,
    or in NotImplementedError being raised.  It is intended that
    all conditions where ``is_implemented`` may be False be
    thoroughly documented.


BoundArguments Object
=====================

Result of a ``Signature.bind`` call.  Holds the mapping of arguments
to the function's parameters.

Has the following public attributes:

* arguments : OrderedDict
    An ordered mutable mapping of parameters' names to arguments' values.
    Does not contain arguments' default values.
* args : tuple
    Tuple of positional arguments values.  Dynamically computed from
    the 'arguments' attribute.
* kwargs : dict
    Dict of keyword arguments values. Dynamically computed from
    the 'arguments' attribute.

The ``arguments`` attribute should be used in conjunction with
``Signature.parameters`` for any arguments processing purposes.

``args`` and ``kwargs`` properties should be used to invoke functions:
::

    def test(a, *, b):
        ...

    sig = signature(test)
    ba = sig.bind(10, b=20)
    test(*ba.args, **ba.kwargs)


Implementation
==============

An implementation for Python 3.3 can be found here: [#impl]_.
A python issue was also created: [#issue]_.

The implementation adds a new function ``signature()`` to the
``inspect`` module.  ``signature()``  returns the value stored
on the ``__signature__`` attribute if it exists, otherwise it
creates the Signature object for the function and caches it in
the function's ``__signature__``.  (For methods this is stored
directly in the ``__func__`` function object, since that is what
decorators work with.)


Examples
========

Function Signature Renderer
---------------------------
::

    def render_signature(signature):
        '''Renders function definition by its signature.

        Example:

            >>> def test(a:'foo', *, b:'bar', c=True, **kwargs:None) -> 'spam':
            ...    pass

            >>> render_signature(inspect.signature(test))
            test(a:'foo', *, b:'bar', c=True, **kwargs:None) -> 'spam'
        '''

        result = []
        render_kw_only_separator = True
        for param in signature.parameters.values():
            formatted = param.name

            # Add annotation and default value
            if hasattr(param, 'annotation'):
                formatted = '{}:{!r}'.format(formatted, param.annotation)
            if hasattr(param, 'default'):
                formatted = '{}={!r}'.format(formatted, param.default)

            # Handle *args and **kwargs -like parameters
            if param.is_args:
                formatted = '*' + formatted
            elif param.is_kwargs:
                formatted = '**' + formatted

            if param.is_args:
                # OK, we have an '*args'-like parameter, so we won't need
                # a '*' to separate keyword-only arguments
                render_kw_only_separator = False
            elif param.is_keyword_only and render_kw_only_separator:
                # We have a keyword-only parameter to render and we haven't
                # rendered an '*args'-like parameter before, so add a '*'
                # separator to the parameters list ("foo(arg1, *, arg2)" case)
                result.append('*')
                # This condition should be only triggered once, so
                # reset the flag
                render_kw_only_separator = False

            result.append(formatted)

        rendered = '{}({})'.format(signature.name, ', '.join(result))

        if hasattr(signature, 'return_annotation'):
            rendered += ' -> {!r}'.format(signature.return_annotation)

        return rendered


Annotation Checker
------------------
::

    import inspect
    import functools

    def checktypes(func):
        '''Decorator to verify arguments and return types

        Example:

            >>> @checktypes
            ... def test(a:int, b:str) -> int:
            ...     return int(a * b)

            >>> test(10, '1')
            1111111111

            >>> test(10, 1)
            Traceback (most recent call last):
              ...
            ValueError: foo: wrong type of 'b' argument, 'str' expected, got 'int'
        '''

        sig = inspect.signature(func)

        types = {}
        for param in sig.parameters.values():
            # Iterate through function's parameters and build the list of
            # arguments types
            try:
                type_ = param.annotation
            except AttributeError:
                continue
            else:
                if not inspect.isclass(type_):
                    # Not a type, skip it
                    continue

                types[param.name] = type_

                # If the argument has a type specified, let's check that its
                # default value (if present) conforms with the type.
                try:
                    default = param.default
                except AttributeError:
                    continue
                else:
                    if not isinstance(default, type_):
                        raise ValueError("{func}: wrong type of a default value for {arg!r}". \
                                         format(func=sig.qualname, arg=param.name))

        def check_type(sig, arg_name, arg_type, arg_value):
            # Internal function that incapsulates arguments type checking
            if not isinstance(arg_value, arg_type):
                raise ValueError("{func}: wrong type of {arg!r} argument, " \
                                 "{exp!r} expected, got {got!r}". \
                                 format(func=sig.qualname, arg=arg_name,
                                        exp=arg_type.__name__, got=type(arg_value).__name__))

        @functools.wraps(func)
        def wrapper(*args, **kwargs):
            # Let's bind the arguments
            ba = sig.bind(*args, **kwargs)
            for arg_name, arg in ba.arguments.items():
                # And iterate through the bound arguments
                try:
                    type_ = types[arg_name]
                except KeyError:
                    continue
                else:
                    # OK, we have a type for the argument, lets get the corresponding
                    # parameter description from the signature object
                    param = sig.parameters[arg_name]
                    if param.is_args:
                        # If this parameter is a variable-argument parameter,
                        # then we need to check each of its values
                        for value in arg:
                            check_type(sig, arg_name, type_, value)
                    elif param.is_kwargs:
                        # If this parameter is a variable-keyword-argument parameter:
                        for subname, value in arg.items():
                            check_type(sig, arg_name + ':' + subname, type_, value)
                    else:
                        # And, finally, if this parameter a regular one:
                        check_type(sig, arg_name, type_, arg)

            result = func(*ba.args, **ba.kwargs)
            # The last bit - let's check that the result is correct
            try:
                return_type = sig.return_annotation
            except AttributeError:
                # Looks like we don't have any restriction on the return type
                pass
            else:
                if isinstance(return_type, type) and not isinstance(result, return_type):
                    raise ValueError('{func}: wrong return type, {exp} expected, got {got}'. \
                                     format(func=sig.qualname, exp=return_type.__name__,
                                            got=type(result).__name__))
            return result

        return wrapper


Open Issues
===========

When to construct the Signature object?
---------------------------------------

The Signature object can either be created in an eager or lazy
fashion.  In the eager situation, the object can be created during
creation of the function object.  In the lazy situation, one would
pass a function object to a function and that would generate the
Signature object and store it to ``__signature__`` if
needed, and then return the value of ``__signature__``.

In the current implementation, signatures are created only on demand
("lazy").


Deprecate ``inspect.getfullargspec()`` and ``inspect.getcallargs()``?
---------------------------------------------------------------------

Since the Signature object replicates the use of ``getfullargspec()``
and ``getcallargs()`` from the ``inspect`` module it might make sense
to begin deprecating them in 3.3.


References
==========

.. [#impl] pep362 branch (https://bitbucket.org/1st1/cpython/overview)
.. [#issue] issue 15008 (http://bugs.python.org/issue15008)


Copyright
=========

This document has been placed in the public domain.


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   coding: utf-8
   End: