1 # -*- coding: iso-8859-1 -*- 2 """Get useful information from live Python objects. 3 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. 7 8 Here are some of the useful functions provided by this module: 9 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 14 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 19 20 getargspec(), getargvalues(), getcallargs() - 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 """ 26 27 # This module is in the public domain. No warranties. 28 29 __author__ = 'Ka-Ping Yee <ping (at] lfw.org>' 30 __date__ = '1 Jan 2001' 31 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 43 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 49 50 # ----------------------------------------------------------- type-checking 51 def ismodule(object): 52 """Return true if the object is a module. 53 54 Module objects provide these attributes: 55 __doc__ documentation string 56 __file__ filename (missing for built-in modules)""" 57 return isinstance(object, types.ModuleType) 58 59 def isclass(object): 60 """Return true if the object is a class. 61 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, (type, types.ClassType)) 66 67 def ismethod(object): 68 """Return true if the object is an instance method. 69 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) 77 78 def ismethoddescriptor(object): 79 """Return true if the object is a method descriptor. 80 81 But not if ismethod() or isclass() or isfunction() are true. 82 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. 87 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)) 97 98 def isdatadescriptor(object): 99 """Return true if the object is a data descriptor. 100 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__")) 107 108 if hasattr(types, 'MemberDescriptorType'): 109 # CPython and equivalent 110 def ismemberdescriptor(object): 111 """Return true if the object is a member descriptor. 112 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. 120 121 Member descriptors are specialized descriptors defined in extension 122 modules.""" 123 return False 124 125 if hasattr(types, 'GetSetDescriptorType'): 126 # CPython and equivalent 127 def isgetsetdescriptor(object): 128 """Return true if the object is a getset descriptor. 129 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. 137 138 getset descriptors are specialized descriptors defined in extension 139 modules.""" 140 return False 141 142 def isfunction(object): 143 """Return true if the object is a user-defined function. 144 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) 154 155 def isgeneratorfunction(object): 156 """Return true if the object is a user-defined generator function. 157 158 Generator function objects provides same attributes as functions. 159 160 See help(isfunction) for attributes listing.""" 161 return bool((isfunction(object) or ismethod(object)) and 162 object.func_code.co_flags & CO_GENERATOR) 163 164 def isgenerator(object): 165 """Return true if the object is a generator. 166 167 Generator objects provide these attributes: 168 __iter__ defined to support interation over container 169 close raises a new GeneratorExit exception inside the 170 generator to terminate the iteration 171 gi_code code object 172 gi_frame frame object or possibly None once the generator has 173 been exhausted 174 gi_running set to 1 when generator is executing, 0 otherwise 175 next return the next item from the container 176 send resumes the generator and "sends" a value that becomes 177 the result of the current yield-expression 178 throw used to raise an exception inside the generator""" 179 return isinstance(object, types.GeneratorType) 180 181 def istraceback(object): 182 """Return true if the object is a traceback. 183 184 Traceback objects provide these attributes: 185 tb_frame frame object at this level 186 tb_lasti index of last attempted instruction in bytecode 187 tb_lineno current line number in Python source code 188 tb_next next inner traceback object (called by this level)""" 189 return isinstance(object, types.TracebackType) 190 191 def isframe(object): 192 """Return true if the object is a frame object. 193 194 Frame objects provide these attributes: 195 f_back next outer frame object (this frame's caller) 196 f_builtins built-in namespace seen by this frame 197 f_code code object being executed in this frame 198 f_exc_traceback traceback if raised in this frame, or None 199 f_exc_type exception type if raised in this frame, or None 200 f_exc_value exception value if raised in this frame, or None 201 f_globals global namespace seen by this frame 202 f_lasti index of last attempted instruction in bytecode 203 f_lineno current line number in Python source code 204 f_locals local namespace seen by this frame 205 f_restricted 0 or 1 if frame is in restricted execution mode 206 f_trace tracing function for this frame, or None""" 207 return isinstance(object, types.FrameType) 208 209 def iscode(object): 210 """Return true if the object is a code object. 211 212 Code objects provide these attributes: 213 co_argcount number of arguments (not including * or ** args) 214 co_code string of raw compiled bytecode 215 co_consts tuple of constants used in the bytecode 216 co_filename name of file in which this code object was created 217 co_firstlineno number of first line in Python source code 218 co_flags bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg 219 co_lnotab encoded mapping of line numbers to bytecode indices 220 co_name name with which this code object was defined 221 co_names tuple of names of local variables 222 co_nlocals number of local variables 223 co_stacksize virtual machine stack space required 224 co_varnames tuple of names of arguments and local variables""" 225 return isinstance(object, types.CodeType) 226 227 def isbuiltin(object): 228 """Return true if the object is a built-in function or method. 229 230 Built-in functions and methods provide these attributes: 231 __doc__ documentation string 232 __name__ original name of this function or method 233 __self__ instance to which a method is bound, or None""" 234 return isinstance(object, types.BuiltinFunctionType) 235 236 def isroutine(object): 237 """Return true if the object is any kind of function or method.""" 238 return (isbuiltin(object) 239 or isfunction(object) 240 or ismethod(object) 241 or ismethoddescriptor(object)) 242 243 def isabstract(object): 244 """Return true if the object is an abstract base class (ABC).""" 245 return bool(isinstance(object, type) and object.__flags__ & TPFLAGS_IS_ABSTRACT) 246 247 def getmembers(object, predicate=None): 248 """Return all members of an object as (name, value) pairs sorted by name. 249 Optionally, only return members that satisfy a given predicate.""" 250 results = [] 251 for key in dir(object): 252 try: 253 value = getattr(object, key) 254 except AttributeError: 255 continue 256 if not predicate or predicate(value): 257 results.append((key, value)) 258 results.sort() 259 return results 260 261 Attribute = namedtuple('Attribute', 'name kind defining_class object') 262 263 def classify_class_attrs(cls): 264 """Return list of attribute-descriptor tuples. 265 266 For each name in dir(cls), the return list contains a 4-tuple 267 with these elements: 268 269 0. The name (a string). 270 271 1. The kind of attribute this is, one of these strings: 272 'class method' created via classmethod() 273 'static method' created via staticmethod() 274 'property' created via property() 275 'method' any other flavor of method 276 'data' not a method 277 278 2. The class which defined this attribute (a class). 279 280 3. The object as obtained directly from the defining class's 281 __dict__, not via getattr. This is especially important for 282 data attributes: C.data is just a data object, but 283 C.__dict__['data'] may be a data descriptor with additional 284 info, like a __doc__ string. 285 """ 286 287 mro = getmro(cls) 288 names = dir(cls) 289 result = [] 290 for name in names: 291 # Get the object associated with the name. 292 # Getting an obj from the __dict__ sometimes reveals more than 293 # using getattr. Static and class methods are dramatic examples. 294 if name in cls.__dict__: 295 obj = cls.__dict__[name] 296 else: 297 obj = getattr(cls, name) 298 299 # Figure out where it was defined. 300 homecls = getattr(obj, "__objclass__", None) 301 if homecls is None: 302 # search the dicts. 303 for base in mro: 304 if name in base.__dict__: 305 homecls = base 306 break 307 308 # Get the object again, in order to get it from the defining 309 # __dict__ instead of via getattr (if possible). 310 if homecls is not None and name in homecls.__dict__: 311 obj = homecls.__dict__[name] 312 313 # Also get the object via getattr. 314 obj_via_getattr = getattr(cls, name) 315 316 # Classify the object. 317 if isinstance(obj, staticmethod): 318 kind = "static method" 319 elif isinstance(obj, classmethod): 320 kind = "class method" 321 elif isinstance(obj, property): 322 kind = "property" 323 elif (ismethod(obj_via_getattr) or 324 ismethoddescriptor(obj_via_getattr)): 325 kind = "method" 326 else: 327 kind = "data" 328 329 result.append(Attribute(name, kind, homecls, obj)) 330 331 return result 332 333 # ----------------------------------------------------------- class helpers 334 def _searchbases(cls, accum): 335 # Simulate the "classic class" search order. 336 if cls in accum: 337 return 338 accum.append(cls) 339 for base in cls.__bases__: 340 _searchbases(base, accum) 341 342 def getmro(cls): 343 "Return tuple of base classes (including cls) in method resolution order." 344 if hasattr(cls, "__mro__"): 345 return cls.__mro__ 346 else: 347 result = [] 348 _searchbases(cls, result) 349 return tuple(result) 350 351 # -------------------------------------------------- source code extraction 352 def indentsize(line): 353 """Return the indent size, in spaces, at the start of a line of text.""" 354 expline = string.expandtabs(line) 355 return len(expline) - len(string.lstrip(expline)) 356 357 def getdoc(object): 358 """Get the documentation string for an object. 359 360 All tabs are expanded to spaces. To clean up docstrings that are 361 indented to line up with blocks of code, any whitespace than can be 362 uniformly removed from the second line onwards is removed.""" 363 try: 364 doc = object.__doc__ 365 except AttributeError: 366 return None 367 if not isinstance(doc, types.StringTypes): 368 return None 369 return cleandoc(doc) 370 371 def cleandoc(doc): 372 """Clean up indentation from docstrings. 373 374 Any whitespace that can be uniformly removed from the second line 375 onwards is removed.""" 376 try: 377 lines = string.split(string.expandtabs(doc), '\n') 378 except UnicodeError: 379 return None 380 else: 381 # Find minimum indentation of any non-blank lines after first line. 382 margin = sys.maxint 383 for line in lines[1:]: 384 content = len(string.lstrip(line)) 385 if content: 386 indent = len(line) - content 387 margin = min(margin, indent) 388 # Remove indentation. 389 if lines: 390 lines[0] = lines[0].lstrip() 391 if margin < sys.maxint: 392 for i in range(1, len(lines)): lines[i] = lines[i][margin:] 393 # Remove any trailing or leading blank lines. 394 while lines and not lines[-1]: 395 lines.pop() 396 while lines and not lines[0]: 397 lines.pop(0) 398 return string.join(lines, '\n') 399 400 def getfile(object): 401 """Work out which source or compiled file an object was defined in.""" 402 if ismodule(object): 403 if hasattr(object, '__file__'): 404 return object.__file__ 405 raise TypeError('{!r} is a built-in module'.format(object)) 406 if isclass(object): 407 object = sys.modules.get(object.__module__) 408 if hasattr(object, '__file__'): 409 return object.__file__ 410 raise TypeError('{!r} is a built-in class'.format(object)) 411 if ismethod(object): 412 object = object.im_func 413 if isfunction(object): 414 object = object.func_code 415 if istraceback(object): 416 object = object.tb_frame 417 if isframe(object): 418 object = object.f_code 419 if iscode(object): 420 return object.co_filename 421 raise TypeError('{!r} is not a module, class, method, ' 422 'function, traceback, frame, or code object'.format(object)) 423 424 ModuleInfo = namedtuple('ModuleInfo', 'name suffix mode module_type') 425 426 def getmoduleinfo(path): 427 """Get the module name, suffix, mode, and module type for a given file.""" 428 filename = os.path.basename(path) 429 suffixes = map(lambda info: 430 (-len(info[0]), info[0], info[1], info[2]), 431 imp.get_suffixes()) 432 suffixes.sort() # try longest suffixes first, in case they overlap 433 for neglen, suffix, mode, mtype in suffixes: 434 if filename[neglen:] == suffix: 435 return ModuleInfo(filename[:neglen], suffix, mode, mtype) 436 437 def getmodulename(path): 438 """Return the module name for a given file, or None.""" 439 info = getmoduleinfo(path) 440 if info: return info[0] 441 442 def getsourcefile(object): 443 """Return the filename that can be used to locate an object's source. 444 Return None if no way can be identified to get the source. 445 """ 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 458 # or it is in the linecache 459 if filename in linecache.cache: 460 return filename 461 462 def getabsfile(object, _filename=None): 463 """Return an absolute path to the source or compiled file for an object. 464 465 The idea is for each object to have a unique origin, so this routine 466 normalizes the result as much as possible.""" 467 if _filename is None: 468 _filename = getsourcefile(object) or getfile(object) 469 return os.path.normcase(os.path.abspath(_filename)) 470 471 modulesbyfile = {} 472 _filesbymodname = {} 473 474 def getmodule(object, _filename=None): 475 """Return the module an object was defined in, or None if not found.""" 476 if ismodule(object): 477 return object 478 if hasattr(object, '__module__'): 479 return sys.modules.get(object.__module__) 480 # Try the filename to modulename cache 481 if _filename is not None and _filename in modulesbyfile: 482 return sys.modules.get(modulesbyfile[_filename]) 483 # Try the cache again with the absolute file name 484 try: 485 file = getabsfile(object, _filename) 486 except TypeError: 487 return None 488 if file in modulesbyfile: 489 return sys.modules.get(modulesbyfile[file]) 490 # Update the filename to module name cache and check yet again 491 # Copy sys.modules in order to cope with changes while iterating 492 for modname, module in sys.modules.items(): 493 if ismodule(module) and hasattr(module, '__file__'): 494 f = module.__file__ 495 if f == _filesbymodname.get(modname, None): 496 # Have already mapped this module, so skip it 497 continue 498 _filesbymodname[modname] = f 499 f = getabsfile(module) 500 # Always map to the name the module knows itself by 501 modulesbyfile[f] = modulesbyfile[ 502 os.path.realpath(f)] = module.__name__ 503 if file in modulesbyfile: 504 return sys.modules.get(modulesbyfile[file]) 505 # Check the main module 506 main = sys.modules['__main__'] 507 if not hasattr(object, '__name__'): 508 return None 509 if hasattr(main, object.__name__): 510 mainobject = getattr(main, object.__name__) 511 if mainobject is object: 512 return main 513 # Check builtins 514 builtin = sys.modules['__builtin__'] 515 if hasattr(builtin, object.__name__): 516 builtinobject = getattr(builtin, object.__name__) 517 if builtinobject is object: 518 return builtin 519 520 def findsource(object): 521 """Return the entire source file and starting line number for an object. 522 523 The argument may be a module, class, method, function, traceback, frame, 524 or code object. The source code is returned as a list of all the lines 525 in the file and the line number indexes a line in that list. An IOError 526 is raised if the source code cannot be retrieved.""" 527 file = getsourcefile(object) 528 if not file: 529 raise IOError('source code not available') 530 module = getmodule(object, file) 531 if module: 532 lines = linecache.getlines(file, module.__dict__) 533 else: 534 lines = linecache.getlines(file) 535 if not lines: 536 raise IOError('could not get source code') 537 538 if ismodule(object): 539 return lines, 0 540 541 if isclass(object): 542 name = object.__name__ 543 pat = re.compile(r'^(\s*)class\s*' + name + r'\b') 544 # make some effort to find the best matching class definition: 545 # use the one with the least indentation, which is the one 546 # that's most probably not inside a function definition. 547 candidates = [] 548 for i in range(len(lines)): 549 match = pat.match(lines[i]) 550 if match: 551 # if it's at toplevel, it's already the best one 552 if lines[i][0] == 'c': 553 return lines, i 554 # else add whitespace to candidate list 555 candidates.append((match.group(1), i)) 556 if candidates: 557 # this will sort by whitespace, and by line number, 558 # less whitespace first 559 candidates.sort() 560 return lines, candidates[0][1] 561 else: 562 raise IOError('could not find class definition') 563 564 if ismethod(object): 565 object = object.im_func 566 if isfunction(object): 567 object = object.func_code 568 if istraceback(object): 569 object = object.tb_frame 570 if isframe(object): 571 object = object.f_code 572 if iscode(object): 573 if not hasattr(object, 'co_firstlineno'): 574 raise IOError('could not find function definition') 575 lnum = object.co_firstlineno - 1 576 pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)') 577 while lnum > 0: 578 if pat.match(lines[lnum]): break 579 lnum = lnum - 1 580 return lines, lnum 581 raise IOError('could not find code object') 582 583 def getcomments(object): 584 """Get lines of comments immediately preceding an object's source code. 585 586 Returns None when source can't be found. 587 """ 588 try: 589 lines, lnum = findsource(object) 590 except (IOError, TypeError): 591 return None 592 593 if ismodule(object): 594 # Look for a comment block at the top of the file. 595 start = 0 596 if lines and lines[0][:2] == '#!': start = 1 597 while start < len(lines) and string.strip(lines[start]) in ('', '#'): 598 start = start + 1 599 if start < len(lines) and lines[start][:1] == '#': 600 comments = [] 601 end = start 602 while end < len(lines) and lines[end][:1] == '#': 603 comments.append(string.expandtabs(lines[end])) 604 end = end + 1 605 return string.join(comments, '') 606 607 # Look for a preceding block of comments at the same indentation. 608 elif lnum > 0: 609 indent = indentsize(lines[lnum]) 610 end = lnum - 1 611 if end >= 0 and string.lstrip(lines[end])[:1] == '#' and \ 612 indentsize(lines[end]) == indent: 613 comments = [string.lstrip(string.expandtabs(lines[end]))] 614 if end > 0: 615 end = end - 1 616 comment = string.lstrip(string.expandtabs(lines[end])) 617 while comment[:1] == '#' and indentsize(lines[end]) == indent: 618 comments[:0] = [comment] 619 end = end - 1 620 if end < 0: break 621 comment = string.lstrip(string.expandtabs(lines[end])) 622 while comments and string.strip(comments[0]) == '#': 623 comments[:1] = [] 624 while comments and string.strip(comments[-1]) == '#': 625 comments[-1:] = [] 626 return string.join(comments, '') 627 628 class EndOfBlock(Exception): pass 629 630 class BlockFinder: 631 """Provide a tokeneater() method to detect the end of a code block.""" 632 def __init__(self): 633 self.indent = 0 634 self.islambda = False 635 self.started = False 636 self.passline = False 637 self.last = 1 638 639 def tokeneater(self, type, token, srow_scol, erow_ecol, line): 640 srow, scol = srow_scol 641 erow, ecol = erow_ecol 642 if not self.started: 643 # look for the first "def", "class" or "lambda" 644 if token in ("def", "class", "lambda"): 645 if token == "lambda": 646 self.islambda = True 647 self.started = True 648 self.passline = True # skip to the end of the line 649 elif type == tokenize.NEWLINE: 650 self.passline = False # stop skipping when a NEWLINE is seen 651 self.last = srow 652 if self.islambda: # lambdas always end at the first NEWLINE 653 raise EndOfBlock 654 elif self.passline: 655 pass 656 elif type == tokenize.INDENT: 657 self.indent = self.indent + 1 658 self.passline = True 659 elif type == tokenize.DEDENT: 660 self.indent = self.indent - 1 661 # the end of matching indent/dedent pairs end a block 662 # (note that this only works for "def"/"class" blocks, 663 # not e.g. for "if: else:" or "try: finally:" blocks) 664 if self.indent <= 0: 665 raise EndOfBlock 666 elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL): 667 # any other token on the same indentation level end the previous 668 # block as well, except the pseudo-tokens COMMENT and NL. 669 raise EndOfBlock 670 671 def getblock(lines): 672 """Extract the block of code at the top of the given list of lines.""" 673 blockfinder = BlockFinder() 674 try: 675 tokenize.tokenize(iter(lines).next, blockfinder.tokeneater) 676 except (EndOfBlock, IndentationError): 677 pass 678 return lines[:blockfinder.last] 679 680 def getsourcelines(object): 681 """Return a list of source lines and starting line number for an object. 682 683 The argument may be a module, class, method, function, traceback, frame, 684 or code object. The source code is returned as a list of the lines 685 corresponding to the object and the line number indicates where in the 686 original source file the first line of code was found. An IOError is 687 raised if the source code cannot be retrieved.""" 688 lines, lnum = findsource(object) 689 690 if ismodule(object): return lines, 0 691 else: return getblock(lines[lnum:]), lnum + 1 692 693 def getsource(object): 694 """Return the text of the source code for an object. 695 696 The argument may be a module, class, method, function, traceback, frame, 697 or code object. The source code is returned as a single string. An 698 IOError is raised if the source code cannot be retrieved.""" 699 lines, lnum = getsourcelines(object) 700 return string.join(lines, '') 701 702 # --------------------------------------------------- class tree extraction 703 def walktree(classes, children, parent): 704 """Recursive helper function for getclasstree().""" 705 results = [] 706 classes.sort(key=attrgetter('__module__', '__name__')) 707 for c in classes: 708 results.append((c, c.__bases__)) 709 if c in children: 710 results.append(walktree(children[c], children, c)) 711 return results 712 713 def getclasstree(classes, unique=0): 714 """Arrange the given list of classes into a hierarchy of nested lists. 715 716 Where a nested list appears, it contains classes derived from the class 717 whose entry immediately precedes the list. Each entry is a 2-tuple 718 containing a class and a tuple of its base classes. If the 'unique' 719 argument is true, exactly one entry appears in the returned structure 720 for each class in the given list. Otherwise, classes using multiple 721 inheritance and their descendants will appear multiple times.""" 722 children = {} 723 roots = [] 724 for c in classes: 725 if c.__bases__: 726 for parent in c.__bases__: 727 if not parent in children: 728 children[parent] = [] 729 children[parent].append(c) 730 if unique and parent in classes: break 731 elif c not in roots: 732 roots.append(c) 733 for parent in children: 734 if parent not in classes: 735 roots.append(parent) 736 return walktree(roots, children, None) 737 738 # ------------------------------------------------ argument list extraction 739 Arguments = namedtuple('Arguments', 'args varargs keywords') 740 741 def getargs(co): 742 """Get information about the arguments accepted by a code object. 743 744 Three things are returned: (args, varargs, varkw), where 'args' is 745 a list of argument names (possibly containing nested lists), and 746 'varargs' and 'varkw' are the names of the * and ** arguments or None.""" 747 748 if not iscode(co): 749 raise TypeError('{!r} is not a code object'.format(co)) 750 751 nargs = co.co_argcount 752 names = co.co_varnames 753 args = list(names[:nargs]) 754 step = 0 755 756 # The following acrobatics are for anonymous (tuple) arguments. 757 for i in range(nargs): 758 if args[i][:1] in ('', '.'): 759 stack, remain, count = [], [], [] 760 while step < len(co.co_code): 761 op = ord(co.co_code[step]) 762 step = step + 1 763 if op >= dis.HAVE_ARGUMENT: 764 opname = dis.opname[op] 765 value = ord(co.co_code[step]) + ord(co.co_code[step+1])*256 766 step = step + 2 767 if opname in ('UNPACK_TUPLE', 'UNPACK_SEQUENCE'): 768 remain.append(value) 769 count.append(value) 770 elif opname == 'STORE_FAST': 771 stack.append(names[value]) 772 773 # Special case for sublists of length 1: def foo((bar)) 774 # doesn't generate the UNPACK_TUPLE bytecode, so if 775 # `remain` is empty here, we have such a sublist. 776 if not remain: 777 stack[0] = [stack[0]] 778 break 779 else: 780 remain[-1] = remain[-1] - 1 781 while remain[-1] == 0: 782 remain.pop() 783 size = count.pop() 784 stack[-size:] = [stack[-size:]] 785 if not remain: break 786 remain[-1] = remain[-1] - 1 787 if not remain: break 788 args[i] = stack[0] 789 790 varargs = None 791 if co.co_flags & CO_VARARGS: 792 varargs = co.co_varnames[nargs] 793 nargs = nargs + 1 794 varkw = None 795 if co.co_flags & CO_VARKEYWORDS: 796 varkw = co.co_varnames[nargs] 797 return Arguments(args, varargs, varkw) 798 799 ArgSpec = namedtuple('ArgSpec', 'args varargs keywords defaults') 800 801 def getargspec(func): 802 """Get the names and default values of a function's arguments. 803 804 A tuple of four things is returned: (args, varargs, varkw, defaults). 805 'args' is a list of the argument names (it may contain nested lists). 806 'varargs' and 'varkw' are the names of the * and ** arguments or None. 807 'defaults' is an n-tuple of the default values of the last n arguments. 808 """ 809 810 if ismethod(func): 811 func = func.im_func 812 if not isfunction(func): 813 raise TypeError('{!r} is not a Python function'.format(func)) 814 args, varargs, varkw = getargs(func.func_code) 815 return ArgSpec(args, varargs, varkw, func.func_defaults) 816 817 ArgInfo = namedtuple('ArgInfo', 'args varargs keywords locals') 818 819 def getargvalues(frame): 820 """Get information about arguments passed into a particular frame. 821 822 A tuple of four things is returned: (args, varargs, varkw, locals). 823 'args' is a list of the argument names (it may contain nested lists). 824 'varargs' and 'varkw' are the names of the * and ** arguments or None. 825 'locals' is the locals dictionary of the given frame.""" 826 args, varargs, varkw = getargs(frame.f_code) 827 return ArgInfo(args, varargs, varkw, frame.f_locals) 828 829 def joinseq(seq): 830 if len(seq) == 1: 831 return '(' + seq[0] + ',)' 832 else: 833 return '(' + string.join(seq, ', ') + ')' 834 835 def strseq(object, convert, join=joinseq): 836 """Recursively walk a sequence, stringifying each element.""" 837 if type(object) in (list, tuple): 838 return join(map(lambda o, c=convert, j=join: strseq(o, c, j), object)) 839 else: 840 return convert(object) 841 842 def formatargspec(args, varargs=None, varkw=None, defaults=None, 843 formatarg=str, 844 formatvarargs=lambda name: '*' + name, 845 formatvarkw=lambda name: '**' + name, 846 formatvalue=lambda value: '=' + repr(value), 847 join=joinseq): 848 """Format an argument spec from the 4 values returned by getargspec. 849 850 The first four arguments are (args, varargs, varkw, defaults). The 851 other four arguments are the corresponding optional formatting functions 852 that are called to turn names and values into strings. The ninth 853 argument is an optional function to format the sequence of arguments.""" 854 specs = [] 855 if defaults: 856 firstdefault = len(args) - len(defaults) 857 for i, arg in enumerate(args): 858 spec = strseq(arg, formatarg, join) 859 if defaults and i >= firstdefault: 860 spec = spec + formatvalue(defaults[i - firstdefault]) 861 specs.append(spec) 862 if varargs is not None: 863 specs.append(formatvarargs(varargs)) 864 if varkw is not None: 865 specs.append(formatvarkw(varkw)) 866 return '(' + string.join(specs, ', ') + ')' 867 868 def formatargvalues(args, varargs, varkw, locals, 869 formatarg=str, 870 formatvarargs=lambda name: '*' + name, 871 formatvarkw=lambda name: '**' + name, 872 formatvalue=lambda value: '=' + repr(value), 873 join=joinseq): 874 """Format an argument spec from the 4 values returned by getargvalues. 875 876 The first four arguments are (args, varargs, varkw, locals). The 877 next four arguments are the corresponding optional formatting functions 878 that are called to turn names and values into strings. The ninth 879 argument is an optional function to format the sequence of arguments.""" 880 def convert(name, locals=locals, 881 formatarg=formatarg, formatvalue=formatvalue): 882 return formatarg(name) + formatvalue(locals[name]) 883 specs = [] 884 for i in range(len(args)): 885 specs.append(strseq(args[i], convert, join)) 886 if varargs: 887 specs.append(formatvarargs(varargs) + formatvalue(locals[varargs])) 888 if varkw: 889 specs.append(formatvarkw(varkw) + formatvalue(locals[varkw])) 890 return '(' + string.join(specs, ', ') + ')' 891 892 def getcallargs(func, *positional, **named): 893 """Get the mapping of arguments to values. 894 895 A dict is returned, with keys the function argument names (including the 896 names of the * and ** arguments, if any), and values the respective bound 897 values from 'positional' and 'named'.""" 898 args, varargs, varkw, defaults = getargspec(func) 899 f_name = func.__name__ 900 arg2value = {} 901 902 # The following closures are basically because of tuple parameter unpacking. 903 assigned_tuple_params = [] 904 def assign(arg, value): 905 if isinstance(arg, str): 906 arg2value[arg] = value 907 else: 908 assigned_tuple_params.append(arg) 909 value = iter(value) 910 for i, subarg in enumerate(arg): 911 try: 912 subvalue = next(value) 913 except StopIteration: 914 raise ValueError('need more than %d %s to unpack' % 915 (i, 'values' if i > 1 else 'value')) 916 assign(subarg,subvalue) 917 try: 918 next(value) 919 except StopIteration: 920 pass 921 else: 922 raise ValueError('too many values to unpack') 923 def is_assigned(arg): 924 if isinstance(arg,str): 925 return arg in arg2value 926 return arg in assigned_tuple_params 927 if ismethod(func) and func.im_self is not None: 928 # implicit 'self' (or 'cls' for classmethods) argument 929 positional = (func.im_self,) + positional 930 num_pos = len(positional) 931 num_total = num_pos + len(named) 932 num_args = len(args) 933 num_defaults = len(defaults) if defaults else 0 934 for arg, value in zip(args, positional): 935 assign(arg, value) 936 if varargs: 937 if num_pos > num_args: 938 assign(varargs, positional[-(num_pos-num_args):]) 939 else: 940 assign(varargs, ()) 941 elif 0 < num_args < num_pos: 942 raise TypeError('%s() takes %s %d %s (%d given)' % ( 943 f_name, 'at most' if defaults else 'exactly', num_args, 944 'arguments' if num_args > 1 else 'argument', num_total)) 945 elif num_args == 0 and num_total: 946 if varkw: 947 if num_pos: 948 # XXX: We should use num_pos, but Python also uses num_total: 949 raise TypeError('%s() takes exactly 0 arguments ' 950 '(%d given)' % (f_name, num_total)) 951 else: 952 raise TypeError('%s() takes no arguments (%d given)' % 953 (f_name, num_total)) 954 for arg in args: 955 if isinstance(arg, str) and arg in named: 956 if is_assigned(arg): 957 raise TypeError("%s() got multiple values for keyword " 958 "argument '%s'" % (f_name, arg)) 959 else: 960 assign(arg, named.pop(arg)) 961 if defaults: # fill in any missing values with the defaults 962 for arg, value in zip(args[-num_defaults:], defaults): 963 if not is_assigned(arg): 964 assign(arg, value) 965 if varkw: 966 assign(varkw, named) 967 elif named: 968 unexpected = next(iter(named)) 969 if isinstance(unexpected, unicode): 970 unexpected = unexpected.encode(sys.getdefaultencoding(), 'replace') 971 raise TypeError("%s() got an unexpected keyword argument '%s'" % 972 (f_name, unexpected)) 973 unassigned = num_args - len([arg for arg in args if is_assigned(arg)]) 974 if unassigned: 975 num_required = num_args - num_defaults 976 raise TypeError('%s() takes %s %d %s (%d given)' % ( 977 f_name, 'at least' if defaults else 'exactly', num_required, 978 'arguments' if num_required > 1 else 'argument', num_total)) 979 return arg2value 980 981 # -------------------------------------------------- stack frame extraction 982 983 Traceback = namedtuple('Traceback', 'filename lineno function code_context index') 984 985 def getframeinfo(frame, context=1): 986 """Get information about a frame or traceback object. 987 988 A tuple of five things is returned: the filename, the line number of 989 the current line, the function name, a list of lines of context from 990 the source code, and the index of the current line within that list. 991 The optional second argument specifies the number of lines of context 992 to return, which are centered around the current line.""" 993 if istraceback(frame): 994 lineno = frame.tb_lineno 995 frame = frame.tb_frame 996 else: 997 lineno = frame.f_lineno 998 if not isframe(frame): 999 raise TypeError('{!r} is not a frame or traceback object'.format(frame)) 1000 1001 filename = getsourcefile(frame) or getfile(frame) 1002 if context > 0: 1003 start = lineno - 1 - context//2 1004 try: 1005 lines, lnum = findsource(frame) 1006 except IOError: 1007 lines = index = None 1008 else: 1009 start = max(start, 1) 1010 start = max(0, min(start, len(lines) - context)) 1011 lines = lines[start:start+context] 1012 index = lineno - 1 - start 1013 else: 1014 lines = index = None 1015 1016 return Traceback(filename, lineno, frame.f_code.co_name, lines, index) 1017 1018 def getlineno(frame): 1019 """Get the line number from a frame object, allowing for optimization.""" 1020 # FrameType.f_lineno is now a descriptor that grovels co_lnotab 1021 return frame.f_lineno 1022 1023 def getouterframes(frame, context=1): 1024 """Get a list of records for a frame and all higher (calling) frames. 1025 1026 Each record contains a frame object, filename, line number, function 1027 name, a list of lines of context, and index within the context.""" 1028 framelist = [] 1029 while frame: 1030 framelist.append((frame,) + getframeinfo(frame, context)) 1031 frame = frame.f_back 1032 return framelist 1033 1034 def getinnerframes(tb, context=1): 1035 """Get a list of records for a traceback's frame and all lower frames. 1036 1037 Each record contains a frame object, filename, line number, function 1038 name, a list of lines of context, and index within the context.""" 1039 framelist = [] 1040 while tb: 1041 framelist.append((tb.tb_frame,) + getframeinfo(tb, context)) 1042 tb = tb.tb_next 1043 return framelist 1044 1045 if hasattr(sys, '_getframe'): 1046 currentframe = sys._getframe 1047 else: 1048 currentframe = lambda _=None: None 1049 1050 def stack(context=1): 1051 """Return a list of records for the stack above the caller's frame.""" 1052 return getouterframes(sys._getframe(1), context) 1053 1054 def trace(context=1): 1055 """Return a list of records for the stack below the current exception.""" 1056 return getinnerframes(sys.exc_info()[2], context) 1057
