Clarify the docs for the 'strict' argument to httplib.HTTPConnection.
[python.git] / Lib / inspect.py
blobd3d946d525c1c860c4490ff1585803d4d4559ecc
1 # -*- coding: iso-8859-1 -*-
2 """Get useful information from live Python objects.
4 This module encapsulates the interface provided by the internal special
5 attributes (func_*, co_*, im_*, tb_*, etc.) in a friendlier fashion.
6 It also provides some help for examining source code and class layout.
8 Here are some of the useful functions provided by this module:
10 ismodule(), isclass(), ismethod(), isfunction(), isgeneratorfunction(),
11 isgenerator(), istraceback(), isframe(), iscode(), isbuiltin(),
12 isroutine() - check object types
13 getmembers() - get members of an object that satisfy a given condition
15 getfile(), getsourcefile(), getsource() - find an object's source code
16 getdoc(), getcomments() - get documentation on an object
17 getmodule() - determine the module that an object came from
18 getclasstree() - arrange classes so as to represent their hierarchy
20 getargspec(), getargvalues() - get info about function arguments
21 formatargspec(), formatargvalues() - format an argument spec
22 getouterframes(), getinnerframes() - get info about frames
23 currentframe() - get the current stack frame
24 stack(), trace() - get info about frames on the stack or in a traceback
25 """
27 # This module is in the public domain. No warranties.
29 __author__ = 'Ka-Ping Yee <ping@lfw.org>'
30 __date__ = '1 Jan 2001'
32 import sys
33 import os
34 import types
35 import string
36 import re
37 import dis
38 import imp
39 import tokenize
40 import linecache
41 from operator import attrgetter
42 from collections import namedtuple
44 # These constants are from Include/code.h.
45 CO_OPTIMIZED, CO_NEWLOCALS, CO_VARARGS, CO_VARKEYWORDS = 0x1, 0x2, 0x4, 0x8
46 CO_NESTED, CO_GENERATOR, CO_NOFREE = 0x10, 0x20, 0x40
47 # See Include/object.h
48 TPFLAGS_IS_ABSTRACT = 1 << 20
50 # ----------------------------------------------------------- type-checking
51 def ismodule(object):
52 """Return true if the object is a module.
54 Module objects provide these attributes:
55 __doc__ documentation string
56 __file__ filename (missing for built-in modules)"""
57 return isinstance(object, types.ModuleType)
59 def isclass(object):
60 """Return true if the object is a class.
62 Class objects provide these attributes:
63 __doc__ documentation string
64 __module__ name of module in which this class was defined"""
65 return isinstance(object, types.ClassType) or hasattr(object, '__bases__')
67 def ismethod(object):
68 """Return true if the object is an instance method.
70 Instance method objects provide these attributes:
71 __doc__ documentation string
72 __name__ name with which this method was defined
73 im_class class object in which this method belongs
74 im_func function object containing implementation of method
75 im_self instance to which this method is bound, or None"""
76 return isinstance(object, types.MethodType)
78 def ismethoddescriptor(object):
79 """Return true if the object is a method descriptor.
81 But not if ismethod() or isclass() or isfunction() are true.
83 This is new in Python 2.2, and, for example, is true of int.__add__.
84 An object passing this test has a __get__ attribute but not a __set__
85 attribute, but beyond that the set of attributes varies. __name__ is
86 usually sensible, and __doc__ often is.
88 Methods implemented via descriptors that also pass one of the other
89 tests return false from the ismethoddescriptor() test, simply because
90 the other tests promise more -- you can, e.g., count on having the
91 im_func attribute (etc) when an object passes ismethod()."""
92 return (hasattr(object, "__get__")
93 and not hasattr(object, "__set__") # else it's a data descriptor
94 and not ismethod(object) # mutual exclusion
95 and not isfunction(object)
96 and not isclass(object))
98 def isdatadescriptor(object):
99 """Return true if the object is a data descriptor.
101 Data descriptors have both a __get__ and a __set__ attribute. Examples are
102 properties (defined in Python) and getsets and members (defined in C).
103 Typically, data descriptors will also have __name__ and __doc__ attributes
104 (properties, getsets, and members have both of these attributes), but this
105 is not guaranteed."""
106 return (hasattr(object, "__set__") and hasattr(object, "__get__"))
108 if hasattr(types, 'MemberDescriptorType'):
109 # CPython and equivalent
110 def ismemberdescriptor(object):
111 """Return true if the object is a member descriptor.
113 Member descriptors are specialized descriptors defined in extension
114 modules."""
115 return isinstance(object, types.MemberDescriptorType)
116 else:
117 # Other implementations
118 def ismemberdescriptor(object):
119 """Return true if the object is a member descriptor.
121 Member descriptors are specialized descriptors defined in extension
122 modules."""
123 return False
125 if hasattr(types, 'GetSetDescriptorType'):
126 # CPython and equivalent
127 def isgetsetdescriptor(object):
128 """Return true if the object is a getset descriptor.
130 getset descriptors are specialized descriptors defined in extension
131 modules."""
132 return isinstance(object, types.GetSetDescriptorType)
133 else:
134 # Other implementations
135 def isgetsetdescriptor(object):
136 """Return true if the object is a getset descriptor.
138 getset descriptors are specialized descriptors defined in extension
139 modules."""
140 return False
142 def isfunction(object):
143 """Return true if the object is a user-defined function.
145 Function objects provide these attributes:
146 __doc__ documentation string
147 __name__ name with which this function was defined
148 func_code code object containing compiled function bytecode
149 func_defaults tuple of any default values for arguments
150 func_doc (same as __doc__)
151 func_globals global namespace in which this function was defined
152 func_name (same as __name__)"""
153 return isinstance(object, types.FunctionType)
155 def isgeneratorfunction(object):
156 """Return true if the object is a user-defined generator function.
158 Generator function objects provides same attributes as functions.
160 See isfunction.__doc__ for attributes listing."""
161 if (isfunction(object) or ismethod(object)) and \
162 object.func_code.co_flags & CO_GENERATOR:
163 return True
165 def isgenerator(object):
166 """Return true if the object is a generator.
168 Generator objects provide these attributes:
169 __iter__ defined to support interation over container
170 close raises a new GeneratorExit exception inside the
171 generator to terminate the iteration
172 gi_code code object
173 gi_frame frame object or possibly None once the generator has
174 been exhausted
175 gi_running set to 1 when generator is executing, 0 otherwise
176 next return the next item from the container
177 send resumes the generator and "sends" a value that becomes
178 the result of the current yield-expression
179 throw used to raise an exception inside the generator"""
180 return isinstance(object, types.GeneratorType)
182 def istraceback(object):
183 """Return true if the object is a traceback.
185 Traceback objects provide these attributes:
186 tb_frame frame object at this level
187 tb_lasti index of last attempted instruction in bytecode
188 tb_lineno current line number in Python source code
189 tb_next next inner traceback object (called by this level)"""
190 return isinstance(object, types.TracebackType)
192 def isframe(object):
193 """Return true if the object is a frame object.
195 Frame objects provide these attributes:
196 f_back next outer frame object (this frame's caller)
197 f_builtins built-in namespace seen by this frame
198 f_code code object being executed in this frame
199 f_exc_traceback traceback if raised in this frame, or None
200 f_exc_type exception type if raised in this frame, or None
201 f_exc_value exception value if raised in this frame, or None
202 f_globals global namespace seen by this frame
203 f_lasti index of last attempted instruction in bytecode
204 f_lineno current line number in Python source code
205 f_locals local namespace seen by this frame
206 f_restricted 0 or 1 if frame is in restricted execution mode
207 f_trace tracing function for this frame, or None"""
208 return isinstance(object, types.FrameType)
210 def iscode(object):
211 """Return true if the object is a code object.
213 Code objects provide these attributes:
214 co_argcount number of arguments (not including * or ** args)
215 co_code string of raw compiled bytecode
216 co_consts tuple of constants used in the bytecode
217 co_filename name of file in which this code object was created
218 co_firstlineno number of first line in Python source code
219 co_flags bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
220 co_lnotab encoded mapping of line numbers to bytecode indices
221 co_name name with which this code object was defined
222 co_names tuple of names of local variables
223 co_nlocals number of local variables
224 co_stacksize virtual machine stack space required
225 co_varnames tuple of names of arguments and local variables"""
226 return isinstance(object, types.CodeType)
228 def isbuiltin(object):
229 """Return true if the object is a built-in function or method.
231 Built-in functions and methods provide these attributes:
232 __doc__ documentation string
233 __name__ original name of this function or method
234 __self__ instance to which a method is bound, or None"""
235 return isinstance(object, types.BuiltinFunctionType)
237 def isroutine(object):
238 """Return true if the object is any kind of function or method."""
239 return (isbuiltin(object)
240 or isfunction(object)
241 or ismethod(object)
242 or ismethoddescriptor(object))
244 def isgenerator(object):
245 """Return true if the object is a generator object."""
246 return isinstance(object, types.GeneratorType)
248 def isabstract(object):
249 """Return true if the object is an abstract base class (ABC)."""
250 return isinstance(object, type) and object.__flags__ & TPFLAGS_IS_ABSTRACT
252 def getmembers(object, predicate=None):
253 """Return all members of an object as (name, value) pairs sorted by name.
254 Optionally, only return members that satisfy a given predicate."""
255 results = []
256 for key in dir(object):
257 value = getattr(object, key)
258 if not predicate or predicate(value):
259 results.append((key, value))
260 results.sort()
261 return results
263 Attribute = namedtuple('Attribute', 'name kind defining_class object')
265 def classify_class_attrs(cls):
266 """Return list of attribute-descriptor tuples.
268 For each name in dir(cls), the return list contains a 4-tuple
269 with these elements:
271 0. The name (a string).
273 1. The kind of attribute this is, one of these strings:
274 'class method' created via classmethod()
275 'static method' created via staticmethod()
276 'property' created via property()
277 'method' any other flavor of method
278 'data' not a method
280 2. The class which defined this attribute (a class).
282 3. The object as obtained directly from the defining class's
283 __dict__, not via getattr. This is especially important for
284 data attributes: C.data is just a data object, but
285 C.__dict__['data'] may be a data descriptor with additional
286 info, like a __doc__ string.
289 mro = getmro(cls)
290 names = dir(cls)
291 result = []
292 for name in names:
293 # Get the object associated with the name.
294 # Getting an obj from the __dict__ sometimes reveals more than
295 # using getattr. Static and class methods are dramatic examples.
296 if name in cls.__dict__:
297 obj = cls.__dict__[name]
298 else:
299 obj = getattr(cls, name)
301 # Figure out where it was defined.
302 homecls = getattr(obj, "__objclass__", None)
303 if homecls is None:
304 # search the dicts.
305 for base in mro:
306 if name in base.__dict__:
307 homecls = base
308 break
310 # Get the object again, in order to get it from the defining
311 # __dict__ instead of via getattr (if possible).
312 if homecls is not None and name in homecls.__dict__:
313 obj = homecls.__dict__[name]
315 # Also get the object via getattr.
316 obj_via_getattr = getattr(cls, name)
318 # Classify the object.
319 if isinstance(obj, staticmethod):
320 kind = "static method"
321 elif isinstance(obj, classmethod):
322 kind = "class method"
323 elif isinstance(obj, property):
324 kind = "property"
325 elif (ismethod(obj_via_getattr) or
326 ismethoddescriptor(obj_via_getattr)):
327 kind = "method"
328 else:
329 kind = "data"
331 result.append(Attribute(name, kind, homecls, obj))
333 return result
335 # ----------------------------------------------------------- class helpers
336 def _searchbases(cls, accum):
337 # Simulate the "classic class" search order.
338 if cls in accum:
339 return
340 accum.append(cls)
341 for base in cls.__bases__:
342 _searchbases(base, accum)
344 def getmro(cls):
345 "Return tuple of base classes (including cls) in method resolution order."
346 if hasattr(cls, "__mro__"):
347 return cls.__mro__
348 else:
349 result = []
350 _searchbases(cls, result)
351 return tuple(result)
353 # -------------------------------------------------- source code extraction
354 def indentsize(line):
355 """Return the indent size, in spaces, at the start of a line of text."""
356 expline = string.expandtabs(line)
357 return len(expline) - len(string.lstrip(expline))
359 def getdoc(object):
360 """Get the documentation string for an object.
362 All tabs are expanded to spaces. To clean up docstrings that are
363 indented to line up with blocks of code, any whitespace than can be
364 uniformly removed from the second line onwards is removed."""
365 try:
366 doc = object.__doc__
367 except AttributeError:
368 return None
369 if not isinstance(doc, types.StringTypes):
370 return None
371 return cleandoc(doc)
373 def cleandoc(doc):
374 """Clean up indentation from docstrings.
376 Any whitespace that can be uniformly removed from the second line
377 onwards is removed."""
378 try:
379 lines = string.split(string.expandtabs(doc), '\n')
380 except UnicodeError:
381 return None
382 else:
383 # Find minimum indentation of any non-blank lines after first line.
384 margin = sys.maxint
385 for line in lines[1:]:
386 content = len(string.lstrip(line))
387 if content:
388 indent = len(line) - content
389 margin = min(margin, indent)
390 # Remove indentation.
391 if lines:
392 lines[0] = lines[0].lstrip()
393 if margin < sys.maxint:
394 for i in range(1, len(lines)): lines[i] = lines[i][margin:]
395 # Remove any trailing or leading blank lines.
396 while lines and not lines[-1]:
397 lines.pop()
398 while lines and not lines[0]:
399 lines.pop(0)
400 return string.join(lines, '\n')
402 def getfile(object):
403 """Work out which source or compiled file an object was defined in."""
404 if ismodule(object):
405 if hasattr(object, '__file__'):
406 return object.__file__
407 raise TypeError('arg is a built-in module')
408 if isclass(object):
409 object = sys.modules.get(object.__module__)
410 if hasattr(object, '__file__'):
411 return object.__file__
412 raise TypeError('arg is a built-in class')
413 if ismethod(object):
414 object = object.im_func
415 if isfunction(object):
416 object = object.func_code
417 if istraceback(object):
418 object = object.tb_frame
419 if isframe(object):
420 object = object.f_code
421 if iscode(object):
422 return object.co_filename
423 raise TypeError('arg is not a module, class, method, '
424 'function, traceback, frame, or code object')
426 ModuleInfo = namedtuple('ModuleInfo', 'name suffix mode module_type')
428 def getmoduleinfo(path):
429 """Get the module name, suffix, mode, and module type for a given file."""
430 filename = os.path.basename(path)
431 suffixes = map(lambda info:
432 (-len(info[0]), info[0], info[1], info[2]),
433 imp.get_suffixes())
434 suffixes.sort() # try longest suffixes first, in case they overlap
435 for neglen, suffix, mode, mtype in suffixes:
436 if filename[neglen:] == suffix:
437 return ModuleInfo(filename[:neglen], suffix, mode, mtype)
439 def getmodulename(path):
440 """Return the module name for a given file, or None."""
441 info = getmoduleinfo(path)
442 if info: return info[0]
444 def getsourcefile(object):
445 """Return the Python source file an object was defined in, if it exists."""
446 filename = getfile(object)
447 if string.lower(filename[-4:]) in ('.pyc', '.pyo'):
448 filename = filename[:-4] + '.py'
449 for suffix, mode, kind in imp.get_suffixes():
450 if 'b' in mode and string.lower(filename[-len(suffix):]) == suffix:
451 # Looks like a binary file. We want to only return a text file.
452 return None
453 if os.path.exists(filename):
454 return filename
455 # only return a non-existent filename if the module has a PEP 302 loader
456 if hasattr(getmodule(object, filename), '__loader__'):
457 return filename
459 def getabsfile(object, _filename=None):
460 """Return an absolute path to the source or compiled file for an object.
462 The idea is for each object to have a unique origin, so this routine
463 normalizes the result as much as possible."""
464 if _filename is None:
465 _filename = getsourcefile(object) or getfile(object)
466 return os.path.normcase(os.path.abspath(_filename))
468 modulesbyfile = {}
469 _filesbymodname = {}
471 def getmodule(object, _filename=None):
472 """Return the module an object was defined in, or None if not found."""
473 if ismodule(object):
474 return object
475 if hasattr(object, '__module__'):
476 return sys.modules.get(object.__module__)
477 # Try the filename to modulename cache
478 if _filename is not None and _filename in modulesbyfile:
479 return sys.modules.get(modulesbyfile[_filename])
480 # Try the cache again with the absolute file name
481 try:
482 file = getabsfile(object, _filename)
483 except TypeError:
484 return None
485 if file in modulesbyfile:
486 return sys.modules.get(modulesbyfile[file])
487 # Update the filename to module name cache and check yet again
488 # Copy sys.modules in order to cope with changes while iterating
489 for modname, module in sys.modules.items():
490 if ismodule(module) and hasattr(module, '__file__'):
491 f = module.__file__
492 if f == _filesbymodname.get(modname, None):
493 # Have already mapped this module, so skip it
494 continue
495 _filesbymodname[modname] = f
496 f = getabsfile(module)
497 # Always map to the name the module knows itself by
498 modulesbyfile[f] = modulesbyfile[
499 os.path.realpath(f)] = module.__name__
500 if file in modulesbyfile:
501 return sys.modules.get(modulesbyfile[file])
502 # Check the main module
503 main = sys.modules['__main__']
504 if not hasattr(object, '__name__'):
505 return None
506 if hasattr(main, object.__name__):
507 mainobject = getattr(main, object.__name__)
508 if mainobject is object:
509 return main
510 # Check builtins
511 builtin = sys.modules['__builtin__']
512 if hasattr(builtin, object.__name__):
513 builtinobject = getattr(builtin, object.__name__)
514 if builtinobject is object:
515 return builtin
517 def findsource(object):
518 """Return the entire source file and starting line number for an object.
520 The argument may be a module, class, method, function, traceback, frame,
521 or code object. The source code is returned as a list of all the lines
522 in the file and the line number indexes a line in that list. An IOError
523 is raised if the source code cannot be retrieved."""
524 file = getsourcefile(object) or getfile(object)
525 module = getmodule(object, file)
526 if module:
527 lines = linecache.getlines(file, module.__dict__)
528 else:
529 lines = linecache.getlines(file)
530 if not lines:
531 raise IOError('could not get source code')
533 if ismodule(object):
534 return lines, 0
536 if isclass(object):
537 name = object.__name__
538 pat = re.compile(r'^(\s*)class\s*' + name + r'\b')
539 # make some effort to find the best matching class definition:
540 # use the one with the least indentation, which is the one
541 # that's most probably not inside a function definition.
542 candidates = []
543 for i in range(len(lines)):
544 match = pat.match(lines[i])
545 if match:
546 # if it's at toplevel, it's already the best one
547 if lines[i][0] == 'c':
548 return lines, i
549 # else add whitespace to candidate list
550 candidates.append((match.group(1), i))
551 if candidates:
552 # this will sort by whitespace, and by line number,
553 # less whitespace first
554 candidates.sort()
555 return lines, candidates[0][1]
556 else:
557 raise IOError('could not find class definition')
559 if ismethod(object):
560 object = object.im_func
561 if isfunction(object):
562 object = object.func_code
563 if istraceback(object):
564 object = object.tb_frame
565 if isframe(object):
566 object = object.f_code
567 if iscode(object):
568 if not hasattr(object, 'co_firstlineno'):
569 raise IOError('could not find function definition')
570 lnum = object.co_firstlineno - 1
571 pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
572 while lnum > 0:
573 if pat.match(lines[lnum]): break
574 lnum = lnum - 1
575 return lines, lnum
576 raise IOError('could not find code object')
578 def getcomments(object):
579 """Get lines of comments immediately preceding an object's source code.
581 Returns None when source can't be found.
583 try:
584 lines, lnum = findsource(object)
585 except (IOError, TypeError):
586 return None
588 if ismodule(object):
589 # Look for a comment block at the top of the file.
590 start = 0
591 if lines and lines[0][:2] == '#!': start = 1
592 while start < len(lines) and string.strip(lines[start]) in ('', '#'):
593 start = start + 1
594 if start < len(lines) and lines[start][:1] == '#':
595 comments = []
596 end = start
597 while end < len(lines) and lines[end][:1] == '#':
598 comments.append(string.expandtabs(lines[end]))
599 end = end + 1
600 return string.join(comments, '')
602 # Look for a preceding block of comments at the same indentation.
603 elif lnum > 0:
604 indent = indentsize(lines[lnum])
605 end = lnum - 1
606 if end >= 0 and string.lstrip(lines[end])[:1] == '#' and \
607 indentsize(lines[end]) == indent:
608 comments = [string.lstrip(string.expandtabs(lines[end]))]
609 if end > 0:
610 end = end - 1
611 comment = string.lstrip(string.expandtabs(lines[end]))
612 while comment[:1] == '#' and indentsize(lines[end]) == indent:
613 comments[:0] = [comment]
614 end = end - 1
615 if end < 0: break
616 comment = string.lstrip(string.expandtabs(lines[end]))
617 while comments and string.strip(comments[0]) == '#':
618 comments[:1] = []
619 while comments and string.strip(comments[-1]) == '#':
620 comments[-1:] = []
621 return string.join(comments, '')
623 class EndOfBlock(Exception): pass
625 class BlockFinder:
626 """Provide a tokeneater() method to detect the end of a code block."""
627 def __init__(self):
628 self.indent = 0
629 self.islambda = False
630 self.started = False
631 self.passline = False
632 self.last = 1
634 def tokeneater(self, type, token, srow_scol, erow_ecol, line):
635 srow, scol = srow_scol
636 erow, ecol = erow_ecol
637 if not self.started:
638 # look for the first "def", "class" or "lambda"
639 if token in ("def", "class", "lambda"):
640 if token == "lambda":
641 self.islambda = True
642 self.started = True
643 self.passline = True # skip to the end of the line
644 elif type == tokenize.NEWLINE:
645 self.passline = False # stop skipping when a NEWLINE is seen
646 self.last = srow
647 if self.islambda: # lambdas always end at the first NEWLINE
648 raise EndOfBlock
649 elif self.passline:
650 pass
651 elif type == tokenize.INDENT:
652 self.indent = self.indent + 1
653 self.passline = True
654 elif type == tokenize.DEDENT:
655 self.indent = self.indent - 1
656 # the end of matching indent/dedent pairs end a block
657 # (note that this only works for "def"/"class" blocks,
658 # not e.g. for "if: else:" or "try: finally:" blocks)
659 if self.indent <= 0:
660 raise EndOfBlock
661 elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL):
662 # any other token on the same indentation level end the previous
663 # block as well, except the pseudo-tokens COMMENT and NL.
664 raise EndOfBlock
666 def getblock(lines):
667 """Extract the block of code at the top of the given list of lines."""
668 blockfinder = BlockFinder()
669 try:
670 tokenize.tokenize(iter(lines).next, blockfinder.tokeneater)
671 except (EndOfBlock, IndentationError):
672 pass
673 return lines[:blockfinder.last]
675 def getsourcelines(object):
676 """Return a list of source lines and starting line number for an object.
678 The argument may be a module, class, method, function, traceback, frame,
679 or code object. The source code is returned as a list of the lines
680 corresponding to the object and the line number indicates where in the
681 original source file the first line of code was found. An IOError is
682 raised if the source code cannot be retrieved."""
683 lines, lnum = findsource(object)
685 if ismodule(object): return lines, 0
686 else: return getblock(lines[lnum:]), lnum + 1
688 def getsource(object):
689 """Return the text of the source code for an object.
691 The argument may be a module, class, method, function, traceback, frame,
692 or code object. The source code is returned as a single string. An
693 IOError is raised if the source code cannot be retrieved."""
694 lines, lnum = getsourcelines(object)
695 return string.join(lines, '')
697 # --------------------------------------------------- class tree extraction
698 def walktree(classes, children, parent):
699 """Recursive helper function for getclasstree()."""
700 results = []
701 classes.sort(key=attrgetter('__module__', '__name__'))
702 for c in classes:
703 results.append((c, c.__bases__))
704 if c in children:
705 results.append(walktree(children[c], children, c))
706 return results
708 def getclasstree(classes, unique=0):
709 """Arrange the given list of classes into a hierarchy of nested lists.
711 Where a nested list appears, it contains classes derived from the class
712 whose entry immediately precedes the list. Each entry is a 2-tuple
713 containing a class and a tuple of its base classes. If the 'unique'
714 argument is true, exactly one entry appears in the returned structure
715 for each class in the given list. Otherwise, classes using multiple
716 inheritance and their descendants will appear multiple times."""
717 children = {}
718 roots = []
719 for c in classes:
720 if c.__bases__:
721 for parent in c.__bases__:
722 if not parent in children:
723 children[parent] = []
724 children[parent].append(c)
725 if unique and parent in classes: break
726 elif c not in roots:
727 roots.append(c)
728 for parent in children:
729 if parent not in classes:
730 roots.append(parent)
731 return walktree(roots, children, None)
733 # ------------------------------------------------ argument list extraction
734 Arguments = namedtuple('Arguments', 'args varargs keywords')
736 def getargs(co):
737 """Get information about the arguments accepted by a code object.
739 Three things are returned: (args, varargs, varkw), where 'args' is
740 a list of argument names (possibly containing nested lists), and
741 'varargs' and 'varkw' are the names of the * and ** arguments or None."""
743 if not iscode(co):
744 raise TypeError('arg is not a code object')
746 nargs = co.co_argcount
747 names = co.co_varnames
748 args = list(names[:nargs])
749 step = 0
751 # The following acrobatics are for anonymous (tuple) arguments.
752 for i in range(nargs):
753 if args[i][:1] in ('', '.'):
754 stack, remain, count = [], [], []
755 while step < len(co.co_code):
756 op = ord(co.co_code[step])
757 step = step + 1
758 if op >= dis.HAVE_ARGUMENT:
759 opname = dis.opname[op]
760 value = ord(co.co_code[step]) + ord(co.co_code[step+1])*256
761 step = step + 2
762 if opname in ('UNPACK_TUPLE', 'UNPACK_SEQUENCE'):
763 remain.append(value)
764 count.append(value)
765 elif opname == 'STORE_FAST':
766 stack.append(names[value])
768 # Special case for sublists of length 1: def foo((bar))
769 # doesn't generate the UNPACK_TUPLE bytecode, so if
770 # `remain` is empty here, we have such a sublist.
771 if not remain:
772 stack[0] = [stack[0]]
773 break
774 else:
775 remain[-1] = remain[-1] - 1
776 while remain[-1] == 0:
777 remain.pop()
778 size = count.pop()
779 stack[-size:] = [stack[-size:]]
780 if not remain: break
781 remain[-1] = remain[-1] - 1
782 if not remain: break
783 args[i] = stack[0]
785 varargs = None
786 if co.co_flags & CO_VARARGS:
787 varargs = co.co_varnames[nargs]
788 nargs = nargs + 1
789 varkw = None
790 if co.co_flags & CO_VARKEYWORDS:
791 varkw = co.co_varnames[nargs]
792 return Arguments(args, varargs, varkw)
794 ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults')
796 def getargspec(func):
797 """Get the names and default values of a function's arguments.
799 A tuple of four things is returned: (args, varargs, varkw, defaults).
800 'args' is a list of the argument names (it may contain nested lists).
801 'varargs' and 'varkw' are the names of the * and ** arguments or None.
802 'defaults' is an n-tuple of the default values of the last n arguments.
805 if ismethod(func):
806 func = func.im_func
807 if not isfunction(func):
808 raise TypeError('arg is not a Python function')
809 args, varargs, varkw = getargs(func.func_code)
810 return ArgSpec(args, varargs, varkw, func.func_defaults)
812 ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals')
814 def getargvalues(frame):
815 """Get information about arguments passed into a particular frame.
817 A tuple of four things is returned: (args, varargs, varkw, locals).
818 'args' is a list of the argument names (it may contain nested lists).
819 'varargs' and 'varkw' are the names of the * and ** arguments or None.
820 'locals' is the locals dictionary of the given frame."""
821 args, varargs, varkw = getargs(frame.f_code)
822 return ArgInfo(args, varargs, varkw, frame.f_locals)
824 def joinseq(seq):
825 if len(seq) == 1:
826 return '(' + seq[0] + ',)'
827 else:
828 return '(' + string.join(seq, ', ') + ')'
830 def strseq(object, convert, join=joinseq):
831 """Recursively walk a sequence, stringifying each element."""
832 if type(object) in (list, tuple):
833 return join(map(lambda o, c=convert, j=join: strseq(o, c, j), object))
834 else:
835 return convert(object)
837 def formatargspec(args, varargs=None, varkw=None, defaults=None,
838 formatarg=str,
839 formatvarargs=lambda name: '*' + name,
840 formatvarkw=lambda name: '**' + name,
841 formatvalue=lambda value: '=' + repr(value),
842 join=joinseq):
843 """Format an argument spec from the 4 values returned by getargspec.
845 The first four arguments are (args, varargs, varkw, defaults). The
846 other four arguments are the corresponding optional formatting functions
847 that are called to turn names and values into strings. The ninth
848 argument is an optional function to format the sequence of arguments."""
849 specs = []
850 if defaults:
851 firstdefault = len(args) - len(defaults)
852 for i in range(len(args)):
853 spec = strseq(args[i], formatarg, join)
854 if defaults and i >= firstdefault:
855 spec = spec + formatvalue(defaults[i - firstdefault])
856 specs.append(spec)
857 if varargs is not None:
858 specs.append(formatvarargs(varargs))
859 if varkw is not None:
860 specs.append(formatvarkw(varkw))
861 return '(' + string.join(specs, ', ') + ')'
863 def formatargvalues(args, varargs, varkw, locals,
864 formatarg=str,
865 formatvarargs=lambda name: '*' + name,
866 formatvarkw=lambda name: '**' + name,
867 formatvalue=lambda value: '=' + repr(value),
868 join=joinseq):
869 """Format an argument spec from the 4 values returned by getargvalues.
871 The first four arguments are (args, varargs, varkw, locals). The
872 next four arguments are the corresponding optional formatting functions
873 that are called to turn names and values into strings. The ninth
874 argument is an optional function to format the sequence of arguments."""
875 def convert(name, locals=locals,
876 formatarg=formatarg, formatvalue=formatvalue):
877 return formatarg(name) + formatvalue(locals[name])
878 specs = []
879 for i in range(len(args)):
880 specs.append(strseq(args[i], convert, join))
881 if varargs:
882 specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
883 if varkw:
884 specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
885 return '(' + string.join(specs, ', ') + ')'
887 # -------------------------------------------------- stack frame extraction
889 Traceback = namedtuple('Traceback', 'filename lineno function code_context index')
891 def getframeinfo(frame, context=1):
892 """Get information about a frame or traceback object.
894 A tuple of five things is returned: the filename, the line number of
895 the current line, the function name, a list of lines of context from
896 the source code, and the index of the current line within that list.
897 The optional second argument specifies the number of lines of context
898 to return, which are centered around the current line."""
899 if istraceback(frame):
900 lineno = frame.tb_lineno
901 frame = frame.tb_frame
902 else:
903 lineno = frame.f_lineno
904 if not isframe(frame):
905 raise TypeError('arg is not a frame or traceback object')
907 filename = getsourcefile(frame) or getfile(frame)
908 if context > 0:
909 start = lineno - 1 - context//2
910 try:
911 lines, lnum = findsource(frame)
912 except IOError:
913 lines = index = None
914 else:
915 start = max(start, 1)
916 start = max(0, min(start, len(lines) - context))
917 lines = lines[start:start+context]
918 index = lineno - 1 - start
919 else:
920 lines = index = None
922 return Traceback(filename, lineno, frame.f_code.co_name, lines, index)
924 def getlineno(frame):
925 """Get the line number from a frame object, allowing for optimization."""
926 # FrameType.f_lineno is now a descriptor that grovels co_lnotab
927 return frame.f_lineno
929 def getouterframes(frame, context=1):
930 """Get a list of records for a frame and all higher (calling) frames.
932 Each record contains a frame object, filename, line number, function
933 name, a list of lines of context, and index within the context."""
934 framelist = []
935 while frame:
936 framelist.append((frame,) + getframeinfo(frame, context))
937 frame = frame.f_back
938 return framelist
940 def getinnerframes(tb, context=1):
941 """Get a list of records for a traceback's frame and all lower frames.
943 Each record contains a frame object, filename, line number, function
944 name, a list of lines of context, and index within the context."""
945 framelist = []
946 while tb:
947 framelist.append((tb.tb_frame,) + getframeinfo(tb, context))
948 tb = tb.tb_next
949 return framelist
951 currentframe = sys._getframe
953 def stack(context=1):
954 """Return a list of records for the stack above the caller's frame."""
955 return getouterframes(sys._getframe(1), context)
957 def trace(context=1):
958 """Return a list of records for the stack below the current exception."""
959 return getinnerframes(sys.exc_info()[2], context)