traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

inspect: Update docstrings; Rename _signature_internal to _signature_from_callable.

This commit is contained in:
Yury Selivanov 2014-03-29 13:47:11 -04:00
parent 67d727e824
commit 5a23bd0d37
1 changed files with 78 additions and 57 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

123
Lib/inspect.py
View File

@ -967,7 +967,7 @@ def getfullargspec(func):
# getfullargspec() historically ignored __wrapped__ attributes,
# so we ensure that remains the case in 3.3+
sig = _signature_internal(func,
sig = _signature_from_callable(func,
follow_wrapper_chains=False,
skip_bound_arg=False,
sigcls=Signature)
@ -1497,6 +1497,10 @@ _NonUserDefinedCallables = (_WrapperDescriptor,
def _signature_get_user_defined_method(cls, method_name):
"""Private helper. Checks if ``cls`` has an attribute
named ``method_name`` and returns it only if it is a
pure python function.
"""
try:
meth = getattr(cls, method_name)
except AttributeError:
@ -1509,9 +1513,10 @@ def _signature_get_user_defined_method(cls, method_name):
def _signature_get_partial(wrapped_sig, partial, extra_args=()):
# Internal helper to calculate how 'wrapped_sig' signature will
# look like after applying a 'functools.partial' object (or alike)
# on it.
"""Private helper to calculate how 'wrapped_sig' signature will
look like after applying a 'functools.partial' object (or alike)
on it.
"""
new_params = OrderedDict(wrapped_sig.parameters.items())
@ -1558,8 +1563,9 @@ def _signature_get_partial(wrapped_sig, partial, extra_args=()):
def _signature_bound_method(sig):
# Internal helper to transform signatures for unbound
# functions to bound methods
"""Private helper to transform signatures for unbound
functions to bound methods.
"""
params = tuple(sig.parameters.values())
@ -1583,8 +1589,9 @@ def _signature_bound_method(sig):
def _signature_is_builtin(obj):
# Internal helper to test if `obj` is a callable that might
# support Argument Clinic's __text_signature__ protocol.
"""Private helper to test if `obj` is a callable that might
support Argument Clinic's __text_signature__ protocol.
"""
return (isbuiltin(obj) or
ismethoddescriptor(obj) or
isinstance(obj, _NonUserDefinedCallables) or
@ -1594,10 +1601,11 @@ def _signature_is_builtin(obj):
def _signature_is_functionlike(obj):
# Internal helper to test if `obj` is a duck type of FunctionType.
# A good example of such objects are functions compiled with
# Cython, which have all attributes that a pure Python function
# would have, but have their code statically compiled.
"""Private helper to test if `obj` is a duck type of FunctionType.
A good example of such objects are functions compiled with
Cython, which have all attributes that a pure Python function
would have, but have their code statically compiled.
"""
if not callable(obj) or isclass(obj):
# All function-like objects are obviously callables,
@ -1618,11 +1626,12 @@ def _signature_is_functionlike(obj):
def _signature_get_bound_param(spec):
# Internal helper to get first parameter name from a
# __text_signature__ of a builtin method, which should
# be in the following format: '($param1, ...)'.
# Assumptions are that the first argument won't have
# a default value or an annotation.
""" Private helper to get first parameter name from a
__text_signature__ of a builtin method, which should
be in the following format: '($param1, ...)'.
Assumptions are that the first argument won't have
a default value or an annotation.
"""
assert spec.startswith('($')
@ -1641,7 +1650,9 @@ def _signature_get_bound_param(spec):
def _signature_strip_non_python_syntax(signature):
"""
Takes a signature in Argument Clinic's extended signature format.
Private helper function. Takes a signature in Argument Clinic's
extended signature format.
Returns a tuple of three things:
* that signature re-rendered in standard Python syntax,
* the index of the "self" parameter (generally 0), or None if
@ -1710,8 +1721,10 @@ def _signature_strip_non_python_syntax(signature):
def _signature_fromstr(cls, obj, s, skip_bound_arg=True):
# Internal helper to parse content of '__text_signature__'
# and return a Signature based on it
"""Private helper to parse content of '__text_signature__'
and return a Signature based on it.
"""
Parameter = cls._parameter_cls
clean_signature, self_parameter, last_positional_only = \
@ -1849,8 +1862,10 @@ def _signature_fromstr(cls, obj, s, skip_bound_arg=True):
def _signature_from_builtin(cls, func, skip_bound_arg=True):
# Internal helper function to get signature for
# builtin callables
"""Private helper function to get signature for
builtin callables.
"""
if not _signature_is_builtin(func):
raise TypeError("{!r} is not a Python builtin "
"function".format(func))
@ -1862,18 +1877,22 @@ def _signature_from_builtin(cls, func, skip_bound_arg=True):
return _signature_fromstr(cls, func, s, skip_bound_arg)
def _signature_internal(obj, *,
def _signature_from_callable(obj, *,
follow_wrapper_chains=True,
skip_bound_arg=True,
sigcls):
"""Private helper function to get signature for arbitrary
callable objects.
"""
if not callable(obj):
raise TypeError('{!r} is not a callable object'.format(obj))
if isinstance(obj, types.MethodType):
# In this case we skip the first parameter of the underlying
# function (usually `self` or `cls`).
sig = _signature_internal(
sig = _signature_from_callable(
obj.__func__,
follow_wrapper_chains=follow_wrapper_chains,
skip_bound_arg=skip_bound_arg,
@ -1909,7 +1928,7 @@ def _signature_internal(obj, *,
# (usually `self`, or `cls`) will not be passed
# automatically (as for boundmethods)
wrapped_sig = _signature_internal(
wrapped_sig = _signature_from_callable(
partialmethod.func,
follow_wrapper_chains=follow_wrapper_chains,
skip_bound_arg=skip_bound_arg,
@ -1932,7 +1951,7 @@ def _signature_internal(obj, *,
skip_bound_arg=skip_bound_arg)
if isinstance(obj, functools.partial):
wrapped_sig = _signature_internal(
wrapped_sig = _signature_from_callable(
obj.func,
follow_wrapper_chains=follow_wrapper_chains,
skip_bound_arg=skip_bound_arg,
@ -1947,7 +1966,7 @@ def _signature_internal(obj, *,
# in its metaclass
call = _signature_get_user_defined_method(type(obj), '__call__')
if call is not None:
sig = _signature_internal(
sig = _signature_from_callable(
call,
follow_wrapper_chains=follow_wrapper_chains,
skip_bound_arg=skip_bound_arg,
@ -1956,7 +1975,7 @@ def _signature_internal(obj, *,
# Now we check if the 'obj' class has a '__new__' method
new = _signature_get_user_defined_method(obj, '__new__')
if new is not None:
sig = _signature_internal(
sig = _signature_from_callable(
new,
follow_wrapper_chains=follow_wrapper_chains,
skip_bound_arg=skip_bound_arg,
@ -1965,7 +1984,7 @@ def _signature_internal(obj, *,
# Finally, we should have at least __init__ implemented
init = _signature_get_user_defined_method(obj, '__init__')
if init is not None:
sig = _signature_internal(
sig = _signature_from_callable(
init,
follow_wrapper_chains=follow_wrapper_chains,
skip_bound_arg=skip_bound_arg,
@ -2011,7 +2030,7 @@ def _signature_internal(obj, *,
call = _signature_get_user_defined_method(type(obj), '__call__')
if call is not None:
try:
sig = _signature_internal(
sig = _signature_from_callable(
call,
follow_wrapper_chains=follow_wrapper_chains,
skip_bound_arg=skip_bound_arg,
@ -2037,11 +2056,11 @@ def _signature_internal(obj, *,
class _void:
'''A private marker - used in Parameter & Signature'''
"""A private marker - used in Parameter & Signature."""
class _empty:
pass
"""Marker object for Signature.empty and Parameter.empty."""
class _ParameterKind(enum.IntEnum):
@ -2063,7 +2082,7 @@ _VAR_KEYWORD = _ParameterKind.VAR_KEYWORD
class Parameter:
'''Represents a parameter in a function signature.
"""Represents a parameter in a function signature.
Has the following public attributes:
@ -2082,7 +2101,7 @@ class Parameter:
Possible values: `Parameter.POSITIONAL_ONLY`,
`Parameter.POSITIONAL_OR_KEYWORD`, `Parameter.VAR_POSITIONAL`,
`Parameter.KEYWORD_ONLY`, `Parameter.VAR_KEYWORD`.
'''
"""
__slots__ = ('_name', '_kind', '_default', '_annotation', '_partial_kwarg')
@ -2152,7 +2171,7 @@ class Parameter:
def replace(self, *, name=_void, kind=_void, annotation=_void,
default=_void, _partial_kwarg=_void):
'''Creates a customized copy of the Parameter.'''
"""Creates a customized copy of the Parameter."""
if name is _void:
name = self._name
@ -2218,7 +2237,7 @@ class Parameter:
class BoundArguments:
'''Result of `Signature.bind` call. Holds the mapping of arguments
"""Result of `Signature.bind` call. Holds the mapping of arguments
to the function's parameters.
Has the following public attributes:
@ -2232,7 +2251,7 @@ class BoundArguments:
Tuple of positional arguments values.
* kwargs : dict
Dict of keyword arguments values.
'''
"""
def __init__(self, signature, arguments):
self.arguments = arguments
@ -2311,7 +2330,7 @@ class BoundArguments:
class Signature:
'''A Signature object represents the overall signature of a function.
"""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.
@ -2331,7 +2350,7 @@ class Signature:
* bind_partial(*args, **kwargs) -> BoundArguments
Creates a partial mapping from positional and keyword arguments
to parameters (simulating 'functools.partial' behavior.)
'''
"""
__slots__ = ('_return_annotation', '_parameters')
@ -2342,9 +2361,9 @@ class Signature:
def __init__(self, parameters=None, *, return_annotation=_empty,
__validate_parameters__=True):
'''Constructs Signature from the given list of Parameter
"""Constructs Signature from the given list of Parameter
objects and 'return_annotation'. All arguments are optional.
'''
"""
if parameters is None:
params = OrderedDict()
@ -2397,7 +2416,7 @@ class Signature:
@classmethod
def from_function(cls, func):
'''Constructs Signature for the given python function'''
"""Constructs Signature for the given python function."""
is_duck_function = False
if not isfunction(func):
@ -2478,11 +2497,13 @@ class Signature:
@classmethod
def from_builtin(cls, func):
"""Constructs Signature for the given builtin function."""
return _signature_from_builtin(cls, func)
@classmethod
def from_callable(cls, obj):
return _signature_internal(obj, sigcls=cls)
"""Constructs Signature for the given callable object."""
return _signature_from_callable(obj, sigcls=cls)
@property
def parameters(self):
@ -2493,10 +2514,10 @@ class Signature:
return self._return_annotation
def replace(self, *, parameters=_void, return_annotation=_void):
'''Creates a customized copy of the Signature.
"""Creates a customized copy of the Signature.
Pass 'parameters' and/or 'return_annotation' arguments
to override them in the new copy.
'''
"""
if parameters is _void:
parameters = self.parameters.values()
@ -2541,7 +2562,7 @@ class Signature:
return not self.__eq__(other)
def _bind(self, args, kwargs, *, partial=False):
'''Private method. Don't use directly.'''
"""Private method. Don't use directly."""
arguments = OrderedDict()
@ -2677,17 +2698,17 @@ class Signature:
return self._bound_arguments_cls(self, arguments)
def bind(*args, **kwargs):
'''Get a BoundArguments object, that maps the passed `args`
"""Get a BoundArguments object, that maps the passed `args`
and `kwargs` to the function's signature. Raises `TypeError`
if the passed arguments can not be bound.
'''
"""
return args[0]._bind(args[1:], kwargs)
def bind_partial(*args, **kwargs):
'''Get a BoundArguments object, that partially maps the
"""Get a BoundArguments object, that partially maps the
passed `args` and `kwargs` to the function's signature.
Raises `TypeError` if the passed arguments can not be bound.
'''
"""
return args[0]._bind(args[1:], kwargs, partial=True)
def __reduce__(self):
@ -2749,7 +2770,7 @@ class Signature:
def signature(obj):
'''Get a signature object for the passed callable.'''
"""Get a signature object for the passed callable."""
return Signature.from_callable(obj)