[Python-Dev] Updated PEP 362 (Function Signature Object) (original) (raw)

Brett Cannon brett at python.org
Wed Jun 6 02:26:59 CEST 2012

On behalf of Yury, Larry, Jiwon (wherever he ended up), and myself, here is an updated version of PEP 362 to address Guido's earlier comments. Credit for most of the update should go to Yury with Larry also helping out.

At this point I need a BDFAP and someone to do a code review: http://bugs.python.org/issue15008 .

PEP: 362 Title: Function Signature Object Version: RevisionRevisionRevision Last-Modified: DateDateDate Author: Brett Cannon <brett at python.org>, Jiwon Seo <seojiwon at gmail.com>, Yury Selivanov <yselivanov at sprymix.com>, Larry Hastings < larry at 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:

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:

BoundArguments Object

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

Has the following public attributes:

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: -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20120605/d7b54e80/attachment-0001.html>

More information about the Python-Dev mailing list