[Python-Dev] Updated PEP 362 (Function Signature Object)
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: $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>
More information about the Python-Dev
mailing list