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

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