Almost complete rewritten. Documentation added.

Simple interface "pdb.run('<statement>')" added.

Lib/pdb.py

@@ -1,16 +1,157 @@
 # pdb.py -- finally, a Python debugger!
 
-# To do:
+# To use the debugger in its simplest form:
-# - Keep a list of exceptions trapped (default only KeyboardInterrupt?)
+#	>>> import pdb
-# - A blank line should repeat the previous command, not execute 'next'
+#	>>> pdb.run('<a statement>')
-# - Don't line-trace functions (or at least files) without breakpoints
+# The debugger's prompt is '(Pdb) '.
-# - Better handling of call/return events
+# This will stop in the first function call in <a statement>.
-# - It should be possible to intercept KeyboardInterrupt completely
+
-# - Where and when to stop exactly when 'next' encounters a return?
+# The commands recognized by the debugger are listed below.
-#   (should be level-based -- don't trace anything deeper than current)
+# Most can be abbreviated as indicated; e.g., h(elp) means that
-# - Show stack traces upside-down (like dbx/gdb)
+# 'help' can be typed as 'h' or 'help'
-# - When stopping on an exception, show traceback stack
+# (but not as 'he' or 'hel', nor as 'H' or 'Help' or 'HELP').
-# - Merge with tb (for post-mortem usage)
+# Optional arguments are enclosed in square brackets.
+
+# A blank line repeats the previous command literally.
+# (Except for 'list', where it lists the next 11 lines.)
+
+# Commands that the debugger does not recognized are assumed to
+# be Python statements and are executed in the context of the
+# program being debugged.
+# Python statements can also be prefixed with an exclamation point ('!').
+# This is a powerful way to inspect the program being debugged;
+# it is even possible to change variables.
+# When an exception occurs in such a statement, the exception name
+# is printed but the debugger's state is not changed.
+
+# The debugger is not directly programmable; but it is implemented
+# as a class from which you can derive your own debugger class,
+# so you can make as fancy as you like.
+
+# The debugger's commands are:
+
+# h(elp)
+#	Without argument, print the list of available commands.
+#	With a command name as argument, print help about that command
+#	(this is currently not implemented).
+
+# w(here)
+#	Print a stack trace, with the most recent frame at the bottom.
+#	An arrow indicates the "current frame", which determines the
+#	context of most commands.
+
+# d(own)
+#	Move the current frame one level down in the stack trace
+#	(to an older frame).
+
+# u(p)
+#	Move the current frame one level up in the stack trace
+#	(to a newer frame).
+
+# b(reak) [lineno]
+#	With a line number argument, set a break there in the current file.
+#	Without argument, list all breaks.
+
+# cl(ear) [lineno]
+#	With a line number argument, clear that break in the current file.
+#	Without argument, clear all breaks (but first ask confirmation).
+
+# s(tep)
+#	Execute the current line, stop at the first possible occasion
+#	(either in a function that is called or in the current function).
+
+# n(ext)
+#	Continue execution until the next line in the current function
+#	is reached or it returns.
+
+# r(eturn)
+#	Continue execution until the current function returns.
+
+# c(ont(inue))
+#	Continue execution, only stop when a breakpoint is encountered.
+
+# l(ist) [first [,last]]
+#	List source code for the current file.
+#	Without arguments, list 11 lines around the current line
+#	or continue the previous listing.
+#	With one argument, list 11 lines starting at that line.
+#	With two arguments, list the given range;
+#	if the second argument is less than the first, it is a count.
+
+# a(rgs)
+#	Print the argument list of the current function.
+
+# p expression
+#	Print the value of the expression.
+
+# (!) statement
+#	Execute the (one-line) statement in the context of
+#	the current stack frame.
+#	The exclamation point can be omitted unless the first word
+#	of the statement resembles a debugger command.
+#	To assign to a global variable you must always prefix the
+#	command with a 'global' command, e.g.:
+#	(Pdb) global list_options; list_options = ['-l']
+#	(Pdb)
+
+# q(uit)
+#	Quit from the debugger.
+#	The program being executed is aborted.
+
+
+# Here's how it works.
+
+# Some changes were made to the interpreter:
+# - if sys.trace is defined (by the user), it should be a function
+# - sys.trace is called the global trace function
+# - there can also a local trace function (see later)
+
+# Trace functions have three arguments: (frame, event, arg)
+#   - frame is the current stack frame
+#   - event is a string: 'call', 'line', 'return' or 'exception'
+#   - arg is dependent on the event type
+# A trace function should return a new trace function or None.
+# Class methods are accepted (and most useful!) as trace methods.
+
+# The events have the following meaning:
+#
+#   'call':      A function is called (or some other code block entered).
+#                The global trace function is called;
+#                arg is the argument list to the function;
+#                the return value specifies the local trace function.
+#
+#   'line':      The interpreter is about to execute a new line of code
+#                (sometimes multiple line events on one line exist).
+#                The local trace function is called; arg in None;
+#                the return value specifies the new local trace function.
+#
+#   'return':    A function (or other code block) is about to return.
+#                The local trace function is called;
+#                arg is the value that will be returned.
+#                The trace function's return value is ignored.
+#
+#   'exception': An exception has occurred.
+#                The local trace function is called if there is one,
+#                else the global trace function is called;
+#                arg is a triple (exception, value, traceback);
+#                the return value specifies the new local trace function
+#
+# Note that as an exception is propagated down the chain of callers,
+# an 'exception' event is generated at each level.
+
+# A stack frame object has the following read-only attributes:
+#   f_code:      the code object being executed
+#   f_lineno:    the current line number (-1 for 'call' events)
+#   f_back:      the stack frame of the caller, or None
+#   f_locals:    dictionary containing local name bindings
+#   f_globals:   dictionary containing global name bindings
+
+# A code object has the following read-only attributes:
+#   co_code:     the code string
+#   co_names:    the list of names used by the code
+#   co_consts:   the list of (literal) constants used by the code
+#   co_filename: the filename from which the code was compiled
+
 
 import string
 import sys
