[Python-checkins] cpython: inspect: Update docstrings; Rename _signature_internal to
yury.selivanov
python-checkins at python.org
Sat Mar 29 18:47:21 CET 2014
http://hg.python.org/cpython/rev/bc4186df43ad
changeset: 90028:bc4186df43ad
user: Yury Selivanov <yselivanov at sprymix.com>
date: Sat Mar 29 13:47:11 2014 -0400
summary:
inspect: Update docstrings; Rename _signature_internal to _signature_from_callable.
files:
Lib/inspect.py | 135 +++++++++++++++++++++---------------
1 files changed, 78 insertions(+), 57 deletions(-)
diff --git a/Lib/inspect.py b/Lib/inspect.py
--- a/Lib/inspect.py
+++ b/Lib/inspect.py
@@ -967,10 +967,10 @@
# getfullargspec() historically ignored __wrapped__ attributes,
# so we ensure that remains the case in 3.3+
- sig = _signature_internal(func,
- follow_wrapper_chains=False,
- skip_bound_arg=False,
- sigcls=Signature)
+ sig = _signature_from_callable(func,
+ follow_wrapper_chains=False,
+ skip_bound_arg=False,
+ sigcls=Signature)
except Exception as ex:
# Most of the times 'signature' will raise ValueError.
# But, it can also raise AttributeError, and, maybe something
@@ -1497,6 +1497,10 @@
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_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_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_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_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_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_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_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_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,10 +1877,14 @@
return _signature_fromstr(cls, func, s, skip_bound_arg)
-def _signature_internal(obj, *,
- follow_wrapper_chains=True,
- skip_bound_arg=True,
- sigcls):
+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))
@@ -1873,7 +1892,7 @@
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 @@
# (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 @@
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 @@
# 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 @@
# 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 @@
# 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 @@
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 @@
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 @@
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 @@
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 @@
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 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 @@
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 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 @@
* 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 @@
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 @@
@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 @@
@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 @@
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 @@
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 @@
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 @@
def signature(obj):
- '''Get a signature object for the passed callable.'''
+ """Get a signature object for the passed callable."""
return Signature.from_callable(obj)
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list