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 <br...@python.org>, Jiwon Seo <seoji...@gmail.com>, Yury Selivanov <yseliva...@sprymix.com>, Larry Hastings < la...@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:
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