@@ -26,31 +167,35 @@ class Cmd:
 	def init(self):
 		self.prompt = PROMPT
 		self.identchars = IDENTCHARS
+		self.lastcmd = ''
 		return self
-	def commandloop(self):
+	def cmdloop(self):
-		try:
+		stop = None
-			self.innerloop()
+		while not stop:
-		except EOFError:
+			try:
-			pass
+				line = raw_input(self.prompt)
-	def innerloop(self):
+			except EOFError:
-		while 1:
+				line = 'EOF'
-			line = string.strip(self.getline())
+			stop = self.onecmd(line)
-			self.execline(line)
+		return stop
-	def execline(self, line):
+	def onecmd(self, line):
+		line = string.strip(line)
+		if not line:
+			line = self.lastcmd
+			print line
+		else:
+			self.lastcmd = line
 		i, n = 0, len(line)
 		while i < n and line[i] in self.identchars: i = i+1
 		cmd, arg = line[:i], string.strip(line[i:])
 		if cmd == '':
-			self.default(line)
+			return self.default(line)
 		else:
 			try:
 				func = eval('self.do_' + cmd)
 			except AttributeError:
-				self.default(line)
+				return self.default(line)
-				return
+			return func(arg)
-			func(arg)
-	def getline(self):
-		return raw_input(self.prompt)
 	def default(self, line):
 		print '*** Unknown syntax:', line
 	def do_help(self, arg):
@@ -74,8 +219,7 @@ class Cmd:
 
 # A specialization of Cmd for use by the debugger
 
-PdbDone = 'PdbDone' # Exception used internally
+PdbQuit = 'pdb.PdbQuit' # Exception to give up
-PdbQuit = 'PdbQuit' # Exception to just give up
 
 class Pdb(Cmd):
 	
@@ -83,32 +227,32 @@ class Pdb(Cmd):
 		self = Cmd.init(self)
 		self.prompt = '(Pdb) '
 		self.reset()
-		self.breaks = {}
 		return self
 	
 	def reset(self):
-		self.whatnext = ''
+		self.breaks = {}
 		self.botframe = None
+		self.stopframe = None
 		self.forget()
 	
 	def forget(self):
-		self.curframe = self.topframe = None
+		self.setup(None)
-		self.stack = []
-		self.lineno = None
 	
 	def setup(self, frame):
 		self.curframe = self.topframe = frame
 		self.stack = []
 		self.lineno = None
-		self.stopframe = None
-		self.whatnext = ''
 	
 	def run(self, cmd):
-		if cmd[-1:] != '\n': cmd = cmd + '\n'
+		import __main__
+		dict = __main__.__dict__
+		self.runctx(cmd, dict, dict)
+	
+	def runctx(self, cmd, globals, locals):
 		self.reset()
 		sys.trace = self.dispatch
 		try:
