mirror of https://github.com/python/cpython
1220 lines
46 KiB
Python
1220 lines
46 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
|
|
"""
|
|
|
|
# This module is in the public domain. No warranties.
|
|
|
|
__author__ = 'Ka-Ping Yee <ping@lfw.org>'
|
|
__date__ = '1 Jan 2001'
|
|
|
|
import sys
|
|
import os
|
|
import types
|
|
import itertools
|
|
import re
|
|
import imp
|
|
import tokenize
|
|
import linecache
|
|
from operator import attrgetter
|
|
from collections import namedtuple
|
|
|
|
# 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."""
|
|
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."""
|
|
info = getmoduleinfo(path)
|
|
if info: return info[0]
|
|
|
|
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)
|
|
if filename[-4:].lower() in ('.pyc', '.pyo'):
|
|
filename = filename[:-4] + '.py'
|
|
for suffix, mode, kind in imp.get_suffixes():
|
|
if 'b' in mode and filename[-len(suffix):].lower() == suffix:
|
|
# Looks like a binary file. We want to only return a text file.
|
|
return None
|
|
if os.path.exists(filename):
|
|
return filename
|
|
# only return a non-existent filename if the module has a PEP 302 loader
|
|
if hasattr(getmodule(object, filename), '__loader__'):
|
|
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 IOError
|
|
is raised if the source code cannot be retrieved."""
|
|
|
|
file = getfile(object)
|
|
sourcefile = getsourcefile(object)
|
|
if not sourcefile and file[0] + file[-1] != '<>':
|
|
raise IOError('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 IOError('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 IOError('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 IOError('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 IOError('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 (IOError, 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 IOError 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
|
|
IOError 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
|
|
|
|
# -------------------------------------------------- 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 IOError:
|
|
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)
|
|
|
|
|
|
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
|