4c14b5de1c
attributes to None. The long-term goal is for people to be able to rely on these attributes existing and checking for None to see if they have been set. Since import itself sets these attributes when a loader does not the only instances when the attributes are None are from someone overloading __import__() and not using a loader or someone creating a module from scratch. This patch also unifies module initialization. Before you could have different attributes with default values depending on how the module object was created. Now the only way to not get the same default set of attributes is to circumvent initialization by calling ModuleType.__new__() directly.
2074 lines
77 KiB
Python
2074 lines
77 KiB
Python
"""Get useful information from live Python objects.
|
|
|
|
This module encapsulates the interface provided by the internal special
|
|
attributes (co_*, im_*, tb_*, etc.) in a friendlier fashion.
|
|
It also provides some help for examining source code and class layout.
|
|
|
|
Here are some of the useful functions provided by this module:
|
|
|
|
ismodule(), isclass(), ismethod(), isfunction(), isgeneratorfunction(),
|
|
isgenerator(), istraceback(), isframe(), iscode(), isbuiltin(),
|
|
isroutine() - check object types
|
|
getmembers() - get members of an object that satisfy a given condition
|
|
|
|
getfile(), getsourcefile(), getsource() - find an object's source code
|
|
getdoc(), getcomments() - get documentation on an object
|
|
getmodule() - determine the module that an object came from
|
|
getclasstree() - arrange classes so as to represent their hierarchy
|
|
|
|
getargspec(), getargvalues(), getcallargs() - get info about function arguments
|
|
getfullargspec() - same, with support for Python-3000 features
|
|
formatargspec(), formatargvalues() - format an argument spec
|
|
getouterframes(), getinnerframes() - get info about frames
|
|
currentframe() - get the current stack frame
|
|
stack(), trace() - get info about frames on the stack or in a traceback
|
|
|
|
signature() - get a Signature object for the callable
|
|
"""
|
|
|
|
# This module is in the public domain. No warranties.
|
|
|
|
__author__ = ('Ka-Ping Yee <ping@lfw.org>',
|
|
'Yury Selivanov <yselivanov@sprymix.com>')
|
|
|
|
import imp
|
|
import importlib.machinery
|
|
import itertools
|
|
import linecache
|
|
import os
|
|
import re
|
|
import sys
|
|
import tokenize
|
|
import types
|
|
import warnings
|
|
import functools
|
|
import builtins
|
|
from operator import attrgetter
|
|
from collections import namedtuple, OrderedDict
|
|
|
|
# Create constants for the compiler flags in Include/code.h
|
|
# We try to get them from dis to avoid duplication, but fall
|
|
# back to hardcording so the dependency is optional
|
|
try:
|
|
from dis import COMPILER_FLAG_NAMES as _flag_names
|
|
except ImportError:
|
|
CO_OPTIMIZED, CO_NEWLOCALS = 0x1, 0x2
|
|
CO_VARARGS, CO_VARKEYWORDS = 0x4, 0x8
|
|
CO_NESTED, CO_GENERATOR, CO_NOFREE = 0x10, 0x20, 0x40
|
|
else:
|
|
mod_dict = globals()
|
|
for k, v in _flag_names.items():
|
|
mod_dict["CO_" + v] = k
|
|
|
|
# See Include/object.h
|
|
TPFLAGS_IS_ABSTRACT = 1 << 20
|
|
|
|
# ----------------------------------------------------------- type-checking
|
|
def ismodule(object):
|
|
"""Return true if the object is a module.
|
|
|
|
Module objects provide these attributes:
|
|
__cached__ pathname to byte compiled file
|
|
__doc__ documentation string
|
|
__file__ filename (missing for built-in modules)"""
|
|
return isinstance(object, types.ModuleType)
|
|
|
|
def isclass(object):
|
|
"""Return true if the object is a class.
|
|
|
|
Class objects provide these attributes:
|
|
__doc__ documentation string
|
|
__module__ name of module in which this class was defined"""
|
|
return isinstance(object, type)
|
|
|
|
def ismethod(object):
|
|
"""Return true if the object is an instance method.
|
|
|
|
Instance method objects provide these attributes:
|
|
__doc__ documentation string
|
|
__name__ name with which this method was defined
|
|
__func__ function object containing implementation of method
|
|
__self__ instance to which this method is bound"""
|
|
return isinstance(object, types.MethodType)
|
|
|
|
def ismethoddescriptor(object):
|
|
"""Return true if the object is a method descriptor.
|
|
|
|
But not if ismethod() or isclass() or isfunction() are true.
|
|
|
|
This is new in Python 2.2, and, for example, is true of int.__add__.
|
|
An object passing this test has a __get__ attribute but not a __set__
|
|
attribute, but beyond that the set of attributes varies. __name__ is
|
|
usually sensible, and __doc__ often is.
|
|
|
|
Methods implemented via descriptors that also pass one of the other
|
|
tests return false from the ismethoddescriptor() test, simply because
|
|
the other tests promise more -- you can, e.g., count on having the
|
|
__func__ attribute (etc) when an object passes ismethod()."""
|
|
if isclass(object) or ismethod(object) or isfunction(object):
|
|
# mutual exclusion
|
|
return False
|
|
tp = type(object)
|
|
return hasattr(tp, "__get__") and not hasattr(tp, "__set__")
|
|
|
|
def isdatadescriptor(object):
|
|
"""Return true if the object is a data descriptor.
|
|
|
|
Data descriptors have both a __get__ and a __set__ attribute. Examples are
|
|
properties (defined in Python) and getsets and members (defined in C).
|
|
Typically, data descriptors will also have __name__ and __doc__ attributes
|
|
(properties, getsets, and members have both of these attributes), but this
|
|
is not guaranteed."""
|
|
if isclass(object) or ismethod(object) or isfunction(object):
|
|
# mutual exclusion
|
|
return False
|
|
tp = type(object)
|
|
return hasattr(tp, "__set__") and hasattr(tp, "__get__")
|
|
|
|
if hasattr(types, 'MemberDescriptorType'):
|
|
# CPython and equivalent
|
|
def ismemberdescriptor(object):
|
|
"""Return true if the object is a member descriptor.
|
|
|
|
Member descriptors are specialized descriptors defined in extension
|
|
modules."""
|
|
return isinstance(object, types.MemberDescriptorType)
|
|
else:
|
|
# Other implementations
|
|
def ismemberdescriptor(object):
|
|
"""Return true if the object is a member descriptor.
|
|
|
|
Member descriptors are specialized descriptors defined in extension
|
|
modules."""
|
|
return False
|
|
|
|
if hasattr(types, 'GetSetDescriptorType'):
|
|
# CPython and equivalent
|
|
def isgetsetdescriptor(object):
|
|
"""Return true if the object is a getset descriptor.
|
|
|
|
getset descriptors are specialized descriptors defined in extension
|
|
modules."""
|
|
return isinstance(object, types.GetSetDescriptorType)
|
|
else:
|
|
# Other implementations
|
|
def isgetsetdescriptor(object):
|
|
"""Return true if the object is a getset descriptor.
|
|
|
|
getset descriptors are specialized descriptors defined in extension
|
|
modules."""
|
|
return False
|
|
|
|
def isfunction(object):
|
|
"""Return true if the object is a user-defined function.
|
|
|
|
Function objects provide these attributes:
|
|
__doc__ documentation string
|
|
__name__ name with which this function was defined
|
|
__code__ code object containing compiled function bytecode
|
|
__defaults__ tuple of any default values for arguments
|
|
__globals__ global namespace in which this function was defined
|
|
__annotations__ dict of parameter annotations
|
|
__kwdefaults__ dict of keyword only parameters with defaults"""
|
|
return isinstance(object, types.FunctionType)
|
|
|
|
def isgeneratorfunction(object):
|
|
"""Return true if the object is a user-defined generator function.
|
|
|
|
Generator function objects provides same attributes as functions.
|
|
|
|
See help(isfunction) for attributes listing."""
|
|
return bool((isfunction(object) or ismethod(object)) and
|
|
object.__code__.co_flags & CO_GENERATOR)
|
|
|
|
def isgenerator(object):
|
|
"""Return true if the object is a generator.
|
|
|
|
Generator objects provide these attributes:
|
|
__iter__ defined to support interation over container
|
|
close raises a new GeneratorExit exception inside the
|
|
generator to terminate the iteration
|
|
gi_code code object
|
|
gi_frame frame object or possibly None once the generator has
|
|
been exhausted
|
|
gi_running set to 1 when generator is executing, 0 otherwise
|
|
next return the next item from the container
|
|
send resumes the generator and "sends" a value that becomes
|
|
the result of the current yield-expression
|
|
throw used to raise an exception inside the generator"""
|
|
return isinstance(object, types.GeneratorType)
|
|
|
|
def istraceback(object):
|
|
"""Return true if the object is a traceback.
|
|
|
|
Traceback objects provide these attributes:
|
|
tb_frame frame object at this level
|
|
tb_lasti index of last attempted instruction in bytecode
|
|
tb_lineno current line number in Python source code
|
|
tb_next next inner traceback object (called by this level)"""
|
|
return isinstance(object, types.TracebackType)
|
|
|
|
def isframe(object):
|
|
"""Return true if the object is a frame object.
|
|
|
|
Frame objects provide these attributes:
|
|
f_back next outer frame object (this frame's caller)
|
|
f_builtins built-in namespace seen by this frame
|
|
f_code code object being executed in this frame
|
|
f_globals global namespace seen by this frame
|
|
f_lasti index of last attempted instruction in bytecode
|
|
f_lineno current line number in Python source code
|
|
f_locals local namespace seen by this frame
|
|
f_trace tracing function for this frame, or None"""
|
|
return isinstance(object, types.FrameType)
|
|
|
|
def iscode(object):
|
|
"""Return true if the object is a code object.
|
|
|
|
Code objects provide these attributes:
|
|
co_argcount number of arguments (not including * or ** args)
|
|
co_code string of raw compiled bytecode
|
|
co_consts tuple of constants used in the bytecode
|
|
co_filename name of file in which this code object was created
|
|
co_firstlineno number of first line in Python source code
|
|
co_flags bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
|
|
co_lnotab encoded mapping of line numbers to bytecode indices
|
|
co_name name with which this code object was defined
|
|
co_names tuple of names of local variables
|
|
co_nlocals number of local variables
|
|
co_stacksize virtual machine stack space required
|
|
co_varnames tuple of names of arguments and local variables"""
|
|
return isinstance(object, types.CodeType)
|
|
|
|
def isbuiltin(object):
|
|
"""Return true if the object is a built-in function or method.
|
|
|
|
Built-in functions and methods provide these attributes:
|
|
__doc__ documentation string
|
|
__name__ original name of this function or method
|
|
__self__ instance to which a method is bound, or None"""
|
|
return isinstance(object, types.BuiltinFunctionType)
|
|
|
|
def isroutine(object):
|
|
"""Return true if the object is any kind of function or method."""
|
|
return (isbuiltin(object)
|
|
or isfunction(object)
|
|
or ismethod(object)
|
|
or ismethoddescriptor(object))
|
|
|
|
def isabstract(object):
|
|
"""Return true if the object is an abstract base class (ABC)."""
|
|
return bool(isinstance(object, type) and object.__flags__ & TPFLAGS_IS_ABSTRACT)
|
|
|
|
def getmembers(object, predicate=None):
|
|
"""Return all members of an object as (name, value) pairs sorted by name.
|
|
Optionally, only return members that satisfy a given predicate."""
|
|
if isclass(object):
|
|
mro = (object,) + getmro(object)
|
|
else:
|
|
mro = ()
|
|
results = []
|
|
for key in dir(object):
|
|
# First try to get the value via __dict__. Some descriptors don't
|
|
# like calling their __get__ (see bug #1785).
|
|
for base in mro:
|
|
if key in base.__dict__:
|
|
value = base.__dict__[key]
|
|
break
|
|
else:
|
|
try:
|
|
value = getattr(object, key)
|
|
except AttributeError:
|
|
continue
|
|
if not predicate or predicate(value):
|
|
results.append((key, value))
|
|
results.sort()
|
|
return results
|
|
|
|
Attribute = namedtuple('Attribute', 'name kind defining_class object')
|
|
|
|
def classify_class_attrs(cls):
|
|
"""Return list of attribute-descriptor tuples.
|
|
|
|
For each name in dir(cls), the return list contains a 4-tuple
|
|
with these elements:
|
|
|
|
0. The name (a string).
|
|
|
|
1. The kind of attribute this is, one of these strings:
|
|
'class method' created via classmethod()
|
|
'static method' created via staticmethod()
|
|
'property' created via property()
|
|
'method' any other flavor of method
|
|
'data' not a method
|
|
|
|
2. The class which defined this attribute (a class).
|
|
|
|
3. The object as obtained directly from the defining class's
|
|
__dict__, not via getattr. This is especially important for
|
|
data attributes: C.data is just a data object, but
|
|
C.__dict__['data'] may be a data descriptor with additional
|
|
info, like a __doc__ string.
|
|
"""
|
|
|
|
mro = getmro(cls)
|
|
names = dir(cls)
|
|
result = []
|
|
for name in names:
|
|
# Get the object associated with the name, and where it was defined.
|
|
# Getting an obj from the __dict__ sometimes reveals more than
|
|
# using getattr. Static and class methods are dramatic examples.
|
|
# Furthermore, some objects may raise an Exception when fetched with
|
|
# getattr(). This is the case with some descriptors (bug #1785).
|
|
# Thus, we only use getattr() as a last resort.
|
|
homecls = None
|
|
for base in (cls,) + mro:
|
|
if name in base.__dict__:
|
|
obj = base.__dict__[name]
|
|
homecls = base
|
|
break
|
|
else:
|
|
obj = getattr(cls, name)
|
|
homecls = getattr(obj, "__objclass__", homecls)
|
|
|
|
# Classify the object.
|
|
if isinstance(obj, staticmethod):
|
|
kind = "static method"
|
|
elif isinstance(obj, classmethod):
|
|
kind = "class method"
|
|
elif isinstance(obj, property):
|
|
kind = "property"
|
|
elif ismethoddescriptor(obj):
|
|
kind = "method"
|
|
elif isdatadescriptor(obj):
|
|
kind = "data"
|
|
else:
|
|
obj_via_getattr = getattr(cls, name)
|
|
if (isfunction(obj_via_getattr) or
|
|
ismethoddescriptor(obj_via_getattr)):
|
|
kind = "method"
|
|
else:
|
|
kind = "data"
|
|
obj = obj_via_getattr
|
|
|
|
result.append(Attribute(name, kind, homecls, obj))
|
|
|
|
return result
|
|
|
|
# ----------------------------------------------------------- class helpers
|
|
|
|
def getmro(cls):
|
|
"Return tuple of base classes (including cls) in method resolution order."
|
|
return cls.__mro__
|
|
|
|
# -------------------------------------------------- source code extraction
|
|
def indentsize(line):
|
|
"""Return the indent size, in spaces, at the start of a line of text."""
|
|
expline = line.expandtabs()
|
|
return len(expline) - len(expline.lstrip())
|
|
|
|
def getdoc(object):
|
|
"""Get the documentation string for an object.
|
|
|
|
All tabs are expanded to spaces. To clean up docstrings that are
|
|
indented to line up with blocks of code, any whitespace than can be
|
|
uniformly removed from the second line onwards is removed."""
|
|
try:
|
|
doc = object.__doc__
|
|
except AttributeError:
|
|
return None
|
|
if not isinstance(doc, str):
|
|
return None
|
|
return cleandoc(doc)
|
|
|
|
def cleandoc(doc):
|
|
"""Clean up indentation from docstrings.
|
|
|
|
Any whitespace that can be uniformly removed from the second line
|
|
onwards is removed."""
|
|
try:
|
|
lines = doc.expandtabs().split('\n')
|
|
except UnicodeError:
|
|
return None
|
|
else:
|
|
# Find minimum indentation of any non-blank lines after first line.
|
|
margin = sys.maxsize
|
|
for line in lines[1:]:
|
|
content = len(line.lstrip())
|
|
if content:
|
|
indent = len(line) - content
|
|
margin = min(margin, indent)
|
|
# Remove indentation.
|
|
if lines:
|
|
lines[0] = lines[0].lstrip()
|
|
if margin < sys.maxsize:
|
|
for i in range(1, len(lines)): lines[i] = lines[i][margin:]
|
|
# Remove any trailing or leading blank lines.
|
|
while lines and not lines[-1]:
|
|
lines.pop()
|
|
while lines and not lines[0]:
|
|
lines.pop(0)
|
|
return '\n'.join(lines)
|
|
|
|
def getfile(object):
|
|
"""Work out which source or compiled file an object was defined in."""
|
|
if ismodule(object):
|
|
if hasattr(object, '__file__'):
|
|
return object.__file__
|
|
raise TypeError('{!r} is a built-in module'.format(object))
|
|
if isclass(object):
|
|
object = sys.modules.get(object.__module__)
|
|
if hasattr(object, '__file__'):
|
|
return object.__file__
|
|
raise TypeError('{!r} is a built-in class'.format(object))
|
|
if ismethod(object):
|
|
object = object.__func__
|
|
if isfunction(object):
|
|
object = object.__code__
|
|
if istraceback(object):
|
|
object = object.tb_frame
|
|
if isframe(object):
|
|
object = object.f_code
|
|
if iscode(object):
|
|
return object.co_filename
|
|
raise TypeError('{!r} is not a module, class, method, '
|
|
'function, traceback, frame, or code object'.format(object))
|
|
|
|
ModuleInfo = namedtuple('ModuleInfo', 'name suffix mode module_type')
|
|
|
|
def getmoduleinfo(path):
|
|
"""Get the module name, suffix, mode, and module type for a given file."""
|
|
warnings.warn('inspect.getmoduleinfo() is deprecated', DeprecationWarning,
|
|
2)
|
|
filename = os.path.basename(path)
|
|
suffixes = [(-len(suffix), suffix, mode, mtype)
|
|
for suffix, mode, mtype in imp.get_suffixes()]
|
|
suffixes.sort() # try longest suffixes first, in case they overlap
|
|
for neglen, suffix, mode, mtype in suffixes:
|
|
if filename[neglen:] == suffix:
|
|
return ModuleInfo(filename[:neglen], suffix, mode, mtype)
|
|
|
|
def getmodulename(path):
|
|
"""Return the module name for a given file, or None."""
|
|
fname = os.path.basename(path)
|
|
# Check for paths that look like an actual module file
|
|
suffixes = [(-len(suffix), suffix)
|
|
for suffix in importlib.machinery.all_suffixes()]
|
|
suffixes.sort() # try longest suffixes first, in case they overlap
|
|
for neglen, suffix in suffixes:
|
|
if fname.endswith(suffix):
|
|
return fname[:neglen]
|
|
return None
|
|
|
|
def getsourcefile(object):
|
|
"""Return the filename that can be used to locate an object's source.
|
|
Return None if no way can be identified to get the source.
|
|
"""
|
|
filename = getfile(object)
|
|
all_bytecode_suffixes = importlib.machinery.DEBUG_BYTECODE_SUFFIXES[:]
|
|
all_bytecode_suffixes += importlib.machinery.OPTIMIZED_BYTECODE_SUFFIXES[:]
|
|
if any(filename.endswith(s) for s in all_bytecode_suffixes):
|
|
filename = (os.path.splitext(filename)[0] +
|
|
importlib.machinery.SOURCE_SUFFIXES[0])
|
|
elif any(filename.endswith(s) for s in
|
|
importlib.machinery.EXTENSION_SUFFIXES):
|
|
return None
|
|
if os.path.exists(filename):
|
|
return filename
|
|
# only return a non-existent filename if the module has a PEP 302 loader
|
|
if getattr(getmodule(object, filename), '__loader__', None) is not None:
|
|
return filename
|
|
# or it is in the linecache
|
|
if filename in linecache.cache:
|
|
return filename
|
|
|
|
def getabsfile(object, _filename=None):
|
|
"""Return an absolute path to the source or compiled file for an object.
|
|
|
|
The idea is for each object to have a unique origin, so this routine
|
|
normalizes the result as much as possible."""
|
|
if _filename is None:
|
|
_filename = getsourcefile(object) or getfile(object)
|
|
return os.path.normcase(os.path.abspath(_filename))
|
|
|
|
modulesbyfile = {}
|
|
_filesbymodname = {}
|
|
|
|
def getmodule(object, _filename=None):
|
|
"""Return the module an object was defined in, or None if not found."""
|
|
if ismodule(object):
|
|
return object
|
|
if hasattr(object, '__module__'):
|
|
return sys.modules.get(object.__module__)
|
|
# Try the filename to modulename cache
|
|
if _filename is not None and _filename in modulesbyfile:
|
|
return sys.modules.get(modulesbyfile[_filename])
|
|
# Try the cache again with the absolute file name
|
|
try:
|
|
file = getabsfile(object, _filename)
|
|
except TypeError:
|
|
return None
|
|
if file in modulesbyfile:
|
|
return sys.modules.get(modulesbyfile[file])
|
|
# Update the filename to module name cache and check yet again
|
|
# Copy sys.modules in order to cope with changes while iterating
|
|
for modname, module in list(sys.modules.items()):
|
|
if ismodule(module) and hasattr(module, '__file__'):
|
|
f = module.__file__
|
|
if f == _filesbymodname.get(modname, None):
|
|
# Have already mapped this module, so skip it
|
|
continue
|
|
_filesbymodname[modname] = f
|
|
f = getabsfile(module)
|
|
# Always map to the name the module knows itself by
|
|
modulesbyfile[f] = modulesbyfile[
|
|
os.path.realpath(f)] = module.__name__
|
|
if file in modulesbyfile:
|
|
return sys.modules.get(modulesbyfile[file])
|
|
# Check the main module
|
|
main = sys.modules['__main__']
|
|
if not hasattr(object, '__name__'):
|
|
return None
|
|
if hasattr(main, object.__name__):
|
|
mainobject = getattr(main, object.__name__)
|
|
if mainobject is object:
|
|
return main
|
|
# Check builtins
|
|
builtin = sys.modules['builtins']
|
|
if hasattr(builtin, object.__name__):
|
|
builtinobject = getattr(builtin, object.__name__)
|
|
if builtinobject is object:
|
|
return builtin
|
|
|
|
def findsource(object):
|
|
"""Return the entire source file and starting line number for an object.
|
|
|
|
The argument may be a module, class, method, function, traceback, frame,
|
|
or code object. The source code is returned as a list of all the lines
|
|
in the file and the line number indexes a line in that list. An OSError
|
|
is raised if the source code cannot be retrieved."""
|
|
|
|
file = getfile(object)
|
|
sourcefile = getsourcefile(object)
|
|
if not sourcefile and file[:1] + file[-1:] != '<>':
|
|
raise OSError('source code not available')
|
|
file = sourcefile if sourcefile else file
|
|
|
|
module = getmodule(object, file)
|
|
if module:
|
|
lines = linecache.getlines(file, module.__dict__)
|
|
else:
|
|
lines = linecache.getlines(file)
|
|
if not lines:
|
|
raise OSError('could not get source code')
|
|
|
|
if ismodule(object):
|
|
return lines, 0
|
|
|
|
if isclass(object):
|
|
name = object.__name__
|
|
pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
|
|
# make some effort to find the best matching class definition:
|
|
# use the one with the least indentation, which is the one
|
|
# that's most probably not inside a function definition.
|
|
candidates = []
|
|
for i in range(len(lines)):
|
|
match = pat.match(lines[i])
|
|
if match:
|
|
# if it's at toplevel, it's already the best one
|
|
if lines[i][0] == 'c':
|
|
return lines, i
|
|
# else add whitespace to candidate list
|
|
candidates.append((match.group(1), i))
|
|
if candidates:
|
|
# this will sort by whitespace, and by line number,
|
|
# less whitespace first
|
|
candidates.sort()
|
|
return lines, candidates[0][1]
|
|
else:
|
|
raise OSError('could not find class definition')
|
|
|
|
if ismethod(object):
|
|
object = object.__func__
|
|
if isfunction(object):
|
|
object = object.__code__
|
|
if istraceback(object):
|
|
object = object.tb_frame
|
|
if isframe(object):
|
|
object = object.f_code
|
|
if iscode(object):
|
|
if not hasattr(object, 'co_firstlineno'):
|
|
raise OSError('could not find function definition')
|
|
lnum = object.co_firstlineno - 1
|
|
pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
|
|
while lnum > 0:
|
|
if pat.match(lines[lnum]): break
|
|
lnum = lnum - 1
|
|
return lines, lnum
|
|
raise OSError('could not find code object')
|
|
|
|
def getcomments(object):
|
|
"""Get lines of comments immediately preceding an object's source code.
|
|
|
|
Returns None when source can't be found.
|
|
"""
|
|
try:
|
|
lines, lnum = findsource(object)
|
|
except (OSError, TypeError):
|
|
return None
|
|
|
|
if ismodule(object):
|
|
# Look for a comment block at the top of the file.
|
|
start = 0
|
|
if lines and lines[0][:2] == '#!': start = 1
|
|
while start < len(lines) and lines[start].strip() in ('', '#'):
|
|
start = start + 1
|
|
if start < len(lines) and lines[start][:1] == '#':
|
|
comments = []
|
|
end = start
|
|
while end < len(lines) and lines[end][:1] == '#':
|
|
comments.append(lines[end].expandtabs())
|
|
end = end + 1
|
|
return ''.join(comments)
|
|
|
|
# Look for a preceding block of comments at the same indentation.
|
|
elif lnum > 0:
|
|
indent = indentsize(lines[lnum])
|
|
end = lnum - 1
|
|
if end >= 0 and lines[end].lstrip()[:1] == '#' and \
|
|
indentsize(lines[end]) == indent:
|
|
comments = [lines[end].expandtabs().lstrip()]
|
|
if end > 0:
|
|
end = end - 1
|
|
comment = lines[end].expandtabs().lstrip()
|
|
while comment[:1] == '#' and indentsize(lines[end]) == indent:
|
|
comments[:0] = [comment]
|
|
end = end - 1
|
|
if end < 0: break
|
|
comment = lines[end].expandtabs().lstrip()
|
|
while comments and comments[0].strip() == '#':
|
|
comments[:1] = []
|
|
while comments and comments[-1].strip() == '#':
|
|
comments[-1:] = []
|
|
return ''.join(comments)
|
|
|
|
class EndOfBlock(Exception): pass
|
|
|
|
class BlockFinder:
|
|
"""Provide a tokeneater() method to detect the end of a code block."""
|
|
def __init__(self):
|
|
self.indent = 0
|
|
self.islambda = False
|
|
self.started = False
|
|
self.passline = False
|
|
self.last = 1
|
|
|
|
def tokeneater(self, type, token, srowcol, erowcol, line):
|
|
if not self.started:
|
|
# look for the first "def", "class" or "lambda"
|
|
if token in ("def", "class", "lambda"):
|
|
if token == "lambda":
|
|
self.islambda = True
|
|
self.started = True
|
|
self.passline = True # skip to the end of the line
|
|
elif type == tokenize.NEWLINE:
|
|
self.passline = False # stop skipping when a NEWLINE is seen
|
|
self.last = srowcol[0]
|
|
if self.islambda: # lambdas always end at the first NEWLINE
|
|
raise EndOfBlock
|
|
elif self.passline:
|
|
pass
|
|
elif type == tokenize.INDENT:
|
|
self.indent = self.indent + 1
|
|
self.passline = True
|
|
elif type == tokenize.DEDENT:
|
|
self.indent = self.indent - 1
|
|
# the end of matching indent/dedent pairs end a block
|
|
# (note that this only works for "def"/"class" blocks,
|
|
# not e.g. for "if: else:" or "try: finally:" blocks)
|
|
if self.indent <= 0:
|
|
raise EndOfBlock
|
|
elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL):
|
|
# any other token on the same indentation level end the previous
|
|
# block as well, except the pseudo-tokens COMMENT and NL.
|
|
raise EndOfBlock
|
|
|
|
def getblock(lines):
|
|
"""Extract the block of code at the top of the given list of lines."""
|
|
blockfinder = BlockFinder()
|
|
try:
|
|
tokens = tokenize.generate_tokens(iter(lines).__next__)
|
|
for _token in tokens:
|
|
blockfinder.tokeneater(*_token)
|
|
except (EndOfBlock, IndentationError):
|
|
pass
|
|
return lines[:blockfinder.last]
|
|
|
|
def getsourcelines(object):
|
|
"""Return a list of source lines and starting line number for an object.
|
|
|
|
The argument may be a module, class, method, function, traceback, frame,
|
|
or code object. The source code is returned as a list of the lines
|
|
corresponding to the object and the line number indicates where in the
|
|
original source file the first line of code was found. An OSError is
|
|
raised if the source code cannot be retrieved."""
|
|
lines, lnum = findsource(object)
|
|
|
|
if ismodule(object): return lines, 0
|
|
else: return getblock(lines[lnum:]), lnum + 1
|
|
|
|
def getsource(object):
|
|
"""Return the text of the source code for an object.
|
|
|
|
The argument may be a module, class, method, function, traceback, frame,
|
|
or code object. The source code is returned as a single string. An
|
|
OSError is raised if the source code cannot be retrieved."""
|
|
lines, lnum = getsourcelines(object)
|
|
return ''.join(lines)
|
|
|
|
# --------------------------------------------------- class tree extraction
|
|
def walktree(classes, children, parent):
|
|
"""Recursive helper function for getclasstree()."""
|
|
results = []
|
|
classes.sort(key=attrgetter('__module__', '__name__'))
|
|
for c in classes:
|
|
results.append((c, c.__bases__))
|
|
if c in children:
|
|
results.append(walktree(children[c], children, c))
|
|
return results
|
|
|
|
def getclasstree(classes, unique=False):
|
|
"""Arrange the given list of classes into a hierarchy of nested lists.
|
|
|
|
Where a nested list appears, it contains classes derived from the class
|
|
whose entry immediately precedes the list. Each entry is a 2-tuple
|
|
containing a class and a tuple of its base classes. If the 'unique'
|
|
argument is true, exactly one entry appears in the returned structure
|
|
for each class in the given list. Otherwise, classes using multiple
|
|
inheritance and their descendants will appear multiple times."""
|
|
children = {}
|
|
roots = []
|
|
for c in classes:
|
|
if c.__bases__:
|
|
for parent in c.__bases__:
|
|
if not parent in children:
|
|
children[parent] = []
|
|
children[parent].append(c)
|
|
if unique and parent in classes: break
|
|
elif c not in roots:
|
|
roots.append(c)
|
|
for parent in children:
|
|
if parent not in classes:
|
|
roots.append(parent)
|
|
return walktree(roots, children, None)
|
|
|
|
# ------------------------------------------------ argument list extraction
|
|
Arguments = namedtuple('Arguments', 'args, varargs, varkw')
|
|
|
|
def getargs(co):
|
|
"""Get information about the arguments accepted by a code object.
|
|
|
|
Three things are returned: (args, varargs, varkw), where
|
|
'args' is the list of argument names. Keyword-only arguments are
|
|
appended. 'varargs' and 'varkw' are the names of the * and **
|
|
arguments or None."""
|
|
args, varargs, kwonlyargs, varkw = _getfullargs(co)
|
|
return Arguments(args + kwonlyargs, varargs, varkw)
|
|
|
|
def _getfullargs(co):
|
|
"""Get information about the arguments accepted by a code object.
|
|
|
|
Four things are returned: (args, varargs, kwonlyargs, varkw), where
|
|
'args' and 'kwonlyargs' are lists of argument names, and 'varargs'
|
|
and 'varkw' are the names of the * and ** arguments or None."""
|
|
|
|
if not iscode(co):
|
|
raise TypeError('{!r} is not a code object'.format(co))
|
|
|
|
nargs = co.co_argcount
|
|
names = co.co_varnames
|
|
nkwargs = co.co_kwonlyargcount
|
|
args = list(names[:nargs])
|
|
kwonlyargs = list(names[nargs:nargs+nkwargs])
|
|
step = 0
|
|
|
|
nargs += nkwargs
|
|
varargs = None
|
|
if co.co_flags & CO_VARARGS:
|
|
varargs = co.co_varnames[nargs]
|
|
nargs = nargs + 1
|
|
varkw = None
|
|
if co.co_flags & CO_VARKEYWORDS:
|
|
varkw = co.co_varnames[nargs]
|
|
return args, varargs, kwonlyargs, varkw
|
|
|
|
|
|
ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults')
|
|
|
|
def getargspec(func):
|
|
"""Get the names and default values of a function's arguments.
|
|
|
|
A tuple of four things is returned: (args, varargs, varkw, defaults).
|
|
'args' is a list of the argument names.
|
|
'args' will include keyword-only argument names.
|
|
'varargs' and 'varkw' are the names of the * and ** arguments or None.
|
|
'defaults' is an n-tuple of the default values of the last n arguments.
|
|
|
|
Use the getfullargspec() API for Python-3000 code, as annotations
|
|
and keyword arguments are supported. getargspec() will raise ValueError
|
|
if the func has either annotations or keyword arguments.
|
|
"""
|
|
|
|
args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = \
|
|
getfullargspec(func)
|
|
if kwonlyargs or ann:
|
|
raise ValueError("Function has keyword-only arguments or annotations"
|
|
", use getfullargspec() API which can support them")
|
|
return ArgSpec(args, varargs, varkw, defaults)
|
|
|
|
FullArgSpec = namedtuple('FullArgSpec',
|
|
'args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, annotations')
|
|
|
|
def getfullargspec(func):
|
|
"""Get the names and default values of a function's arguments.
|
|
|
|
A tuple of seven things is returned:
|
|
(args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults annotations).
|
|
'args' is a list of the argument names.
|
|
'varargs' and 'varkw' are the names of the * and ** arguments or None.
|
|
'defaults' is an n-tuple of the default values of the last n arguments.
|
|
'kwonlyargs' is a list of keyword-only argument names.
|
|
'kwonlydefaults' is a dictionary mapping names from kwonlyargs to defaults.
|
|
'annotations' is a dictionary mapping argument names to annotations.
|
|
|
|
The first four items in the tuple correspond to getargspec().
|
|
"""
|
|
|
|
if ismethod(func):
|
|
func = func.__func__
|
|
if not isfunction(func):
|
|
raise TypeError('{!r} is not a Python function'.format(func))
|
|
args, varargs, kwonlyargs, varkw = _getfullargs(func.__code__)
|
|
return FullArgSpec(args, varargs, varkw, func.__defaults__,
|
|
kwonlyargs, func.__kwdefaults__, func.__annotations__)
|
|
|
|
ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals')
|
|
|
|
def getargvalues(frame):
|
|
"""Get information about arguments passed into a particular frame.
|
|
|
|
A tuple of four things is returned: (args, varargs, varkw, locals).
|
|
'args' is a list of the argument names.
|
|
'varargs' and 'varkw' are the names of the * and ** arguments or None.
|
|
'locals' is the locals dictionary of the given frame."""
|
|
args, varargs, varkw = getargs(frame.f_code)
|
|
return ArgInfo(args, varargs, varkw, frame.f_locals)
|
|
|
|
def formatannotation(annotation, base_module=None):
|
|
if isinstance(annotation, type):
|
|
if annotation.__module__ in ('builtins', base_module):
|
|
return annotation.__name__
|
|
return annotation.__module__+'.'+annotation.__name__
|
|
return repr(annotation)
|
|
|
|
def formatannotationrelativeto(object):
|
|
module = getattr(object, '__module__', None)
|
|
def _formatannotation(annotation):
|
|
return formatannotation(annotation, module)
|
|
return _formatannotation
|
|
|
|
def formatargspec(args, varargs=None, varkw=None, defaults=None,
|
|
kwonlyargs=(), kwonlydefaults={}, annotations={},
|
|
formatarg=str,
|
|
formatvarargs=lambda name: '*' + name,
|
|
formatvarkw=lambda name: '**' + name,
|
|
formatvalue=lambda value: '=' + repr(value),
|
|
formatreturns=lambda text: ' -> ' + text,
|
|
formatannotation=formatannotation):
|
|
"""Format an argument spec from the values returned by getargspec
|
|
or getfullargspec.
|
|
|
|
The first seven arguments are (args, varargs, varkw, defaults,
|
|
kwonlyargs, kwonlydefaults, annotations). The other five arguments
|
|
are the corresponding optional formatting functions that are called to
|
|
turn names and values into strings. The last argument is an optional
|
|
function to format the sequence of arguments."""
|
|
def formatargandannotation(arg):
|
|
result = formatarg(arg)
|
|
if arg in annotations:
|
|
result += ': ' + formatannotation(annotations[arg])
|
|
return result
|
|
specs = []
|
|
if defaults:
|
|
firstdefault = len(args) - len(defaults)
|
|
for i, arg in enumerate(args):
|
|
spec = formatargandannotation(arg)
|
|
if defaults and i >= firstdefault:
|
|
spec = spec + formatvalue(defaults[i - firstdefault])
|
|
specs.append(spec)
|
|
if varargs is not None:
|
|
specs.append(formatvarargs(formatargandannotation(varargs)))
|
|
else:
|
|
if kwonlyargs:
|
|
specs.append('*')
|
|
if kwonlyargs:
|
|
for kwonlyarg in kwonlyargs:
|
|
spec = formatargandannotation(kwonlyarg)
|
|
if kwonlydefaults and kwonlyarg in kwonlydefaults:
|
|
spec += formatvalue(kwonlydefaults[kwonlyarg])
|
|
specs.append(spec)
|
|
if varkw is not None:
|
|
specs.append(formatvarkw(formatargandannotation(varkw)))
|
|
result = '(' + ', '.join(specs) + ')'
|
|
if 'return' in annotations:
|
|
result += formatreturns(formatannotation(annotations['return']))
|
|
return result
|
|
|
|
def formatargvalues(args, varargs, varkw, locals,
|
|
formatarg=str,
|
|
formatvarargs=lambda name: '*' + name,
|
|
formatvarkw=lambda name: '**' + name,
|
|
formatvalue=lambda value: '=' + repr(value)):
|
|
"""Format an argument spec from the 4 values returned by getargvalues.
|
|
|
|
The first four arguments are (args, varargs, varkw, locals). The
|
|
next four arguments are the corresponding optional formatting functions
|
|
that are called to turn names and values into strings. The ninth
|
|
argument is an optional function to format the sequence of arguments."""
|
|
def convert(name, locals=locals,
|
|
formatarg=formatarg, formatvalue=formatvalue):
|
|
return formatarg(name) + formatvalue(locals[name])
|
|
specs = []
|
|
for i in range(len(args)):
|
|
specs.append(convert(args[i]))
|
|
if varargs:
|
|
specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
|
|
if varkw:
|
|
specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
|
|
return '(' + ', '.join(specs) + ')'
|
|
|
|
def _missing_arguments(f_name, argnames, pos, values):
|
|
names = [repr(name) for name in argnames if name not in values]
|
|
missing = len(names)
|
|
if missing == 1:
|
|
s = names[0]
|
|
elif missing == 2:
|
|
s = "{} and {}".format(*names)
|
|
else:
|
|
tail = ", {} and {}".format(names[-2:])
|
|
del names[-2:]
|
|
s = ", ".join(names) + tail
|
|
raise TypeError("%s() missing %i required %s argument%s: %s" %
|
|
(f_name, missing,
|
|
"positional" if pos else "keyword-only",
|
|
"" if missing == 1 else "s", s))
|
|
|
|
def _too_many(f_name, args, kwonly, varargs, defcount, given, values):
|
|
atleast = len(args) - defcount
|
|
kwonly_given = len([arg for arg in kwonly if arg in values])
|
|
if varargs:
|
|
plural = atleast != 1
|
|
sig = "at least %d" % (atleast,)
|
|
elif defcount:
|
|
plural = True
|
|
sig = "from %d to %d" % (atleast, len(args))
|
|
else:
|
|
plural = len(args) != 1
|
|
sig = str(len(args))
|
|
kwonly_sig = ""
|
|
if kwonly_given:
|
|
msg = " positional argument%s (and %d keyword-only argument%s)"
|
|
kwonly_sig = (msg % ("s" if given != 1 else "", kwonly_given,
|
|
"s" if kwonly_given != 1 else ""))
|
|
raise TypeError("%s() takes %s positional argument%s but %d%s %s given" %
|
|
(f_name, sig, "s" if plural else "", given, kwonly_sig,
|
|
"was" if given == 1 and not kwonly_given else "were"))
|
|
|
|
def getcallargs(func, *positional, **named):
|
|
"""Get the mapping of arguments to values.
|
|
|
|
A dict is returned, with keys the function argument names (including the
|
|
names of the * and ** arguments, if any), and values the respective bound
|
|
values from 'positional' and 'named'."""
|
|
spec = getfullargspec(func)
|
|
args, varargs, varkw, defaults, kwonlyargs, kwonlydefaults, ann = spec
|
|
f_name = func.__name__
|
|
arg2value = {}
|
|
|
|
|
|
if ismethod(func) and func.__self__ is not None:
|
|
# implicit 'self' (or 'cls' for classmethods) argument
|
|
positional = (func.__self__,) + positional
|
|
num_pos = len(positional)
|
|
num_args = len(args)
|
|
num_defaults = len(defaults) if defaults else 0
|
|
|
|
n = min(num_pos, num_args)
|
|
for i in range(n):
|
|
arg2value[args[i]] = positional[i]
|
|
if varargs:
|
|
arg2value[varargs] = tuple(positional[n:])
|
|
possible_kwargs = set(args + kwonlyargs)
|
|
if varkw:
|
|
arg2value[varkw] = {}
|
|
for kw, value in named.items():
|
|
if kw not in possible_kwargs:
|
|
if not varkw:
|
|
raise TypeError("%s() got an unexpected keyword argument %r" %
|
|
(f_name, kw))
|
|
arg2value[varkw][kw] = value
|
|
continue
|
|
if kw in arg2value:
|
|
raise TypeError("%s() got multiple values for argument %r" %
|
|
(f_name, kw))
|
|
arg2value[kw] = value
|
|
if num_pos > num_args and not varargs:
|
|
_too_many(f_name, args, kwonlyargs, varargs, num_defaults,
|
|
num_pos, arg2value)
|
|
if num_pos < num_args:
|
|
req = args[:num_args - num_defaults]
|
|
for arg in req:
|
|
if arg not in arg2value:
|
|
_missing_arguments(f_name, req, True, arg2value)
|
|
for i, arg in enumerate(args[num_args - num_defaults:]):
|
|
if arg not in arg2value:
|
|
arg2value[arg] = defaults[i]
|
|
missing = 0
|
|
for kwarg in kwonlyargs:
|
|
if kwarg not in arg2value:
|
|
if kwarg in kwonlydefaults:
|
|
arg2value[kwarg] = kwonlydefaults[kwarg]
|
|
else:
|
|
missing += 1
|
|
if missing:
|
|
_missing_arguments(f_name, kwonlyargs, False, arg2value)
|
|
return arg2value
|
|
|
|
ClosureVars = namedtuple('ClosureVars', 'nonlocals globals builtins unbound')
|
|
|
|
def getclosurevars(func):
|
|
"""
|
|
Get the mapping of free variables to their current values.
|
|
|
|
Returns a named tuple of dicts mapping the current nonlocal, global
|
|
and builtin references as seen by the body of the function. A final
|
|
set of unbound names that could not be resolved is also provided.
|
|
"""
|
|
|
|
if ismethod(func):
|
|
func = func.__func__
|
|
|
|
if not isfunction(func):
|
|
raise TypeError("'{!r}' is not a Python function".format(func))
|
|
|
|
code = func.__code__
|
|
# Nonlocal references are named in co_freevars and resolved
|
|
# by looking them up in __closure__ by positional index
|
|
if func.__closure__ is None:
|
|
nonlocal_vars = {}
|
|
else:
|
|
nonlocal_vars = {
|
|
var : cell.cell_contents
|
|
for var, cell in zip(code.co_freevars, func.__closure__)
|
|
}
|
|
|
|
# Global and builtin references are named in co_names and resolved
|
|
# by looking them up in __globals__ or __builtins__
|
|
global_ns = func.__globals__
|
|
builtin_ns = global_ns.get("__builtins__", builtins.__dict__)
|
|
if ismodule(builtin_ns):
|
|
builtin_ns = builtin_ns.__dict__
|
|
global_vars = {}
|
|
builtin_vars = {}
|
|
unbound_names = set()
|
|
for name in code.co_names:
|
|
if name in ("None", "True", "False"):
|
|
# Because these used to be builtins instead of keywords, they
|
|
# may still show up as name references. We ignore them.
|
|
continue
|
|
try:
|
|
global_vars[name] = global_ns[name]
|
|
except KeyError:
|
|
try:
|
|
builtin_vars[name] = builtin_ns[name]
|
|
except KeyError:
|
|
unbound_names.add(name)
|
|
|
|
return ClosureVars(nonlocal_vars, global_vars,
|
|
builtin_vars, unbound_names)
|
|
|
|
# -------------------------------------------------- stack frame extraction
|
|
|
|
Traceback = namedtuple('Traceback', 'filename lineno function code_context index')
|
|
|
|
def getframeinfo(frame, context=1):
|
|
"""Get information about a frame or traceback object.
|
|
|
|
A tuple of five things is returned: the filename, the line number of
|
|
the current line, the function name, a list of lines of context from
|
|
the source code, and the index of the current line within that list.
|
|
The optional second argument specifies the number of lines of context
|
|
to return, which are centered around the current line."""
|
|
if istraceback(frame):
|
|
lineno = frame.tb_lineno
|
|
frame = frame.tb_frame
|
|
else:
|
|
lineno = frame.f_lineno
|
|
if not isframe(frame):
|
|
raise TypeError('{!r} is not a frame or traceback object'.format(frame))
|
|
|
|
filename = getsourcefile(frame) or getfile(frame)
|
|
if context > 0:
|
|
start = lineno - 1 - context//2
|
|
try:
|
|
lines, lnum = findsource(frame)
|
|
except OSError:
|
|
lines = index = None
|
|
else:
|
|
start = max(start, 1)
|
|
start = max(0, min(start, len(lines) - context))
|
|
lines = lines[start:start+context]
|
|
index = lineno - 1 - start
|
|
else:
|
|
lines = index = None
|
|
|
|
return Traceback(filename, lineno, frame.f_code.co_name, lines, index)
|
|
|
|
def getlineno(frame):
|
|
"""Get the line number from a frame object, allowing for optimization."""
|
|
# FrameType.f_lineno is now a descriptor that grovels co_lnotab
|
|
return frame.f_lineno
|
|
|
|
def getouterframes(frame, context=1):
|
|
"""Get a list of records for a frame and all higher (calling) frames.
|
|
|
|
Each record contains a frame object, filename, line number, function
|
|
name, a list of lines of context, and index within the context."""
|
|
framelist = []
|
|
while frame:
|
|
framelist.append((frame,) + getframeinfo(frame, context))
|
|
frame = frame.f_back
|
|
return framelist
|
|
|
|
def getinnerframes(tb, context=1):
|
|
"""Get a list of records for a traceback's frame and all lower frames.
|
|
|
|
Each record contains a frame object, filename, line number, function
|
|
name, a list of lines of context, and index within the context."""
|
|
framelist = []
|
|
while tb:
|
|
framelist.append((tb.tb_frame,) + getframeinfo(tb, context))
|
|
tb = tb.tb_next
|
|
return framelist
|
|
|
|
def currentframe():
|
|
"""Return the frame of the caller or None if this is not possible."""
|
|
return sys._getframe(1) if hasattr(sys, "_getframe") else None
|
|
|
|
def stack(context=1):
|
|
"""Return a list of records for the stack above the caller's frame."""
|
|
return getouterframes(sys._getframe(1), context)
|
|
|
|
def trace(context=1):
|
|
"""Return a list of records for the stack below the current exception."""
|
|
return getinnerframes(sys.exc_info()[2], context)
|
|
|
|
|
|
# ------------------------------------------------ static version of getattr
|
|
|
|
_sentinel = object()
|
|
|
|
def _static_getmro(klass):
|
|
return type.__dict__['__mro__'].__get__(klass)
|
|
|
|
def _check_instance(obj, attr):
|
|
instance_dict = {}
|
|
try:
|
|
instance_dict = object.__getattribute__(obj, "__dict__")
|
|
except AttributeError:
|
|
pass
|
|
return dict.get(instance_dict, attr, _sentinel)
|
|
|
|
|
|
def _check_class(klass, attr):
|
|
for entry in _static_getmro(klass):
|
|
if _shadowed_dict(type(entry)) is _sentinel:
|
|
try:
|
|
return entry.__dict__[attr]
|
|
except KeyError:
|
|
pass
|
|
return _sentinel
|
|
|
|
def _is_type(obj):
|
|
try:
|
|
_static_getmro(obj)
|
|
except TypeError:
|
|
return False
|
|
return True
|
|
|
|
def _shadowed_dict(klass):
|
|
dict_attr = type.__dict__["__dict__"]
|
|
for entry in _static_getmro(klass):
|
|
try:
|
|
class_dict = dict_attr.__get__(entry)["__dict__"]
|
|
except KeyError:
|
|
pass
|
|
else:
|
|
if not (type(class_dict) is types.GetSetDescriptorType and
|
|
class_dict.__name__ == "__dict__" and
|
|
class_dict.__objclass__ is entry):
|
|
return class_dict
|
|
return _sentinel
|
|
|
|
def getattr_static(obj, attr, default=_sentinel):
|
|
"""Retrieve attributes without triggering dynamic lookup via the
|
|
descriptor protocol, __getattr__ or __getattribute__.
|
|
|
|
Note: this function may not be able to retrieve all attributes
|
|
that getattr can fetch (like dynamically created attributes)
|
|
and may find attributes that getattr can't (like descriptors
|
|
that raise AttributeError). It can also return descriptor objects
|
|
instead of instance members in some cases. See the
|
|
documentation for details.
|
|
"""
|
|
instance_result = _sentinel
|
|
if not _is_type(obj):
|
|
klass = type(obj)
|
|
dict_attr = _shadowed_dict(klass)
|
|
if (dict_attr is _sentinel or
|
|
type(dict_attr) is types.MemberDescriptorType):
|
|
instance_result = _check_instance(obj, attr)
|
|
else:
|
|
klass = obj
|
|
|
|
klass_result = _check_class(klass, attr)
|
|
|
|
if instance_result is not _sentinel and klass_result is not _sentinel:
|
|
if (_check_class(type(klass_result), '__get__') is not _sentinel and
|
|
_check_class(type(klass_result), '__set__') is not _sentinel):
|
|
return klass_result
|
|
|
|
if instance_result is not _sentinel:
|
|
return instance_result
|
|
if klass_result is not _sentinel:
|
|
return klass_result
|
|
|
|
if obj is klass:
|
|
# for types we check the metaclass too
|
|
for entry in _static_getmro(type(klass)):
|
|
if _shadowed_dict(type(entry)) is _sentinel:
|
|
try:
|
|
return entry.__dict__[attr]
|
|
except KeyError:
|
|
pass
|
|
if default is not _sentinel:
|
|
return default
|
|
raise AttributeError(attr)
|
|
|
|
|
|
# ------------------------------------------------ generator introspection
|
|
|
|
GEN_CREATED = 'GEN_CREATED'
|
|
GEN_RUNNING = 'GEN_RUNNING'
|
|
GEN_SUSPENDED = 'GEN_SUSPENDED'
|
|
GEN_CLOSED = 'GEN_CLOSED'
|
|
|
|
def getgeneratorstate(generator):
|
|
"""Get current state of a generator-iterator.
|
|
|
|
Possible states are:
|
|
GEN_CREATED: Waiting to start execution.
|
|
GEN_RUNNING: Currently being executed by the interpreter.
|
|
GEN_SUSPENDED: Currently suspended at a yield expression.
|
|
GEN_CLOSED: Execution has completed.
|
|
"""
|
|
if generator.gi_running:
|
|
return GEN_RUNNING
|
|
if generator.gi_frame is None:
|
|
return GEN_CLOSED
|
|
if generator.gi_frame.f_lasti == -1:
|
|
return GEN_CREATED
|
|
return GEN_SUSPENDED
|
|
|
|
|
|
def getgeneratorlocals(generator):
|
|
"""
|
|
Get the mapping of generator local variables to their current values.
|
|
|
|
A dict is returned, with the keys the local variable names and values the
|
|
bound values."""
|
|
|
|
if not isgenerator(generator):
|
|
raise TypeError("'{!r}' is not a Python generator".format(generator))
|
|
|
|
frame = getattr(generator, "gi_frame", None)
|
|
if frame is not None:
|
|
return generator.gi_frame.f_locals
|
|
else:
|
|
return {}
|
|
|
|
###############################################################################
|
|
### Function Signature Object (PEP 362)
|
|
###############################################################################
|
|
|
|
|
|
_WrapperDescriptor = type(type.__call__)
|
|
_MethodWrapper = type(all.__call__)
|
|
|
|
_NonUserDefinedCallables = (_WrapperDescriptor,
|
|
_MethodWrapper,
|
|
types.BuiltinFunctionType)
|
|
|
|
|
|
def _get_user_defined_method(cls, method_name):
|
|
try:
|
|
meth = getattr(cls, method_name)
|
|
except AttributeError:
|
|
return
|
|
else:
|
|
if not isinstance(meth, _NonUserDefinedCallables):
|
|
# Once '__signature__' will be added to 'C'-level
|
|
# callables, this check won't be necessary
|
|
return meth
|
|
|
|
|
|
def signature(obj):
|
|
'''Get a signature object for the passed callable.'''
|
|
|
|
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(obj.__func__)
|
|
return sig.replace(parameters=tuple(sig.parameters.values())[1:])
|
|
|
|
try:
|
|
sig = obj.__signature__
|
|
except AttributeError:
|
|
pass
|
|
else:
|
|
if sig is not None:
|
|
return sig
|
|
|
|
try:
|
|
# Was this function wrapped by a decorator?
|
|
wrapped = obj.__wrapped__
|
|
except AttributeError:
|
|
pass
|
|
else:
|
|
return signature(wrapped)
|
|
|
|
if isinstance(obj, types.FunctionType):
|
|
return Signature.from_function(obj)
|
|
|
|
if isinstance(obj, functools.partial):
|
|
sig = signature(obj.func)
|
|
|
|
new_params = OrderedDict(sig.parameters.items())
|
|
|
|
partial_args = obj.args or ()
|
|
partial_keywords = obj.keywords or {}
|
|
try:
|
|
ba = sig.bind_partial(*partial_args, **partial_keywords)
|
|
except TypeError as ex:
|
|
msg = 'partial object {!r} has incorrect arguments'.format(obj)
|
|
raise ValueError(msg) from ex
|
|
|
|
for arg_name, arg_value in ba.arguments.items():
|
|
param = new_params[arg_name]
|
|
if arg_name in partial_keywords:
|
|
# We set a new default value, because the following code
|
|
# is correct:
|
|
#
|
|
# >>> def foo(a): print(a)
|
|
# >>> print(partial(partial(foo, a=10), a=20)())
|
|
# 20
|
|
# >>> print(partial(partial(foo, a=10), a=20)(a=30))
|
|
# 30
|
|
#
|
|
# So, with 'partial' objects, passing a keyword argument is
|
|
# like setting a new default value for the corresponding
|
|
# parameter
|
|
#
|
|
# We also mark this parameter with '_partial_kwarg'
|
|
# flag. Later, in '_bind', the 'default' value of this
|
|
# parameter will be added to 'kwargs', to simulate
|
|
# the 'functools.partial' real call.
|
|
new_params[arg_name] = param.replace(default=arg_value,
|
|
_partial_kwarg=True)
|
|
|
|
elif (param.kind not in (_VAR_KEYWORD, _VAR_POSITIONAL) and
|
|
not param._partial_kwarg):
|
|
new_params.pop(arg_name)
|
|
|
|
return sig.replace(parameters=new_params.values())
|
|
|
|
sig = None
|
|
if isinstance(obj, type):
|
|
# obj is a class or a metaclass
|
|
|
|
# First, let's see if it has an overloaded __call__ defined
|
|
# in its metaclass
|
|
call = _get_user_defined_method(type(obj), '__call__')
|
|
if call is not None:
|
|
sig = signature(call)
|
|
else:
|
|
# Now we check if the 'obj' class has a '__new__' method
|
|
new = _get_user_defined_method(obj, '__new__')
|
|
if new is not None:
|
|
sig = signature(new)
|
|
else:
|
|
# Finally, we should have at least __init__ implemented
|
|
init = _get_user_defined_method(obj, '__init__')
|
|
if init is not None:
|
|
sig = signature(init)
|
|
elif not isinstance(obj, _NonUserDefinedCallables):
|
|
# An object with __call__
|
|
# We also check that the 'obj' is not an instance of
|
|
# _WrapperDescriptor or _MethodWrapper to avoid
|
|
# infinite recursion (and even potential segfault)
|
|
call = _get_user_defined_method(type(obj), '__call__')
|
|
if call is not None:
|
|
sig = signature(call)
|
|
|
|
if sig is not None:
|
|
# For classes and objects we skip the first parameter of their
|
|
# __call__, __new__, or __init__ methods
|
|
return sig.replace(parameters=tuple(sig.parameters.values())[1:])
|
|
|
|
if isinstance(obj, types.BuiltinFunctionType):
|
|
# Raise a nicer error message for builtins
|
|
msg = 'no signature found for builtin function {!r}'.format(obj)
|
|
raise ValueError(msg)
|
|
|
|
raise ValueError('callable {!r} is not supported by signature'.format(obj))
|
|
|
|
|
|
class _void:
|
|
'''A private marker - used in Parameter & Signature'''
|
|
|
|
|
|
class _empty:
|
|
pass
|
|
|
|
|
|
class _ParameterKind(int):
|
|
def __new__(self, *args, name):
|
|
obj = int.__new__(self, *args)
|
|
obj._name = name
|
|
return obj
|
|
|
|
def __str__(self):
|
|
return self._name
|
|
|
|
def __repr__(self):
|
|
return '<_ParameterKind: {!r}>'.format(self._name)
|
|
|
|
|
|
_POSITIONAL_ONLY = _ParameterKind(0, name='POSITIONAL_ONLY')
|
|
_POSITIONAL_OR_KEYWORD = _ParameterKind(1, name='POSITIONAL_OR_KEYWORD')
|
|
_VAR_POSITIONAL = _ParameterKind(2, name='VAR_POSITIONAL')
|
|
_KEYWORD_ONLY = _ParameterKind(3, name='KEYWORD_ONLY')
|
|
_VAR_KEYWORD = _ParameterKind(4, name='VAR_KEYWORD')
|
|
|
|
|
|
class Parameter:
|
|
'''Represents a parameter in a function signature.
|
|
|
|
Has the following public attributes:
|
|
|
|
* 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
|
|
The annotation for the parameter if specified. If the
|
|
parameter has no annotation, this attribute is not set.
|
|
* kind : str
|
|
Describes how argument values are bound to the 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')
|
|
|
|
POSITIONAL_ONLY = _POSITIONAL_ONLY
|
|
POSITIONAL_OR_KEYWORD = _POSITIONAL_OR_KEYWORD
|
|
VAR_POSITIONAL = _VAR_POSITIONAL
|
|
KEYWORD_ONLY = _KEYWORD_ONLY
|
|
VAR_KEYWORD = _VAR_KEYWORD
|
|
|
|
empty = _empty
|
|
|
|
def __init__(self, name, kind, *, default=_empty, annotation=_empty,
|
|
_partial_kwarg=False):
|
|
|
|
if kind not in (_POSITIONAL_ONLY, _POSITIONAL_OR_KEYWORD,
|
|
_VAR_POSITIONAL, _KEYWORD_ONLY, _VAR_KEYWORD):
|
|
raise ValueError("invalid value for 'Parameter.kind' attribute")
|
|
self._kind = kind
|
|
|
|
if default is not _empty:
|
|
if kind in (_VAR_POSITIONAL, _VAR_KEYWORD):
|
|
msg = '{} parameters cannot have default values'.format(kind)
|
|
raise ValueError(msg)
|
|
self._default = default
|
|
self._annotation = annotation
|
|
|
|
if name is None:
|
|
if kind != _POSITIONAL_ONLY:
|
|
raise ValueError("None is not a valid name for a "
|
|
"non-positional-only parameter")
|
|
self._name = name
|
|
else:
|
|
name = str(name)
|
|
if kind != _POSITIONAL_ONLY and not name.isidentifier():
|
|
msg = '{!r} is not a valid parameter name'.format(name)
|
|
raise ValueError(msg)
|
|
self._name = name
|
|
|
|
self._partial_kwarg = _partial_kwarg
|
|
|
|
@property
|
|
def name(self):
|
|
return self._name
|
|
|
|
@property
|
|
def default(self):
|
|
return self._default
|
|
|
|
@property
|
|
def annotation(self):
|
|
return self._annotation
|
|
|
|
@property
|
|
def kind(self):
|
|
return self._kind
|
|
|
|
def replace(self, *, name=_void, kind=_void, annotation=_void,
|
|
default=_void, _partial_kwarg=_void):
|
|
'''Creates a customized copy of the Parameter.'''
|
|
|
|
if name is _void:
|
|
name = self._name
|
|
|
|
if kind is _void:
|
|
kind = self._kind
|
|
|
|
if annotation is _void:
|
|
annotation = self._annotation
|
|
|
|
if default is _void:
|
|
default = self._default
|
|
|
|
if _partial_kwarg is _void:
|
|
_partial_kwarg = self._partial_kwarg
|
|
|
|
return type(self)(name, kind, default=default, annotation=annotation,
|
|
_partial_kwarg=_partial_kwarg)
|
|
|
|
def __str__(self):
|
|
kind = self.kind
|
|
|
|
formatted = self._name
|
|
if kind == _POSITIONAL_ONLY:
|
|
if formatted is None:
|
|
formatted = ''
|
|
formatted = '<{}>'.format(formatted)
|
|
|
|
# Add annotation and default value
|
|
if self._annotation is not _empty:
|
|
formatted = '{}:{}'.format(formatted,
|
|
formatannotation(self._annotation))
|
|
|
|
if self._default is not _empty:
|
|
formatted = '{}={}'.format(formatted, repr(self._default))
|
|
|
|
if kind == _VAR_POSITIONAL:
|
|
formatted = '*' + formatted
|
|
elif kind == _VAR_KEYWORD:
|
|
formatted = '**' + formatted
|
|
|
|
return formatted
|
|
|
|
def __repr__(self):
|
|
return '<{} at {:#x} {!r}>'.format(self.__class__.__name__,
|
|
id(self), self.name)
|
|
|
|
def __eq__(self, other):
|
|
return (issubclass(other.__class__, Parameter) and
|
|
self._name == other._name and
|
|
self._kind == other._kind and
|
|
self._default == other._default and
|
|
self._annotation == other._annotation)
|
|
|
|
def __ne__(self, other):
|
|
return not self.__eq__(other)
|
|
|
|
|
|
class BoundArguments:
|
|
'''Result of `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.
|
|
* signature : Signature
|
|
The Signature object that created this instance.
|
|
* args : tuple
|
|
Tuple of positional arguments values.
|
|
* kwargs : dict
|
|
Dict of keyword arguments values.
|
|
'''
|
|
|
|
def __init__(self, signature, arguments):
|
|
self.arguments = arguments
|
|
self._signature = signature
|
|
|
|
@property
|
|
def signature(self):
|
|
return self._signature
|
|
|
|
@property
|
|
def args(self):
|
|
args = []
|
|
for param_name, param in self._signature.parameters.items():
|
|
if (param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY) or
|
|
param._partial_kwarg):
|
|
# Keyword arguments mapped by 'functools.partial'
|
|
# (Parameter._partial_kwarg is True) are mapped
|
|
# in 'BoundArguments.kwargs', along with VAR_KEYWORD &
|
|
# KEYWORD_ONLY
|
|
break
|
|
|
|
try:
|
|
arg = self.arguments[param_name]
|
|
except KeyError:
|
|
# We're done here. Other arguments
|
|
# will be mapped in 'BoundArguments.kwargs'
|
|
break
|
|
else:
|
|
if param.kind == _VAR_POSITIONAL:
|
|
# *args
|
|
args.extend(arg)
|
|
else:
|
|
# plain argument
|
|
args.append(arg)
|
|
|
|
return tuple(args)
|
|
|
|
@property
|
|
def kwargs(self):
|
|
kwargs = {}
|
|
kwargs_started = False
|
|
for param_name, param in self._signature.parameters.items():
|
|
if not kwargs_started:
|
|
if (param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY) or
|
|
param._partial_kwarg):
|
|
kwargs_started = True
|
|
else:
|
|
if param_name not in self.arguments:
|
|
kwargs_started = True
|
|
continue
|
|
|
|
if not kwargs_started:
|
|
continue
|
|
|
|
try:
|
|
arg = self.arguments[param_name]
|
|
except KeyError:
|
|
pass
|
|
else:
|
|
if param.kind == _VAR_KEYWORD:
|
|
# **kwargs
|
|
kwargs.update(arg)
|
|
else:
|
|
# plain keyword argument
|
|
kwargs[param_name] = arg
|
|
|
|
return kwargs
|
|
|
|
def __eq__(self, other):
|
|
return (issubclass(other.__class__, BoundArguments) and
|
|
self.signature == other.signature and
|
|
self.arguments == other.arguments)
|
|
|
|
def __ne__(self, other):
|
|
return not self.__eq__(other)
|
|
|
|
|
|
class Signature:
|
|
'''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:
|
|
|
|
* 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`).
|
|
* 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.
|
|
* bind(*args, **kwargs) -> BoundArguments
|
|
Creates a mapping from positional and keyword arguments to
|
|
parameters.
|
|
* bind_partial(*args, **kwargs) -> BoundArguments
|
|
Creates a partial mapping from positional and keyword arguments
|
|
to parameters (simulating 'functools.partial' behavior.)
|
|
'''
|
|
|
|
__slots__ = ('_return_annotation', '_parameters')
|
|
|
|
_parameter_cls = Parameter
|
|
_bound_arguments_cls = BoundArguments
|
|
|
|
empty = _empty
|
|
|
|
def __init__(self, parameters=None, *, return_annotation=_empty,
|
|
__validate_parameters__=True):
|
|
'''Constructs Signature from the given list of Parameter
|
|
objects and 'return_annotation'. All arguments are optional.
|
|
'''
|
|
|
|
if parameters is None:
|
|
params = OrderedDict()
|
|
else:
|
|
if __validate_parameters__:
|
|
params = OrderedDict()
|
|
top_kind = _POSITIONAL_ONLY
|
|
|
|
for idx, param in enumerate(parameters):
|
|
kind = param.kind
|
|
if kind < top_kind:
|
|
msg = 'wrong parameter order: {} before {}'
|
|
msg = msg.format(top_kind, param.kind)
|
|
raise ValueError(msg)
|
|
else:
|
|
top_kind = kind
|
|
|
|
name = param.name
|
|
if name is None:
|
|
name = str(idx)
|
|
param = param.replace(name=name)
|
|
|
|
if name in params:
|
|
msg = 'duplicate parameter name: {!r}'.format(name)
|
|
raise ValueError(msg)
|
|
params[name] = param
|
|
else:
|
|
params = OrderedDict(((param.name, param)
|
|
for param in parameters))
|
|
|
|
self._parameters = types.MappingProxyType(params)
|
|
self._return_annotation = return_annotation
|
|
|
|
@classmethod
|
|
def from_function(cls, func):
|
|
'''Constructs Signature for the given python function'''
|
|
|
|
if not isinstance(func, types.FunctionType):
|
|
raise TypeError('{!r} is not a Python function'.format(func))
|
|
|
|
Parameter = cls._parameter_cls
|
|
|
|
# Parameter information.
|
|
func_code = func.__code__
|
|
pos_count = func_code.co_argcount
|
|
arg_names = func_code.co_varnames
|
|
positional = tuple(arg_names[:pos_count])
|
|
keyword_only_count = func_code.co_kwonlyargcount
|
|
keyword_only = arg_names[pos_count:(pos_count + keyword_only_count)]
|
|
annotations = func.__annotations__
|
|
defaults = func.__defaults__
|
|
kwdefaults = func.__kwdefaults__
|
|
|
|
if defaults:
|
|
pos_default_count = len(defaults)
|
|
else:
|
|
pos_default_count = 0
|
|
|
|
parameters = []
|
|
|
|
# Non-keyword-only parameters w/o defaults.
|
|
non_default_count = pos_count - pos_default_count
|
|
for name in positional[:non_default_count]:
|
|
annotation = annotations.get(name, _empty)
|
|
parameters.append(Parameter(name, annotation=annotation,
|
|
kind=_POSITIONAL_OR_KEYWORD))
|
|
|
|
# ... w/ defaults.
|
|
for offset, name in enumerate(positional[non_default_count:]):
|
|
annotation = annotations.get(name, _empty)
|
|
parameters.append(Parameter(name, annotation=annotation,
|
|
kind=_POSITIONAL_OR_KEYWORD,
|
|
default=defaults[offset]))
|
|
|
|
# *args
|
|
if func_code.co_flags & 0x04:
|
|
name = arg_names[pos_count + keyword_only_count]
|
|
annotation = annotations.get(name, _empty)
|
|
parameters.append(Parameter(name, annotation=annotation,
|
|
kind=_VAR_POSITIONAL))
|
|
|
|
# Keyword-only parameters.
|
|
for name in keyword_only:
|
|
default = _empty
|
|
if kwdefaults is not None:
|
|
default = kwdefaults.get(name, _empty)
|
|
|
|
annotation = annotations.get(name, _empty)
|
|
parameters.append(Parameter(name, annotation=annotation,
|
|
kind=_KEYWORD_ONLY,
|
|
default=default))
|
|
# **kwargs
|
|
if func_code.co_flags & 0x08:
|
|
index = pos_count + keyword_only_count
|
|
if func_code.co_flags & 0x04:
|
|
index += 1
|
|
|
|
name = arg_names[index]
|
|
annotation = annotations.get(name, _empty)
|
|
parameters.append(Parameter(name, annotation=annotation,
|
|
kind=_VAR_KEYWORD))
|
|
|
|
return cls(parameters,
|
|
return_annotation=annotations.get('return', _empty),
|
|
__validate_parameters__=False)
|
|
|
|
@property
|
|
def parameters(self):
|
|
return self._parameters
|
|
|
|
@property
|
|
def return_annotation(self):
|
|
return self._return_annotation
|
|
|
|
def replace(self, *, parameters=_void, return_annotation=_void):
|
|
'''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()
|
|
|
|
if return_annotation is _void:
|
|
return_annotation = self._return_annotation
|
|
|
|
return type(self)(parameters,
|
|
return_annotation=return_annotation)
|
|
|
|
def __eq__(self, other):
|
|
if (not issubclass(type(other), Signature) or
|
|
self.return_annotation != other.return_annotation or
|
|
len(self.parameters) != len(other.parameters)):
|
|
return False
|
|
|
|
other_positions = {param: idx
|
|
for idx, param in enumerate(other.parameters.keys())}
|
|
|
|
for idx, (param_name, param) in enumerate(self.parameters.items()):
|
|
if param.kind == _KEYWORD_ONLY:
|
|
try:
|
|
other_param = other.parameters[param_name]
|
|
except KeyError:
|
|
return False
|
|
else:
|
|
if param != other_param:
|
|
return False
|
|
else:
|
|
try:
|
|
other_idx = other_positions[param_name]
|
|
except KeyError:
|
|
return False
|
|
else:
|
|
if (idx != other_idx or
|
|
param != other.parameters[param_name]):
|
|
return False
|
|
|
|
return True
|
|
|
|
def __ne__(self, other):
|
|
return not self.__eq__(other)
|
|
|
|
def _bind(self, args, kwargs, *, partial=False):
|
|
'''Private method. Don't use directly.'''
|
|
|
|
arguments = OrderedDict()
|
|
|
|
parameters = iter(self.parameters.values())
|
|
parameters_ex = ()
|
|
arg_vals = iter(args)
|
|
|
|
if partial:
|
|
# Support for binding arguments to 'functools.partial' objects.
|
|
# See 'functools.partial' case in 'signature()' implementation
|
|
# for details.
|
|
for param_name, param in self.parameters.items():
|
|
if (param._partial_kwarg and param_name not in kwargs):
|
|
# Simulating 'functools.partial' behavior
|
|
kwargs[param_name] = param.default
|
|
|
|
while True:
|
|
# Let's iterate through the positional arguments and corresponding
|
|
# parameters
|
|
try:
|
|
arg_val = next(arg_vals)
|
|
except StopIteration:
|
|
# No more positional arguments
|
|
try:
|
|
param = next(parameters)
|
|
except StopIteration:
|
|
# No more parameters. That's it. Just need to check that
|
|
# we have no `kwargs` after this while loop
|
|
break
|
|
else:
|
|
if param.kind == _VAR_POSITIONAL:
|
|
# That's OK, just empty *args. Let's start parsing
|
|
# kwargs
|
|
break
|
|
elif param.name in kwargs:
|
|
if param.kind == _POSITIONAL_ONLY:
|
|
msg = '{arg!r} parameter is positional only, ' \
|
|
'but was passed as a keyword'
|
|
msg = msg.format(arg=param.name)
|
|
raise TypeError(msg) from None
|
|
parameters_ex = (param,)
|
|
break
|
|
elif (param.kind == _VAR_KEYWORD or
|
|
param.default is not _empty):
|
|
# That's fine too - we have a default value for this
|
|
# parameter. So, lets start parsing `kwargs`, starting
|
|
# with the current parameter
|
|
parameters_ex = (param,)
|
|
break
|
|
else:
|
|
if partial:
|
|
parameters_ex = (param,)
|
|
break
|
|
else:
|
|
msg = '{arg!r} parameter lacking default value'
|
|
msg = msg.format(arg=param.name)
|
|
raise TypeError(msg) from None
|
|
else:
|
|
# We have a positional argument to process
|
|
try:
|
|
param = next(parameters)
|
|
except StopIteration:
|
|
raise TypeError('too many positional arguments') from None
|
|
else:
|
|
if param.kind in (_VAR_KEYWORD, _KEYWORD_ONLY):
|
|
# Looks like we have no parameter for this positional
|
|
# argument
|
|
raise TypeError('too many positional arguments')
|
|
|
|
if param.kind == _VAR_POSITIONAL:
|
|
# We have an '*args'-like argument, let's fill it with
|
|
# all positional arguments we have left and move on to
|
|
# the next phase
|
|
values = [arg_val]
|
|
values.extend(arg_vals)
|
|
arguments[param.name] = tuple(values)
|
|
break
|
|
|
|
if param.name in kwargs:
|
|
raise TypeError('multiple values for argument '
|
|
'{arg!r}'.format(arg=param.name))
|
|
|
|
arguments[param.name] = arg_val
|
|
|
|
# Now, we iterate through the remaining parameters to process
|
|
# keyword arguments
|
|
kwargs_param = None
|
|
for param in itertools.chain(parameters_ex, parameters):
|
|
if param.kind == _POSITIONAL_ONLY:
|
|
# This should never happen in case of a properly built
|
|
# Signature object (but let's have this check here
|
|
# to ensure correct behaviour just in case)
|
|
raise TypeError('{arg!r} parameter is positional only, '
|
|
'but was passed as a keyword'. \
|
|
format(arg=param.name))
|
|
|
|
if param.kind == _VAR_KEYWORD:
|
|
# Memorize that we have a '**kwargs'-like parameter
|
|
kwargs_param = param
|
|
continue
|
|
|
|
param_name = param.name
|
|
try:
|
|
arg_val = kwargs.pop(param_name)
|
|
except KeyError:
|
|
# We have no value for this parameter. It's fine though,
|
|
# if it has a default value, or it is an '*args'-like
|
|
# parameter, left alone by the processing of positional
|
|
# arguments.
|
|
if (not partial and param.kind != _VAR_POSITIONAL and
|
|
param.default is _empty):
|
|
raise TypeError('{arg!r} parameter lacking default value'. \
|
|
format(arg=param_name)) from None
|
|
|
|
else:
|
|
arguments[param_name] = arg_val
|
|
|
|
if kwargs:
|
|
if kwargs_param is not None:
|
|
# Process our '**kwargs'-like parameter
|
|
arguments[kwargs_param.name] = kwargs
|
|
else:
|
|
raise TypeError('too many keyword arguments')
|
|
|
|
return self._bound_arguments_cls(self, arguments)
|
|
|
|
def bind(__bind_self, *args, **kwargs):
|
|
'''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 __bind_self._bind(args, kwargs)
|
|
|
|
def bind_partial(__bind_self, *args, **kwargs):
|
|
'''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 __bind_self._bind(args, kwargs, partial=True)
|
|
|
|
def __str__(self):
|
|
result = []
|
|
render_kw_only_separator = True
|
|
for idx, param in enumerate(self.parameters.values()):
|
|
formatted = str(param)
|
|
|
|
kind = param.kind
|
|
if kind == _VAR_POSITIONAL:
|
|
# OK, we have an '*args'-like parameter, so we won't need
|
|
# a '*' to separate keyword-only arguments
|
|
render_kw_only_separator = False
|
|
elif kind == _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(', '.join(result))
|
|
|
|
if self.return_annotation is not _empty:
|
|
anno = formatannotation(self.return_annotation)
|
|
rendered += ' -> {}'.format(anno)
|
|
|
|
return rendered
|