-			exec(cmd)
+			exec(cmd + '\n', globals, locals)
 		except PdbQuit:
 			pass
 		finally:
@@ -116,64 +260,75 @@ class Pdb(Cmd):
 			del sys.trace
 			self.reset()
 	
-	def dispatch(self, frame, where, arg):
+	def dispatch(self, frame, event, arg):
-		if self.whatnext == 'quit':
+		if event == 'line':
-			return
+			return self.dispatch_line(frame)
-		if self.botframe is None:
+		if event == 'call':
-			self.botframe = frame
+			return self.dispatch_call(frame, arg)
-		if where == 'exception':
+		if event == 'return':
-			if self.whatnext == 'continue' and \
+			return self.dispatch_return(frame, arg)
-				arg[0] is not KeyboardInterrupt:
+		if event == 'exception':
-				return self.trace
+			return self.dispatch_exception(frame, arg)
-			stop = 1
+		print '*** dispatch: unknown event type', `event`
-		elif self.whatnext == 'continue':
-			stop = 0
-		elif self.whatnext == 'next':
-			stop = (frame == self.stopframe)
-		else:
-			stop = 1
-		if not stop:
-			# Check breakpoints only
-			filename = frame.f_code.co_filename
-			if not self.breaks.has_key(filename):
-				return self.dispatch
-			lineno = frame.f_lineno
-			if lineno not in self.breaks[filename]:
-				return self.dispatch
-		if where == 'call':
-			print 'call arguments:', arg
-		elif where == 'return':
-			print 'return value:', arg
-		elif where == 'exception':
-			print 'exception:', arg[:2]
-		elif where != 'line':
-			print 'unknown trace type:', `where`
-		self.setup(frame)
-		try:
-			self.whatnext = self.commandloop()
-		finally:
-			self.forget()
-		if self.whatnext == 'quit':
-			raise PdbQuit
-		if self.whatnext == 'next':
-			if where != 'return':
-				self.stopframe = frame
-			else:
-				self.whatnext = 'step'
 		return self.dispatch
 	
-	def commandloop(self):
+	def dispatch_line(self, frame):
+		if self.stop_here(frame) or self.break_here(frame):
+			self.ask_user(frame)
+		return self.dispatch
+	
+	def dispatch_call(self, frame, arg):
+		if self.botframe is None:
+			self.botframe = frame
+			return
+		if not (self.stop_here(frame) or self.break_anywhere(frame)):
+			return
+		frame.f_locals['__args__'] = arg
+		return self.dispatch
+	
+	def dispatch_return(self, frame, arg):
+		if self.stop_here(frame):
+			print '!!! return', `arg`
+		return
+	
+	def dispatch_exception(self, frame, arg):
+		if arg[0] is PdbQuit: return None
+		if self.stop_here(frame):
+			print '!!! exception', arg[0] + ':', `arg[1]`
+			self.ask_user(frame)
+		return self.dispatch
+	
+	def stop_here(self, frame):
+		if self.stopframe is None:
+			return 1
+		if frame is self.stopframe:
+			return 1
+		while frame is not self.stopframe:
+			if frame is None:
+				return 1
+			frame = frame.f_back
+		return 0
+	
+	def break_here(self, frame):
+		if not self.breaks.has_key(frame.f_code.co_filename):
+			return 0
+		if not frame.f_lineno in \
+			self.breaks[frame.f_code.co_filename]:
+			return 0
+		return 1
+	
+	def break_anywhere(self, frame):
+		return self.breaks.has_key(frame.f_code.co_filename)
+	
+	def ask_user(self, frame):
+		self.setup(frame)
 		self.printwhere(self.curframe)
-		try:
+		dummy = self.cmdloop()
-			self.innerloop()
+		self.forget()
-		except EOFError:
-			self.do_next('')
-		except PdbDone, msg:
-			return msg
 	
 	def default(self, line):
 		if not line:
-			self.do_next('')
+			return self.do_next('')
 		else:
 			if line[0] == '!': line = line[1:]
 			try:
@@ -181,7 +336,7 @@ class Pdb(Cmd):
 					self.curframe.f_globals, \
 					self.curframe.f_locals)
 			except:
