Catch situations where currentframe() returns None. See SF patch #1447410, this is...
[python.git] / Lib / inspect.py
blob57bf18cd29b8e708ef1c1528cdcbccbc606c0a82
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(), istraceback(),
11 isframe(), iscode(), isbuiltin(), isroutine() - check object types
12 getmembers() - get members of an object that satisfy a given condition
14 getfile(), getsourcefile(), getsource() - find an object's source code
15 getdoc(), getcomments() - get documentation on an object
16 getmodule() - determine the module that an object came from
17 getclasstree() - arrange classes so as to represent their hierarchy
19 getargspec(), getargvalues() - get info about function arguments
20 formatargspec(), formatargvalues() - format an argument spec
21 getouterframes(), getinnerframes() - get info about frames
22 currentframe() - get the current stack frame
23 stack(), trace() - get info about frames on the stack or in a traceback
24 """
26 # This module is in the public domain. No warranties.
28 __author__ = 'Ka-Ping Yee <ping@lfw.org>'
29 __date__ = '1 Jan 2001'
31 import sys, os, types, string, re, dis, imp, tokenize, linecache
32 from operator import attrgetter
34 # ----------------------------------------------------------- type-checking
35 def ismodule(object):
36 """Return true if the object is a module.
38 Module objects provide these attributes:
39 __doc__ documentation string
40 __file__ filename (missing for built-in modules)"""
41 return isinstance(object, types.ModuleType)
43 def isclass(object):
44 """Return true if the object is a class.
46 Class objects provide these attributes:
47 __doc__ documentation string
48 __module__ name of module in which this class was defined"""
49 return isinstance(object, types.ClassType) or hasattr(object, '__bases__')
51 def ismethod(object):
52 """Return true if the object is an instance method.
54 Instance method objects provide these attributes:
55 __doc__ documentation string
56 __name__ name with which this method was defined
57 im_class class object in which this method belongs
58 im_func function object containing implementation of method
59 im_self instance to which this method is bound, or None"""
60 return isinstance(object, types.MethodType)
62 def ismethoddescriptor(object):
63 """Return true if the object is a method descriptor.
65 But not if ismethod() or isclass() or isfunction() are true.
67 This is new in Python 2.2, and, for example, is true of int.__add__.
68 An object passing this test has a __get__ attribute but not a __set__
69 attribute, but beyond that the set of attributes varies. __name__ is
70 usually sensible, and __doc__ often is.
72 Methods implemented via descriptors that also pass one of the other
73 tests return false from the ismethoddescriptor() test, simply because
74 the other tests promise more -- you can, e.g., count on having the
75 im_func attribute (etc) when an object passes ismethod()."""
76 return (hasattr(object, "__get__")
77 and not hasattr(object, "__set__") # else it's a data descriptor
78 and not ismethod(object) # mutual exclusion
79 and not isfunction(object)
80 and not isclass(object))
82 def isdatadescriptor(object):
83 """Return true if the object is a data descriptor.
85 Data descriptors have both a __get__ and a __set__ attribute. Examples are
86 properties (defined in Python) and getsets and members (defined in C).
87 Typically, data descriptors will also have __name__ and __doc__ attributes
88 (properties, getsets, and members have both of these attributes), but this
89 is not guaranteed."""
90 return (hasattr(object, "__set__") and hasattr(object, "__get__"))
92 def isfunction(object):
93 """Return true if the object is a user-defined function.
95 Function objects provide these attributes:
96 __doc__ documentation string
97 __name__ name with which this function was defined
98 func_code code object containing compiled function bytecode
99 func_defaults tuple of any default values for arguments
100 func_doc (same as __doc__)
101 func_globals global namespace in which this function was defined
102 func_name (same as __name__)"""
103 return isinstance(object, types.FunctionType)
105 def istraceback(object):
106 """Return true if the object is a traceback.
108 Traceback objects provide these attributes:
109 tb_frame frame object at this level
110 tb_lasti index of last attempted instruction in bytecode
111 tb_lineno current line number in Python source code
112 tb_next next inner traceback object (called by this level)"""
113 return isinstance(object, types.TracebackType)
115 def isframe(object):
116 """Return true if the object is a frame object.
118 Frame objects provide these attributes:
119 f_back next outer frame object (this frame's caller)
120 f_builtins built-in namespace seen by this frame
121 f_code code object being executed in this frame
122 f_exc_traceback traceback if raised in this frame, or None
123 f_exc_type exception type if raised in this frame, or None
124 f_exc_value exception value if raised in this frame, or None
125 f_globals global namespace seen by this frame
126 f_lasti index of last attempted instruction in bytecode
127 f_lineno current line number in Python source code
128 f_locals local namespace seen by this frame
129 f_restricted 0 or 1 if frame is in restricted execution mode
130 f_trace tracing function for this frame, or None"""
131 return isinstance(object, types.FrameType)
133 def iscode(object):
134 """Return true if the object is a code object.
136 Code objects provide these attributes:
137 co_argcount number of arguments (not including * or ** args)
138 co_code string of raw compiled bytecode
139 co_consts tuple of constants used in the bytecode
140 co_filename name of file in which this code object was created
141 co_firstlineno number of first line in Python source code
142 co_flags bitmap: 1=optimized | 2=newlocals | 4=*arg | 8=**arg
143 co_lnotab encoded mapping of line numbers to bytecode indices
144 co_name name with which this code object was defined
145 co_names tuple of names of local variables
146 co_nlocals number of local variables
147 co_stacksize virtual machine stack space required
148 co_varnames tuple of names of arguments and local variables"""
149 return isinstance(object, types.CodeType)
151 def isbuiltin(object):
152 """Return true if the object is a built-in function or method.
154 Built-in functions and methods provide these attributes:
155 __doc__ documentation string
156 __name__ original name of this function or method
157 __self__ instance to which a method is bound, or None"""
158 return isinstance(object, types.BuiltinFunctionType)
160 def isroutine(object):
161 """Return true if the object is any kind of function or method."""
162 return (isbuiltin(object)
163 or isfunction(object)
164 or ismethod(object)
165 or ismethoddescriptor(object))
167 def getmembers(object, predicate=None):
168 """Return all members of an object as (name, value) pairs sorted by name.
169 Optionally, only return members that satisfy a given predicate."""
170 results = []
171 for key in dir(object):
172 value = getattr(object, key)
173 if not predicate or predicate(value):
174 results.append((key, value))
175 results.sort()
176 return results
178 def classify_class_attrs(cls):
179 """Return list of attribute-descriptor tuples.
181 For each name in dir(cls), the return list contains a 4-tuple
182 with these elements:
184 0. The name (a string).
186 1. The kind of attribute this is, one of these strings:
187 'class method' created via classmethod()
188 'static method' created via staticmethod()
189 'property' created via property()
190 'method' any other flavor of method
191 'data' not a method
193 2. The class which defined this attribute (a class).
195 3. The object as obtained directly from the defining class's
196 __dict__, not via getattr. This is especially important for
197 data attributes: C.data is just a data object, but
198 C.__dict__['data'] may be a data descriptor with additional
199 info, like a __doc__ string.
202 mro = getmro(cls)
203 names = dir(cls)
204 result = []
205 for name in names:
206 # Get the object associated with the name.
207 # Getting an obj from the __dict__ sometimes reveals more than
208 # using getattr. Static and class methods are dramatic examples.
209 if name in cls.__dict__:
210 obj = cls.__dict__[name]
211 else:
212 obj = getattr(cls, name)
214 # Figure out where it was defined.
215 homecls = getattr(obj, "__objclass__", None)
216 if homecls is None:
217 # search the dicts.
218 for base in mro:
219 if name in base.__dict__:
220 homecls = base
221 break
223 # Get the object again, in order to get it from the defining
224 # __dict__ instead of via getattr (if possible).
225 if homecls is not None and name in homecls.__dict__:
226 obj = homecls.__dict__[name]
228 # Also get the object via getattr.
229 obj_via_getattr = getattr(cls, name)
231 # Classify the object.
232 if isinstance(obj, staticmethod):
233 kind = "static method"
234 elif isinstance(obj, classmethod):
235 kind = "class method"
236 elif isinstance(obj, property):
237 kind = "property"
238 elif (ismethod(obj_via_getattr) or
239 ismethoddescriptor(obj_via_getattr)):
240 kind = "method"
241 else:
242 kind = "data"
244 result.append((name, kind, homecls, obj))
246 return result
248 # ----------------------------------------------------------- class helpers
249 def _searchbases(cls, accum):
250 # Simulate the "classic class" search order.
251 if cls in accum:
252 return
253 accum.append(cls)
254 for base in cls.__bases__:
255 _searchbases(base, accum)
257 def getmro(cls):
258 "Return tuple of base classes (including cls) in method resolution order."
259 if hasattr(cls, "__mro__"):
260 return cls.__mro__
261 else:
262 result = []
263 _searchbases(cls, result)
264 return tuple(result)
266 # -------------------------------------------------- source code extraction
267 def indentsize(line):
268 """Return the indent size, in spaces, at the start of a line of text."""
269 expline = string.expandtabs(line)
270 return len(expline) - len(string.lstrip(expline))
272 def getdoc(object):
273 """Get the documentation string for an object.
275 All tabs are expanded to spaces. To clean up docstrings that are
276 indented to line up with blocks of code, any whitespace than can be
277 uniformly removed from the second line onwards is removed."""
278 try:
279 doc = object.__doc__
280 except AttributeError:
281 return None
282 if not isinstance(doc, types.StringTypes):
283 return None
284 try:
285 lines = string.split(string.expandtabs(doc), '\n')
286 except UnicodeError:
287 return None
288 else:
289 # Find minimum indentation of any non-blank lines after first line.
290 margin = sys.maxint
291 for line in lines[1:]:
292 content = len(string.lstrip(line))
293 if content:
294 indent = len(line) - content
295 margin = min(margin, indent)
296 # Remove indentation.
297 if lines:
298 lines[0] = lines[0].lstrip()
299 if margin < sys.maxint:
300 for i in range(1, len(lines)): lines[i] = lines[i][margin:]
301 # Remove any trailing or leading blank lines.
302 while lines and not lines[-1]:
303 lines.pop()
304 while lines and not lines[0]:
305 lines.pop(0)
306 return string.join(lines, '\n')
308 def getfile(object):
309 """Work out which source or compiled file an object was defined in."""
310 if ismodule(object):
311 if hasattr(object, '__file__'):
312 return object.__file__
313 raise TypeError('arg is a built-in module')
314 if isclass(object):
315 object = sys.modules.get(object.__module__)
316 if hasattr(object, '__file__'):
317 return object.__file__
318 raise TypeError('arg is a built-in class')
319 if ismethod(object):
320 object = object.im_func
321 if isfunction(object):
322 object = object.func_code
323 if istraceback(object):
324 object = object.tb_frame
325 if isframe(object):
326 object = object.f_code
327 if iscode(object):
328 return object.co_filename
329 raise TypeError('arg is not a module, class, method, '
330 'function, traceback, frame, or code object')
332 def getmoduleinfo(path):
333 """Get the module name, suffix, mode, and module type for a given file."""
334 filename = os.path.basename(path)
335 suffixes = map(lambda (suffix, mode, mtype):
336 (-len(suffix), suffix, mode, mtype), imp.get_suffixes())
337 suffixes.sort() # try longest suffixes first, in case they overlap
338 for neglen, suffix, mode, mtype in suffixes:
339 if filename[neglen:] == suffix:
340 return filename[:neglen], suffix, mode, mtype
342 def getmodulename(path):
343 """Return the module name for a given file, or None."""
344 info = getmoduleinfo(path)
345 if info: return info[0]
347 def getsourcefile(object):
348 """Return the Python source file an object was defined in, if it exists."""
349 filename = getfile(object)
350 if string.lower(filename[-4:]) in ('.pyc', '.pyo'):
351 filename = filename[:-4] + '.py'
352 for suffix, mode, kind in imp.get_suffixes():
353 if 'b' in mode and string.lower(filename[-len(suffix):]) == suffix:
354 # Looks like a binary file. We want to only return a text file.
355 return None
356 if os.path.exists(filename):
357 return filename
359 def getabsfile(object):
360 """Return an absolute path to the source or compiled file for an object.
362 The idea is for each object to have a unique origin, so this routine
363 normalizes the result as much as possible."""
364 return os.path.normcase(
365 os.path.abspath(getsourcefile(object) or getfile(object)))
367 modulesbyfile = {}
369 def getmodule(object):
370 """Return the module an object was defined in, or None if not found."""
371 if ismodule(object):
372 return object
373 if hasattr(object, '__module__'):
374 return sys.modules.get(object.__module__)
375 try:
376 file = getabsfile(object)
377 except TypeError:
378 return None
379 if file in modulesbyfile:
380 return sys.modules.get(modulesbyfile[file])
381 for module in sys.modules.values():
382 if hasattr(module, '__file__'):
383 modulesbyfile[
384 os.path.realpath(
385 getabsfile(module))] = module.__name__
386 if file in modulesbyfile:
387 return sys.modules.get(modulesbyfile[file])
388 main = sys.modules['__main__']
389 if not hasattr(object, '__name__'):
390 return None
391 if hasattr(main, object.__name__):
392 mainobject = getattr(main, object.__name__)
393 if mainobject is object:
394 return main
395 builtin = sys.modules['__builtin__']
396 if hasattr(builtin, object.__name__):
397 builtinobject = getattr(builtin, object.__name__)
398 if builtinobject is object:
399 return builtin
401 def findsource(object):
402 """Return the entire source file and starting line number for an object.
404 The argument may be a module, class, method, function, traceback, frame,
405 or code object. The source code is returned as a list of all the lines
406 in the file and the line number indexes a line in that list. An IOError
407 is raised if the source code cannot be retrieved."""
408 file = getsourcefile(object) or getfile(object)
409 lines = linecache.getlines(file)
410 if not lines:
411 raise IOError('could not get source code')
413 if ismodule(object):
414 return lines, 0
416 if isclass(object):
417 name = object.__name__
418 pat = re.compile(r'^\s*class\s*' + name + r'\b')
419 for i in range(len(lines)):
420 if pat.match(lines[i]): return lines, i
421 else:
422 raise IOError('could not find class definition')
424 if ismethod(object):
425 object = object.im_func
426 if isfunction(object):
427 object = object.func_code
428 if istraceback(object):
429 object = object.tb_frame
430 if isframe(object):
431 object = object.f_code
432 if iscode(object):
433 if not hasattr(object, 'co_firstlineno'):
434 raise IOError('could not find function definition')
435 lnum = object.co_firstlineno - 1
436 pat = re.compile(r'^(\s*def\s)|(.*(?<!\w)lambda(:|\s))|^(\s*@)')
437 while lnum > 0:
438 if pat.match(lines[lnum]): break
439 lnum = lnum - 1
440 return lines, lnum
441 raise IOError('could not find code object')
443 def getcomments(object):
444 """Get lines of comments immediately preceding an object's source code.
446 Returns None when source can't be found.
448 try:
449 lines, lnum = findsource(object)
450 except (IOError, TypeError):
451 return None
453 if ismodule(object):
454 # Look for a comment block at the top of the file.
455 start = 0
456 if lines and lines[0][:2] == '#!': start = 1
457 while start < len(lines) and string.strip(lines[start]) in ('', '#'):
458 start = start + 1
459 if start < len(lines) and lines[start][:1] == '#':
460 comments = []
461 end = start
462 while end < len(lines) and lines[end][:1] == '#':
463 comments.append(string.expandtabs(lines[end]))
464 end = end + 1
465 return string.join(comments, '')
467 # Look for a preceding block of comments at the same indentation.
468 elif lnum > 0:
469 indent = indentsize(lines[lnum])
470 end = lnum - 1
471 if end >= 0 and string.lstrip(lines[end])[:1] == '#' and \
472 indentsize(lines[end]) == indent:
473 comments = [string.lstrip(string.expandtabs(lines[end]))]
474 if end > 0:
475 end = end - 1
476 comment = string.lstrip(string.expandtabs(lines[end]))
477 while comment[:1] == '#' and indentsize(lines[end]) == indent:
478 comments[:0] = [comment]
479 end = end - 1
480 if end < 0: break
481 comment = string.lstrip(string.expandtabs(lines[end]))
482 while comments and string.strip(comments[0]) == '#':
483 comments[:1] = []
484 while comments and string.strip(comments[-1]) == '#':
485 comments[-1:] = []
486 return string.join(comments, '')
488 class EndOfBlock(Exception): pass
490 class BlockFinder:
491 """Provide a tokeneater() method to detect the end of a code block."""
492 def __init__(self):
493 self.indent = 0
494 self.islambda = False
495 self.started = False
496 self.passline = False
497 self.last = 1
499 def tokeneater(self, type, token, (srow, scol), (erow, ecol), line):
500 if not self.started:
501 # look for the first "def", "class" or "lambda"
502 if token in ("def", "class", "lambda"):
503 if token == "lambda":
504 self.islambda = True
505 self.started = True
506 self.passline = True # skip to the end of the line
507 elif type == tokenize.NEWLINE:
508 self.passline = False # stop skipping when a NEWLINE is seen
509 self.last = srow
510 if self.islambda: # lambdas always end at the first NEWLINE
511 raise EndOfBlock
512 elif self.passline:
513 pass
514 elif type == tokenize.INDENT:
515 self.indent = self.indent + 1
516 self.passline = True
517 elif type == tokenize.DEDENT:
518 self.indent = self.indent - 1
519 # the end of matching indent/dedent pairs end a block
520 # (note that this only works for "def"/"class" blocks,
521 # not e.g. for "if: else:" or "try: finally:" blocks)
522 if self.indent <= 0:
523 raise EndOfBlock
524 elif self.indent == 0 and type not in (tokenize.COMMENT, tokenize.NL):
525 # any other token on the same indentation level end the previous
526 # block as well, except the pseudo-tokens COMMENT and NL.
527 raise EndOfBlock
529 def getblock(lines):
530 """Extract the block of code at the top of the given list of lines."""
531 blockfinder = BlockFinder()
532 try:
533 tokenize.tokenize(iter(lines).next, blockfinder.tokeneater)
534 except (EndOfBlock, IndentationError):
535 pass
536 return lines[:blockfinder.last]
538 def getsourcelines(object):
539 """Return a list of source lines and starting line number for an object.
541 The argument may be a module, class, method, function, traceback, frame,
542 or code object. The source code is returned as a list of the lines
543 corresponding to the object and the line number indicates where in the
544 original source file the first line of code was found. An IOError is
545 raised if the source code cannot be retrieved."""
546 lines, lnum = findsource(object)
548 if ismodule(object): return lines, 0
549 else: return getblock(lines[lnum:]), lnum + 1
551 def getsource(object):
552 """Return the text of the source code for an object.
554 The argument may be a module, class, method, function, traceback, frame,
555 or code object. The source code is returned as a single string. An
556 IOError is raised if the source code cannot be retrieved."""
557 lines, lnum = getsourcelines(object)
558 return string.join(lines, '')
560 # --------------------------------------------------- class tree extraction
561 def walktree(classes, children, parent):
562 """Recursive helper function for getclasstree()."""
563 results = []
564 classes.sort(key=attrgetter('__module__', '__name__'))
565 for c in classes:
566 results.append((c, c.__bases__))
567 if c in children:
568 results.append(walktree(children[c], children, c))
569 return results
571 def getclasstree(classes, unique=0):
572 """Arrange the given list of classes into a hierarchy of nested lists.
574 Where a nested list appears, it contains classes derived from the class
575 whose entry immediately precedes the list. Each entry is a 2-tuple
576 containing a class and a tuple of its base classes. If the 'unique'
577 argument is true, exactly one entry appears in the returned structure
578 for each class in the given list. Otherwise, classes using multiple
579 inheritance and their descendants will appear multiple times."""
580 children = {}
581 roots = []
582 for c in classes:
583 if c.__bases__:
584 for parent in c.__bases__:
585 if not parent in children:
586 children[parent] = []
587 children[parent].append(c)
588 if unique and parent in classes: break
589 elif c not in roots:
590 roots.append(c)
591 for parent in children:
592 if parent not in classes:
593 roots.append(parent)
594 return walktree(roots, children, None)
596 # ------------------------------------------------ argument list extraction
597 # These constants are from Python's compile.h.
598 CO_OPTIMIZED, CO_NEWLOCALS, CO_VARARGS, CO_VARKEYWORDS = 1, 2, 4, 8
600 def getargs(co):
601 """Get information about the arguments accepted by a code object.
603 Three things are returned: (args, varargs, varkw), where 'args' is
604 a list of argument names (possibly containing nested lists), and
605 'varargs' and 'varkw' are the names of the * and ** arguments or None."""
607 if not iscode(co):
608 raise TypeError('arg is not a code object')
610 code = co.co_code
611 nargs = co.co_argcount
612 names = co.co_varnames
613 args = list(names[:nargs])
614 step = 0
616 # The following acrobatics are for anonymous (tuple) arguments.
617 for i in range(nargs):
618 if args[i][:1] in ('', '.'):
619 stack, remain, count = [], [], []
620 while step < len(code):
621 op = ord(code[step])
622 step = step + 1
623 if op >= dis.HAVE_ARGUMENT:
624 opname = dis.opname[op]
625 value = ord(code[step]) + ord(code[step+1])*256
626 step = step + 2
627 if opname in ('UNPACK_TUPLE', 'UNPACK_SEQUENCE'):
628 remain.append(value)
629 count.append(value)
630 elif opname == 'STORE_FAST':
631 stack.append(names[value])
633 # Special case for sublists of length 1: def foo((bar))
634 # doesn't generate the UNPACK_TUPLE bytecode, so if
635 # `remain` is empty here, we have such a sublist.
636 if not remain:
637 stack[0] = [stack[0]]
638 break
639 else:
640 remain[-1] = remain[-1] - 1
641 while remain[-1] == 0:
642 remain.pop()
643 size = count.pop()
644 stack[-size:] = [stack[-size:]]
645 if not remain: break
646 remain[-1] = remain[-1] - 1
647 if not remain: break
648 args[i] = stack[0]
650 varargs = None
651 if co.co_flags & CO_VARARGS:
652 varargs = co.co_varnames[nargs]
653 nargs = nargs + 1
654 varkw = None
655 if co.co_flags & CO_VARKEYWORDS:
656 varkw = co.co_varnames[nargs]
657 return args, varargs, varkw
659 def getargspec(func):
660 """Get the names and default values of a function's arguments.
662 A tuple of four things is returned: (args, varargs, varkw, defaults).
663 'args' is a list of the argument names (it may contain nested lists).
664 'varargs' and 'varkw' are the names of the * and ** arguments or None.
665 'defaults' is an n-tuple of the default values of the last n arguments.
668 if ismethod(func):
669 func = func.im_func
670 if not isfunction(func):
671 raise TypeError('arg is not a Python function')
672 args, varargs, varkw = getargs(func.func_code)
673 return args, varargs, varkw, func.func_defaults
675 def getargvalues(frame):
676 """Get information about arguments passed into a particular frame.
678 A tuple of four things is returned: (args, varargs, varkw, locals).
679 'args' is a list of the argument names (it may contain nested lists).
680 'varargs' and 'varkw' are the names of the * and ** arguments or None.
681 'locals' is the locals dictionary of the given frame."""
682 args, varargs, varkw = getargs(frame.f_code)
683 return args, varargs, varkw, frame.f_locals
685 def joinseq(seq):
686 if len(seq) == 1:
687 return '(' + seq[0] + ',)'
688 else:
689 return '(' + string.join(seq, ', ') + ')'
691 def strseq(object, convert, join=joinseq):
692 """Recursively walk a sequence, stringifying each element."""
693 if type(object) in (list, tuple):
694 return join(map(lambda o, c=convert, j=join: strseq(o, c, j), object))
695 else:
696 return convert(object)
698 def formatargspec(args, varargs=None, varkw=None, defaults=None,
699 formatarg=str,
700 formatvarargs=lambda name: '*' + name,
701 formatvarkw=lambda name: '**' + name,
702 formatvalue=lambda value: '=' + repr(value),
703 join=joinseq):
704 """Format an argument spec from the 4 values returned by getargspec.
706 The first four arguments are (args, varargs, varkw, defaults). The
707 other four arguments are the corresponding optional formatting functions
708 that are called to turn names and values into strings. The ninth
709 argument is an optional function to format the sequence of arguments."""
710 specs = []
711 if defaults:
712 firstdefault = len(args) - len(defaults)
713 for i in range(len(args)):
714 spec = strseq(args[i], formatarg, join)
715 if defaults and i >= firstdefault:
716 spec = spec + formatvalue(defaults[i - firstdefault])
717 specs.append(spec)
718 if varargs is not None:
719 specs.append(formatvarargs(varargs))
720 if varkw is not None:
721 specs.append(formatvarkw(varkw))
722 return '(' + string.join(specs, ', ') + ')'
724 def formatargvalues(args, varargs, varkw, locals,
725 formatarg=str,
726 formatvarargs=lambda name: '*' + name,
727 formatvarkw=lambda name: '**' + name,
728 formatvalue=lambda value: '=' + repr(value),
729 join=joinseq):
730 """Format an argument spec from the 4 values returned by getargvalues.
732 The first four arguments are (args, varargs, varkw, locals). The
733 next four arguments are the corresponding optional formatting functions
734 that are called to turn names and values into strings. The ninth
735 argument is an optional function to format the sequence of arguments."""
736 def convert(name, locals=locals,
737 formatarg=formatarg, formatvalue=formatvalue):
738 return formatarg(name) + formatvalue(locals[name])
739 specs = []
740 for i in range(len(args)):
741 specs.append(strseq(args[i], convert, join))
742 if varargs:
743 specs.append(formatvarargs(varargs) + formatvalue(locals[varargs]))
744 if varkw:
745 specs.append(formatvarkw(varkw) + formatvalue(locals[varkw]))
746 return '(' + string.join(specs, ', ') + ')'
748 # -------------------------------------------------- stack frame extraction
749 def getframeinfo(frame, context=1):
750 """Get information about a frame or traceback object.
752 A tuple of five things is returned: the filename, the line number of
753 the current line, the function name, a list of lines of context from
754 the source code, and the index of the current line within that list.
755 The optional second argument specifies the number of lines of context
756 to return, which are centered around the current line."""
757 if istraceback(frame):
758 lineno = frame.tb_lineno
759 frame = frame.tb_frame
760 else:
761 lineno = frame.f_lineno
762 if not isframe(frame):
763 raise TypeError('arg is not a frame or traceback object')
765 filename = getsourcefile(frame) or getfile(frame)
766 if context > 0:
767 start = lineno - 1 - context//2
768 try:
769 lines, lnum = findsource(frame)
770 except IOError:
771 lines = index = None
772 else:
773 start = max(start, 1)
774 start = max(0, min(start, len(lines) - context))
775 lines = lines[start:start+context]
776 index = lineno - 1 - start
777 else:
778 lines = index = None
780 return (filename, lineno, frame.f_code.co_name, lines, index)
782 def getlineno(frame):
783 """Get the line number from a frame object, allowing for optimization."""
784 # FrameType.f_lineno is now a descriptor that grovels co_lnotab
785 return frame.f_lineno
787 def getouterframes(frame, context=1):
788 """Get a list of records for a frame and all higher (calling) frames.
790 Each record contains a frame object, filename, line number, function
791 name, a list of lines of context, and index within the context."""
792 framelist = []
793 while frame:
794 framelist.append((frame,) + getframeinfo(frame, context))
795 frame = frame.f_back
796 return framelist
798 def getinnerframes(tb, context=1):
799 """Get a list of records for a traceback's frame and all lower frames.
801 Each record contains a frame object, filename, line number, function
802 name, a list of lines of context, and index within the context."""
803 framelist = []
804 while tb:
805 framelist.append((tb.tb_frame,) + getframeinfo(tb, context))
806 tb = tb.tb_next
807 return framelist
809 currentframe = sys._getframe
811 def stack(context=1):
812 """Return a list of records for the stack above the caller's frame."""
813 return getouterframes(sys._getframe(1), context)
815 def trace(context=1):
816 """Return a list of records for the stack below the current exception."""
817 return getinnerframes(sys.exc_info()[2], context)