-				print '***', sys.exc_type + ':',
+				print '***', sys.exc_type				 + ':',
 				print `sys.exc_value`
 	
 	do_h = Cmd.do_help
@@ -211,8 +366,13 @@ class Pdb(Cmd):
 	
 	def do_clear(self, arg):
 		if not arg:
-			self.breaks = {}
+			try:
-			print 'All breaks cleared!'
+				reply = raw_input('Clear all breaks? ')
+			except EOFError:
+				reply = 'no'
+			reply = string.lower(string.strip(reply))
+			if reply in ('y', 'yes'):
+				self.breaks = {}
 			return
 		try:
 			lineno = int(eval(arg))
@@ -222,52 +382,63 @@ class Pdb(Cmd):
 		filename = self.curframe.f_code.co_filename
 		try:
 			self.breaks[filename].remove(lineno)
-			if self.breaks[filename] == []:
-				del self.breaks[filename]
 		except (ValueError, KeyError):
 			print '*** There is no break there!'
 			return
+		if not self.breaks[filename]:
+			del self.breaks[filename]
+	do_cl = do_clear # 'c' is already an abbreviation for 'continue'
 	
 	def do_where(self, arg):
 		self.printtb()
 	do_w = do_where
 	
 	def do_up(self, arg):
-		if not self.stack: print '*** Top'
-		else:
-			self.curframe = self.stack[-1]
-			self.lineno = None
-			del self.stack[-1]
-			self.printwhere(self.curframe)
-	do_u = do_up
-	
-	def do_down(self, arg):
 		if self.curframe == self.botframe or \
-			not self.curframe.f_back: print '*** Bottom'
+			not self.curframe.f_back: print '*** Top'
 		else:
 			self.stack.append(self.curframe)
 			self.curframe = self.curframe.f_back
 			self.lineno = None
 			self.printwhere(self.curframe)
+	do_u = do_up
+	
+	def do_down(self, arg):
+		if not self.stack: print '*** Bottom'
+		else:
+			self.curframe = self.stack[-1]
+			self.lineno = None
+			del self.stack[-1]
+			self.printwhere(self.curframe)
 	do_d = do_down
 	
 	def do_step(self, arg):
-		raise PdbDone, 'step'
+		self.stopframe = None
+		return 1
 	do_s = do_step
 	
 	def do_next(self, arg):
-		raise PdbDone, 'next'
+		self.stopframe = self.curframe
+		return 1
 	do_n = do_next
 	
+	def do_return(self, arg):
+		self.stopframe = self.curframe.f_back
+		return 1
+	do_r = do_return
+	
 	def do_continue(self, arg):
-		raise PdbDone, 'continue'
+		self.stopframe = self.botframe
+		return 1
 	do_c = do_cont = do_continue
 	
 	def do_quit(self, arg):
-		raise PdbDone, 'quit'
+		self.stopframe = self.botframe
+		raise PdbQuit
 	do_q = do_quit
 	
 	def do_list(self, arg):
+		self.lastcmd = 'list'
 		last = None
 		if arg:
 			try:
@@ -314,6 +485,25 @@ class Pdb(Cmd):
 			pass
 	do_l = do_list
 	
+	def do_args(self, arg):
+		try:
+			value = eval('__args__', self.curframe.f_globals, \
+					self.curframe.f_locals)
+		except:
+			print '***', sys.exc_type + ':', `sys.exc_value`
+			return
+		print `value`
+	do_a = do_args
+	
+	def do_p(self, arg):
+		try:
+			value = eval(arg, self.curframe.f_globals, \
+					self.curframe.f_locals)
+		except:
+			print '***', sys.exc_type + ':', `sys.exc_value`
+			return
+		print `value`
+
 	# Print a traceback starting at a given stack frame
 	# Note that it is printed upside-down with respect
 	# to the orientation suggested by the up/down commands.
@@ -378,7 +568,7 @@ def bar(a):
 
 def test():
 	linecache.checkcache()
-	Pdb().init().run('foo(12)')
+	Pdb().init().run('foo(12)\n')
 
 
 # --------------------- main ---------------------
@@ -396,6 +586,9 @@ def main():
 			sys.exit(2)
 		del sys.argv[0]
 		sys.path.insert(0, head)
-		Pdb().init().run('import ' + tail[:-3])
+		run('import ' + tail[:-3])
 	else:
-		Pdb().init().run('')
+		run('')
+
+def run(statement):
+	Pdb().init().run(statement)