pdb.py 51.2 KB
Newer Older
1
#! /usr/bin/env python3
2

3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65
"""
The Python Debugger Pdb
=======================

To use the debugger in its simplest form:

        >>> import pdb
        >>> pdb.run('<a statement>')

The debugger's prompt is '(Pdb) '.  This will stop in the first
function call in <a statement>.

Alternatively, if a statement terminated with an unhandled exception,
you can use pdb's post-mortem facility to inspect the contents of the
traceback:

        >>> <a statement>
        <exception traceback>
        >>> import pdb
        >>> pdb.pm()

The commands recognized by the debugger are listed in the next
section.  Most can be abbreviated as indicated; e.g., h(elp) means
that 'help' can be typed as 'h' or 'help' (but not as 'he' or 'hel',
nor as 'H' or 'Help' or 'HELP').  Optional arguments are enclosed in
square brackets.  Alternatives in the command syntax are separated
by a vertical bar (|).

A blank line repeats the previous command literally, except for
'list', where it lists the next 11 lines.

Commands that the debugger doesn't recognize 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 or call functions.
When an exception occurs in such a statement, the exception name is
printed but the debugger's state is not changed.

The debugger supports aliases, which can save typing.  And aliases can
have parameters (see the alias help entry) which allows one a certain
level of adaptability to the context under examination.

Multiple commands may be entered on a single line, separated by the
pair ';;'.  No intelligence is applied to separating the commands; the
input is split at the first ';;', even if it is in the middle of a
quoted string.

If a file ".pdbrc" exists in your home directory or in the current
directory, it is read in and executed as if it had been typed at the
debugger prompt.  This is particularly useful for aliases.  If both
files exist, the one in the home directory is read first and aliases
defined there can be overriden by the local file.

Aside from aliases, the debugger is not directly programmable; but it
is implemented as a class from which you can derive your own debugger
class, which you can make as fancy as you like.


Debugger commands
=================

"""
66 67
# NOTE: the actual command documentation is collected from docstrings of the
# commands and is appended to __doc__ after the class has been defined.
Guido van Rossum's avatar
Guido van Rossum committed
68 69 70

import sys
import linecache
71 72
import cmd
import bdb
73
import dis
74
import os
75
import re
76
import code
77
import pprint
78
import traceback
79 80
import inspect
import types
81 82 83 84 85 86


class Restart(Exception):
    """Causes a debugger to be restarted for the debugged python program."""
    pass

Skip Montanaro's avatar
Skip Montanaro committed
87 88 89
__all__ = ["run", "pm", "Pdb", "runeval", "runctx", "runcall", "set_trace",
           "post_mortem", "help"]

90
def find_function(funcname, filename):
91
    cre = re.compile(r'def\s+%s\s*[(]' % re.escape(funcname))
Tim Peters's avatar
Tim Peters committed
92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108
    try:
        fp = open(filename)
    except IOError:
        return None
    # consumer of this info expects the first line to be 1
    lineno = 1
    answer = None
    while 1:
        line = fp.readline()
        if line == '':
            break
        if cre.match(line):
            answer = funcname, filename, lineno
            break
        lineno = lineno + 1
    fp.close()
    return answer
Guido van Rossum's avatar
Guido van Rossum committed
109

110 111
def getsourcelines(obj):
    lines, lineno = inspect.findsource(obj)
112
    if inspect.isframe(obj) and obj.f_globals is obj.f_locals:
113
        # must be a module frame: do not try to cut a block out of it
114
        return lines, 1
115
    elif inspect.ismodule(obj):
116
        return lines, 1
117
    return inspect.getblock(lines[lineno:]), lineno+1
Guido van Rossum's avatar
Guido van Rossum committed
118

119 120 121 122 123 124 125 126 127
def lasti2lineno(code, lasti):
    linestarts = list(dis.findlinestarts(code))
    linestarts.reverse()
    for i, lineno in linestarts:
        if lasti >= i:
            return lineno
    return 0


Guido van Rossum's avatar
Guido van Rossum committed
128 129 130 131
# Interaction prompt line will separate file and call info from code
# text using value of line_prefix string.  A newline and arrow may
# be to your liking.  You can set it once pdb is imported using the
# command "pdb.line_prefix = '\n% '".
Tim Peters's avatar
Tim Peters committed
132 133
# line_prefix = ': '    # Use this to get the old situation back
line_prefix = '\n-> '   # Probably a better default
Guido van Rossum's avatar
Guido van Rossum committed
134

135
class Pdb(bdb.Bdb, cmd.Cmd):
Tim Peters's avatar
Tim Peters committed
136

137 138
    def __init__(self, completekey='tab', stdin=None, stdout=None, skip=None):
        bdb.Bdb.__init__(self, skip=skip)
139 140 141
        cmd.Cmd.__init__(self, completekey, stdin, stdout)
        if stdout:
            self.use_rawinput = 0
Tim Peters's avatar
Tim Peters committed
142 143
        self.prompt = '(Pdb) '
        self.aliases = {}
144 145
        self.mainpyfile = ''
        self._wait_for_mainpyfile = 0
146
        self.tb_lineno = {}
Tim Peters's avatar
Tim Peters committed
147 148 149 150 151 152 153 154
        # Try to load readline if it exists
        try:
            import readline
        except ImportError:
            pass

        # Read $HOME/.pdbrc and ./.pdbrc
        self.rcLines = []
155
        if 'HOME' in os.environ:
Tim Peters's avatar
Tim Peters committed
156 157
            envHome = os.environ['HOME']
            try:
158 159
                with open(os.path.join(envHome, ".pdbrc")) as rcFile:
                    self.rcLines.extend(rcFile)
Tim Peters's avatar
Tim Peters committed
160 161 162
            except IOError:
                pass
        try:
163 164
            with open(".pdbrc") as rcFile:
                self.rcLines.extend(rcFile)
Tim Peters's avatar
Tim Peters committed
165 166 167
        except IOError:
            pass

168
        self.commands = {} # associates a command list to breakpoint numbers
Benjamin Peterson's avatar
Benjamin Peterson committed
169 170 171 172 173 174 175 176
        self.commands_doprompt = {} # for each bp num, tells if the prompt
                                    # must be disp. after execing the cmd list
        self.commands_silent = {} # for each bp num, tells if the stack trace
                                  # must be disp. after execing the cmd list
        self.commands_defining = False # True while in the process of defining
                                       # a command list
        self.commands_bnum = None # The breakpoint number for which we are
                                  # defining a list
177

Tim Peters's avatar
Tim Peters committed
178 179 180 181 182 183 184 185 186
    def reset(self):
        bdb.Bdb.reset(self)
        self.forget()

    def forget(self):
        self.lineno = None
        self.stack = []
        self.curindex = 0
        self.curframe = None
187
        self.tb_lineno.clear()
Tim Peters's avatar
Tim Peters committed
188

189
    def setup(self, f, tb):
Tim Peters's avatar
Tim Peters committed
190
        self.forget()
191 192 193 194 195 196 197 198
        self.stack, self.curindex = self.get_stack(f, tb)
        while tb:
            # when setting up post-mortem debugging with a traceback, save all
            # the original line numbers to be displayed along the current line
            # numbers (which can be different, e.g. due to finally clauses)
            lineno = lasti2lineno(tb.tb_frame.f_code, tb.tb_lasti)
            self.tb_lineno[tb.tb_frame] = lineno
            tb = tb.tb_next
Tim Peters's avatar
Tim Peters committed
199
        self.curframe = self.stack[self.curindex][0]
Benjamin Peterson's avatar
Benjamin Peterson committed
200 201 202 203
        # The f_locals dictionary is updated from the actual frame
        # locals whenever the .f_locals accessor is called, so we
        # cache it here to ensure that modifications are not overwritten.
        self.curframe_locals = self.curframe.f_locals
204
        return self.execRcLines()
Tim Peters's avatar
Tim Peters committed
205 206 207

    # Can be executed earlier than 'setup' if desired
    def execRcLines(self):
208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223
        if not self.rcLines:
            return
        # local copy because of recursion
        rcLines = self.rcLines
        rcLines.reverse()
        # execute every line only once
        self.rcLines = []
        while rcLines:
            line = rcLines.pop().strip()
            if line and line[0] != '#':
                if self.onecmd(line):
                    # if onecmd returns True, the command wants to exit
                    # from the interaction, save leftover rc lines
                    # to execute before next interaction
                    self.rcLines += reversed(rcLines)
                    return True
Tim Peters's avatar
Tim Peters committed
224

Tim Peters's avatar
Tim Peters committed
225
    # Override Bdb methods
Michael W. Hudson's avatar
Michael W. Hudson committed
226 227 228 229

    def user_call(self, frame, argument_list):
        """This method is called when there is the remote possibility
        that we ever need to stop in this function."""
230 231
        if self._wait_for_mainpyfile:
            return
Michael W. Hudson's avatar
Michael W. Hudson committed
232
        if self.stop_here(frame):
233
            self.message('--Call--')
Michael W. Hudson's avatar
Michael W. Hudson committed
234
            self.interaction(frame, None)
Tim Peters's avatar
Tim Peters committed
235 236 237

    def user_line(self, frame):
        """This function is called when we stop or break at this line."""
238 239 240 241 242
        if self._wait_for_mainpyfile:
            if (self.mainpyfile != self.canonic(frame.f_code.co_filename)
                or frame.f_lineno<= 0):
                return
            self._wait_for_mainpyfile = 0
243 244 245
        if self.bp_commands(frame):
            self.interaction(frame, None)

246
    def bp_commands(self, frame):
247 248 249 250 251 252 253 254
        """Call every command that was set for the current active breakpoint
        (if there is one).

        Returns True if the normal interaction function must be called,
        False otherwise."""
        # self.currentbp is set in bdb in Bdb.break_here if a breakpoint was hit
        if getattr(self, "currentbp", False) and \
               self.currentbp in self.commands:
255 256 257 258 259 260 261 262 263 264 265 266 267 268
            currentbp = self.currentbp
            self.currentbp = 0
            lastcmd_back = self.lastcmd
            self.setup(frame, None)
            for line in self.commands[currentbp]:
                self.onecmd(line)
            self.lastcmd = lastcmd_back
            if not self.commands_silent[currentbp]:
                self.print_stack_entry(self.stack[self.curindex])
            if self.commands_doprompt[currentbp]:
                self.cmdloop()
            self.forget()
            return
        return 1
Tim Peters's avatar
Tim Peters committed
269 270 271

    def user_return(self, frame, return_value):
        """This function is called when a return trap is set here."""
272 273
        if self._wait_for_mainpyfile:
            return
Tim Peters's avatar
Tim Peters committed
274
        frame.f_locals['__return__'] = return_value
275
        self.message('--Return--')
Tim Peters's avatar
Tim Peters committed
276 277
        self.interaction(frame, None)

278
    def user_exception(self, frame, exc_info):
Tim Peters's avatar
Tim Peters committed
279 280
        """This function is called if an exception occurs,
        but only if we are to stop at or just below this level."""
281 282
        if self._wait_for_mainpyfile:
            return
283
        exc_type, exc_value, exc_traceback = exc_info
Tim Peters's avatar
Tim Peters committed
284
        frame.f_locals['__exception__'] = exc_type, exc_value
285 286
        self.message(traceback.format_exception_only(exc_type,
                                                     exc_value)[-1].strip())
Tim Peters's avatar
Tim Peters committed
287 288 289 290 291
        self.interaction(frame, exc_traceback)

    # General interaction function

    def interaction(self, frame, traceback):
292 293 294 295 296
        if self.setup(frame, traceback):
            # no interaction desired at this time (happens if .pdbrc contains
            # a command like "continue")
            self.forget()
            return
Tim Peters's avatar
Tim Peters committed
297 298 299 300
        self.print_stack_entry(self.stack[self.curindex])
        self.cmdloop()
        self.forget()

Benjamin Peterson's avatar
Benjamin Peterson committed
301 302 303 304
    def displayhook(self, obj):
        """Custom displayhook for the exec in default(), which prevents
        assignment of the _ variable in the builtins.
        """
305 306
        # reproduce the behavior of the standard displayhook, not printing None
        if obj is not None:
307
            self.message(repr(obj))
Benjamin Peterson's avatar
Benjamin Peterson committed
308

Tim Peters's avatar
Tim Peters committed
309 310
    def default(self, line):
        if line[:1] == '!': line = line[1:]
Benjamin Peterson's avatar
Benjamin Peterson committed
311
        locals = self.curframe_locals
Tim Peters's avatar
Tim Peters committed
312 313 314
        globals = self.curframe.f_globals
        try:
            code = compile(line + '\n', '<stdin>', 'single')
315 316
            save_stdout = sys.stdout
            save_stdin = sys.stdin
Benjamin Peterson's avatar
Benjamin Peterson committed
317
            save_displayhook = sys.displayhook
318 319 320
            try:
                sys.stdin = self.stdin
                sys.stdout = self.stdout
Benjamin Peterson's avatar
Benjamin Peterson committed
321
                sys.displayhook = self.displayhook
322 323 324 325
                exec(code, globals, locals)
            finally:
                sys.stdout = save_stdout
                sys.stdin = save_stdin
Benjamin Peterson's avatar
Benjamin Peterson committed
326
                sys.displayhook = save_displayhook
Tim Peters's avatar
Tim Peters committed
327
        except:
328 329
            exc_info = sys.exc_info()[:2]
            self.error(traceback.format_exception_only(*exc_info)[-1].strip())
Tim Peters's avatar
Tim Peters committed
330 331 332

    def precmd(self, line):
        """Handle alias expansion and ';;' separator."""
333
        if not line.strip():
Tim Peters's avatar
Tim Peters committed
334
            return line
Eric S. Raymond's avatar
Eric S. Raymond committed
335
        args = line.split()
336
        while args[0] in self.aliases:
Tim Peters's avatar
Tim Peters committed
337 338 339
            line = self.aliases[args[0]]
            ii = 1
            for tmpArg in args[1:]:
Eric S. Raymond's avatar
Eric S. Raymond committed
340
                line = line.replace("%" + str(ii),
Tim Peters's avatar
Tim Peters committed
341 342
                                      tmpArg)
                ii = ii + 1
Eric S. Raymond's avatar
Eric S. Raymond committed
343 344
            line = line.replace("%*", ' '.join(args[1:]))
            args = line.split()
Tim Peters's avatar
Tim Peters committed
345 346 347
        # split into ';;' separated commands
        # unless it's an alias command
        if args[0] != 'alias':
Eric S. Raymond's avatar
Eric S. Raymond committed
348
            marker = line.find(';;')
Tim Peters's avatar
Tim Peters committed
349 350
            if marker >= 0:
                # queue up everything after marker
Eric S. Raymond's avatar
Eric S. Raymond committed
351
                next = line[marker+2:].lstrip()
Tim Peters's avatar
Tim Peters committed
352
                self.cmdqueue.append(next)
Eric S. Raymond's avatar
Eric S. Raymond committed
353
                line = line[:marker].rstrip()
Tim Peters's avatar
Tim Peters committed
354 355
        return line

356 357 358 359
    def onecmd(self, line):
        """Interpret the argument as though it had been typed in response
        to the prompt.

360 361
        Checks whether this line is typed at the normal prompt or in
        a breakpoint command list definition.
362 363 364 365 366 367
        """
        if not self.commands_defining:
            return cmd.Cmd.onecmd(self, line)
        else:
            return self.handle_command_def(line)

368
    def handle_command_def(self, line):
369
        """Handles one command line during command list definition."""
370
        cmd, arg, line = self.parseline(line)
371 372
        if not cmd:
            return
373 374 375 376 377 378 379
        if cmd == 'silent':
            self.commands_silent[self.commands_bnum] = True
            return # continue to handle other cmd def in the cmd list
        elif cmd == 'end':
            self.cmdqueue = []
            return 1 # end of cmd list
        cmdlist = self.commands[self.commands_bnum]
380
        if arg:
381 382 383 384 385 386 387 388
            cmdlist.append(cmd+' '+arg)
        else:
            cmdlist.append(cmd)
        # Determine if we must stop
        try:
            func = getattr(self, 'do_' + cmd)
        except AttributeError:
            func = self.default
389 390
        # one of the resuming commands
        if func.__name__ in self.commands_resuming:
391 392 393 394 395
            self.commands_doprompt[self.commands_bnum] = False
            self.cmdqueue = []
            return 1
        return

396 397 398 399 400 401 402 403
    # interface abstraction functions

    def message(self, msg):
        print(msg, file=self.stdout)

    def error(self, msg):
        print('***', msg, file=self.stdout)

Tim Peters's avatar
Tim Peters committed
404 405 406 407
    # Command definitions, called by cmdloop()
    # The argument is the remaining string on the command line
    # Return true to exit from the command loop

408
    def do_commands(self, arg):
409 410 411 412 413 414 415 416 417 418 419 420
        """commands [bpnumber]
        (com) ...
        (com) end
        (Pdb)

        Specify a list of commands for breakpoint number bpnumber.
        The commands themselves are entered on the following lines.
        Type a line containing just 'end' to terminate the commands.
        The commands are executed when the breakpoint is hit.

        To remove all commands from a breakpoint, type commands and
        follow it immediately with end; that is, give no commands.
421

422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444
        With no bpnumber argument, commands refers to the last
        breakpoint set.

        You can use breakpoint commands to start your program up
        again.  Simply use the continue command, or step, or any other
        command that resumes execution.

        Specifying any command resuming execution (currently continue,
        step, next, return, jump, quit and their abbreviations)
        terminates the command list (as if that command was
        immediately followed by end).  This is because any time you
        resume execution (even with a simple next or step), you may
        encounter another breakpoint -- which could have its own
        command list, leading to ambiguities about which list to
        execute.

        If you use the 'silent' command in the command list, the usual
        message about stopping at a breakpoint is not printed.  This
        may be desirable for breakpoints that are to print a specific
        message and then continue.  If none of the other commands
        print anything, you will see no sign that the breakpoint was
        reached.
        """
445
        if not arg:
446
            bnum = len(bdb.Breakpoint.bpbynumber) - 1
447 448 449 450
        else:
            try:
                bnum = int(arg)
            except:
451
                self.error("Usage: commands [bnum]\n        ...\n        end")
452 453
                return
        self.commands_bnum = bnum
454 455 456 457 458 459 460
        # Save old definitions for the case of a keyboard interrupt.
        if bnum in self.commands:
            old_command_defs = (self.commands[bnum],
                                self.commands_doprompt[bnum],
                                self.commands_silent[bnum])
        else:
            old_command_defs = None
461 462 463
        self.commands[bnum] = []
        self.commands_doprompt[bnum] = True
        self.commands_silent[bnum] = False
464

465 466 467
        prompt_back = self.prompt
        self.prompt = '(com) '
        self.commands_defining = True
468 469
        try:
            self.cmdloop()
470 471 472 473 474 475 476 477 478 479 480
        except KeyboardInterrupt:
            # Restore old definitions.
            if old_command_defs:
                self.commands[bnum] = old_command_defs[0]
                self.commands_doprompt[bnum] = old_command_defs[1]
                self.commands_silent[bnum] = old_command_defs[2]
            else:
                del self.commands[bnum]
                del self.commands_doprompt[bnum]
                del self.commands_silent[bnum]
            self.error('command definition aborted, old commands restored')
481 482 483
        finally:
            self.commands_defining = False
            self.prompt = prompt_back
484

Tim Peters's avatar
Tim Peters committed
485
    def do_break(self, arg, temporary = 0):
486 487 488 489 490 491 492 493 494 495 496 497 498 499
        """b(reak) [ ([filename:]lineno | function) [, condition] ]
        Without argument, list all breaks.

        With a line number argument, set a break at this line in the
        current file.  With a function name, set a break at the first
        executable line of that function.  If a second argument is
        present, it is a string specifying an expression which must
        evaluate to true before the breakpoint is honored.

        The line number may be prefixed with a filename and a colon,
        to specify a breakpoint in another file (probably one that
        hasn't been loaded yet).  The file is searched for on
        sys.path; the .py suffix may be omitted.
        """
Tim Peters's avatar
Tim Peters committed
500 501
        if not arg:
            if self.breaks:  # There's at least one
502
                self.message("Num Type         Disp Enb   Where")
Tim Peters's avatar
Tim Peters committed
503 504
                for bp in bdb.Breakpoint.bpbynumber:
                    if bp:
505
                        self.message(bp.bpformat())
Tim Peters's avatar
Tim Peters committed
506 507 508 509 510 511
            return
        # parse arguments; comma has lowest precedence
        # and cannot occur in filename
        filename = None
        lineno = None
        cond = None
Eric S. Raymond's avatar
Eric S. Raymond committed
512
        comma = arg.find(',')
Tim Peters's avatar
Tim Peters committed
513 514
        if comma > 0:
            # parse stuff after comma: "condition"
Eric S. Raymond's avatar
Eric S. Raymond committed
515 516
            cond = arg[comma+1:].lstrip()
            arg = arg[:comma].rstrip()
Tim Peters's avatar
Tim Peters committed
517
        # parse stuff before comma: [filename:]lineno | function
Eric S. Raymond's avatar
Eric S. Raymond committed
518
        colon = arg.rfind(':')
519
        funcname = None
Tim Peters's avatar
Tim Peters committed
520
        if colon >= 0:
Eric S. Raymond's avatar
Eric S. Raymond committed
521
            filename = arg[:colon].rstrip()
Tim Peters's avatar
Tim Peters committed
522 523
            f = self.lookupmodule(filename)
            if not f:
524
                self.error('%r not found from sys.path' % filename)
Tim Peters's avatar
Tim Peters committed
525 526 527
                return
            else:
                filename = f
Eric S. Raymond's avatar
Eric S. Raymond committed
528
            arg = arg[colon+1:].lstrip()
Tim Peters's avatar
Tim Peters committed
529 530
            try:
                lineno = int(arg)
531
            except ValueError as msg:
532
                self.error('Bad lineno: %s' % arg)
Tim Peters's avatar
Tim Peters committed
533 534 535 536 537 538 539 540 541
                return
        else:
            # no colon; can be lineno or function
            try:
                lineno = int(arg)
            except ValueError:
                try:
                    func = eval(arg,
                                self.curframe.f_globals,
Benjamin Peterson's avatar
Benjamin Peterson committed
542
                                self.curframe_locals)
Tim Peters's avatar
Tim Peters committed
543 544 545
                except:
                    func = arg
                try:
546 547
                    if hasattr(func, '__func__'):
                        func = func.__func__
548
                    code = func.__code__
549 550 551
                    #use co_name to identify the bkpt (function names
                    #could be aliased, but co_name is invariant)
                    funcname = code.co_name
Tim Peters's avatar
Tim Peters committed
552 553 554 555 556 557
                    lineno = code.co_firstlineno
                    filename = code.co_filename
                except:
                    # last thing to try
                    (ok, filename, ln) = self.lineinfo(arg)
                    if not ok:
558 559
                        self.error('The specified object %r is not a function '
                                   'or was not found along sys.path.' % arg)
Tim Peters's avatar
Tim Peters committed
560
                        return
561
                    funcname = ok # ok contains a function name
Tim Peters's avatar
Tim Peters committed
562 563 564 565 566 567 568
                    lineno = int(ln)
        if not filename:
            filename = self.defaultFile()
        # Check for reasonable breakpoint
        line = self.checkline(filename, lineno)
        if line:
            # now set the break point
569
            err = self.set_break(filename, line, temporary, cond, funcname)
570 571
            if err:
                self.error(err, file=self.stdout)
Tim Peters's avatar
Tim Peters committed
572 573
            else:
                bp = self.get_breaks(filename, line)[-1]
574 575
                self.message("Breakpoint %d at %s:%d" %
                             (bp.number, bp.file, bp.line))
Tim Peters's avatar
Tim Peters committed
576 577 578 579 580

    # To be overridden in derived debuggers
    def defaultFile(self):
        """Produce a reasonable default."""
        filename = self.curframe.f_code.co_filename
581 582
        if filename == '<string>' and self.mainpyfile:
            filename = self.mainpyfile
Tim Peters's avatar
Tim Peters committed
583 584 585 586 587
        return filename

    do_b = do_break

    def do_tbreak(self, arg):
588 589 590 591
        """tbreak [ ([filename:]lineno | function) [, condition] ]
        Same arguments as break, but sets a temporary breakpoint: it
        is automatically deleted when first hit.
        """
Tim Peters's avatar
Tim Peters committed
592 593 594 595 596
        self.do_break(arg, 1)

    def lineinfo(self, identifier):
        failed = (None, None, None)
        # Input is identifier, may be in single quotes
Eric S. Raymond's avatar
Eric S. Raymond committed
597
        idstring = identifier.split("'")
Tim Peters's avatar
Tim Peters committed
598 599
        if len(idstring) == 1:
            # not in single quotes
Eric S. Raymond's avatar
Eric S. Raymond committed
600
            id = idstring[0].strip()
Tim Peters's avatar
Tim Peters committed
601 602
        elif len(idstring) == 3:
            # quoted
Eric S. Raymond's avatar
Eric S. Raymond committed
603
            id = idstring[1].strip()
Tim Peters's avatar
Tim Peters committed
604 605 606
        else:
            return failed
        if id == '': return failed
Eric S. Raymond's avatar
Eric S. Raymond committed
607
        parts = id.split('.')
Tim Peters's avatar
Tim Peters committed
608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627
        # Protection for derived debuggers
        if parts[0] == 'self':
            del parts[0]
            if len(parts) == 0:
                return failed
        # Best first guess at file to look at
        fname = self.defaultFile()
        if len(parts) == 1:
            item = parts[0]
        else:
            # More than one part.
            # First is module, second is method/class
            f = self.lookupmodule(parts[0])
            if f:
                fname = f
            item = parts[1]
        answer = find_function(item, fname)
        return answer or failed

    def checkline(self, filename, lineno):
628
        """Check whether specified line seems to be executable.
Tim Peters's avatar
Tim Peters committed
629

630 631 632
        Return `lineno` if it is, 0 if not (e.g. a docstring, comment, blank
        line or EOF). Warning: testing is not comprehensive.
        """
633 634 635 636
        # this method should be callable before starting debugging, so default
        # to "no globals" if there is no current frame
        globs = self.curframe.f_globals if hasattr(self, 'curframe') else None
        line = linecache.getline(filename, lineno, globs)
Tim Peters's avatar
Tim Peters committed
637
        if not line:
638
            self.message('End of file')
Tim Peters's avatar
Tim Peters committed
639
            return 0
Eric S. Raymond's avatar
Eric S. Raymond committed
640
        line = line.strip()
Tim Peters's avatar
Tim Peters committed
641
        # Don't allow setting breakpoint at a blank line
642 643
        if (not line or (line[0] == '#') or
             (line[:3] == '"""') or line[:3] == "'''"):
644
            self.error('Blank or comment')
Tim Peters's avatar
Tim Peters committed
645 646 647 648
            return 0
        return lineno

    def do_enable(self, arg):
649 650 651 652
        """enable bpnumber [bpnumber ...]
        Enables the breakpoints given as a space separated list of
        breakpoint numbers.
        """
Eric S. Raymond's avatar
Eric S. Raymond committed
653
        args = arg.split()
Tim Peters's avatar
Tim Peters committed
654
        for i in args:
655
            try:
656 657
                bp = self.get_bpbynumber(i)
            except ValueError as err:
658
                self.error(err)
659
            else:
Tim Peters's avatar
Tim Peters committed
660
                bp.enable()
661
                self.message('Enabled %s' % bp)
Tim Peters's avatar
Tim Peters committed
662 663

    def do_disable(self, arg):
664 665 666 667 668 669 670
        """disable bpnumber [bpnumber ...]
        Disables the breakpoints given as a space separated list of
        breakpoint numbers.  Disabling a breakpoint means it cannot
        cause the program to stop execution, but unlike clearing a
        breakpoint, it remains in the list of breakpoints and can be
        (re-)enabled.
        """
Eric S. Raymond's avatar
Eric S. Raymond committed
671
        args = arg.split()
Tim Peters's avatar
Tim Peters committed
672
        for i in args:
673
            try:
674 675
                bp = self.get_bpbynumber(i)
            except ValueError as err:
676
                self.error(err)
677
            else:
Tim Peters's avatar
Tim Peters committed
678
                bp.disable()
679
                self.message('Disabled %s' % bp)
Tim Peters's avatar
Tim Peters committed
680 681

    def do_condition(self, arg):
682 683 684 685 686 687
        """condition bpnumber [condition]
        Set a new condition for the breakpoint, an expression which
        must evaluate to true before the breakpoint is honored.  If
        condition is absent, any existing condition is removed; i.e.,
        the breakpoint is made unconditional.
        """
Eric S. Raymond's avatar
Eric S. Raymond committed
688
        args = arg.split(' ', 1)
Tim Peters's avatar
Tim Peters committed
689 690
        try:
            cond = args[1]
691
        except IndexError:
Tim Peters's avatar
Tim Peters committed
692
            cond = None
693
        try:
694 695
            bp = self.get_bpbynumber(args[0].strip())
        except ValueError as err:
696
            self.error(err)
697
        else:
Tim Peters's avatar
Tim Peters committed
698 699
            bp.cond = cond
            if not cond:
700
                self.message('Breakpoint %d is now unconditional.' % bp.number)
701
            else:
702
                self.message('New condition set for breakpoint %d.' % bp.number)
Tim Peters's avatar
Tim Peters committed
703

704
    def do_ignore(self, arg):
705 706 707 708 709 710 711 712
        """ignore bpnumber [count]
        Set the ignore count for the given breakpoint number.  If
        count is omitted, the ignore count is set to 0.  A breakpoint
        becomes active when the ignore count is zero.  When non-zero,
        the count is decremented each time the breakpoint is reached
        and the breakpoint is not disabled and any associated
        condition evaluates to true.
        """
Eric S. Raymond's avatar
Eric S. Raymond committed
713
        args = arg.split()
Tim Peters's avatar
Tim Peters committed
714
        try:
Eric S. Raymond's avatar
Eric S. Raymond committed
715
            count = int(args[1].strip())
Tim Peters's avatar
Tim Peters committed
716 717
        except:
            count = 0
718
        try:
719 720
            bp = self.get_bpbynumber(args[0].strip())
        except ValueError as err:
721
            self.error(err)
722
        else:
Tim Peters's avatar
Tim Peters committed
723
            bp.ignore = count
724 725
            if count > 0:
                if count > 1:
726
                    countstr = '%d crossings' % count
Tim Peters's avatar
Tim Peters committed
727
                else:
728 729 730
                    countstr = '1 crossing'
                self.message('Will ignore next %s of breakpoint %d.' %
                             (countstr, bp.number))
Tim Peters's avatar
Tim Peters committed
731
            else:
732 733
                self.message('Will stop next time breakpoint %d is reached.'
                             % bp.number)
Tim Peters's avatar
Tim Peters committed
734 735

    def do_clear(self, arg):
736 737 738 739 740 741
        """cl(ear) filename:lineno\ncl(ear) [bpnumber [bpnumber...]]
        With a space separated list of breakpoint numbers, clear
        those breakpoints.  Without argument, clear all breaks (but
        first ask confirmation).  With a filename:lineno argument,
        clear all breaks at that line in that file.
        """
Tim Peters's avatar
Tim Peters committed
742 743
        if not arg:
            try:
744
                reply = input('Clear all breaks? ')
Tim Peters's avatar
Tim Peters committed
745 746
            except EOFError:
                reply = 'no'
Eric S. Raymond's avatar
Eric S. Raymond committed
747
            reply = reply.strip().lower()
Tim Peters's avatar
Tim Peters committed
748
            if reply in ('y', 'yes'):
749
                bplist = [bp for bp in bdb.Breakpoint.bpbynumber if bp]
Tim Peters's avatar
Tim Peters committed
750
                self.clear_all_breaks()
751
                for bp in bplist:
752
                    self.message('Deleted %s' % bp)
Tim Peters's avatar
Tim Peters committed
753 754 755
            return
        if ':' in arg:
            # Make sure it works for "clear C:\foo\bar.py:12"
Eric S. Raymond's avatar
Eric S. Raymond committed
756
            i = arg.rfind(':')
Tim Peters's avatar
Tim Peters committed
757 758 759 760
            filename = arg[:i]
            arg = arg[i+1:]
            try:
                lineno = int(arg)
761
            except ValueError:
Tim Peters's avatar
Tim Peters committed
762 763
                err = "Invalid line number (%s)" % arg
            else:
764
                bplist = self.get_breaks(filename, lineno)
Tim Peters's avatar
Tim Peters committed
765
                err = self.clear_break(filename, lineno)
766
            if err:
767
                self.error(err)
768 769
            else:
                for bp in bplist:
770
                    self.message('Deleted %s' % bp)
Tim Peters's avatar
Tim Peters committed
771
            return
Eric S. Raymond's avatar
Eric S. Raymond committed
772
        numberlist = arg.split()
Tim Peters's avatar
Tim Peters committed
773
        for i in numberlist:
774
            try:
775 776
                bp = self.get_bpbynumber(i)
            except ValueError as err:
777
                self.error(err)
Tim Peters's avatar
Tim Peters committed
778
            else:
779
                self.clear_break(bp.file, bp.line)
780
                self.message('Deleted %s' % bp)
Tim Peters's avatar
Tim Peters committed
781 782 783
    do_cl = do_clear # 'c' is already an abbreviation for 'continue'

    def do_where(self, arg):
784 785 786 787 788
        """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.  'bt' is an alias for this command.
        """
Tim Peters's avatar
Tim Peters committed
789 790
        self.print_stack_trace()
    do_w = do_where
791
    do_bt = do_where
Tim Peters's avatar
Tim Peters committed
792

793 794 795 796 797 798 799 800
    def _select_frame(self, number):
        assert 0 <= number < len(self.stack)
        self.curindex = number
        self.curframe = self.stack[self.curindex][0]
        self.curframe_locals = self.curframe.f_locals
        self.print_stack_entry(self.stack[self.curindex])
        self.lineno = None

Tim Peters's avatar
Tim Peters committed
801
    def do_up(self, arg):
802 803 804 805
        """u(p) [count]
        Move the current frame count (default one) levels up in the
        stack trace (to an older frame).
        """
Tim Peters's avatar
Tim Peters committed
806
        if self.curindex == 0:
807
            self.error('Oldest frame')
808 809 810 811
            return
        try:
            count = int(arg or 1)
        except ValueError:
812
            self.error('Invalid frame count (%s)' % arg)
813 814 815
            return
        if count < 0:
            newframe = 0
Tim Peters's avatar
Tim Peters committed
816
        else:
817 818
            newframe = max(0, self.curindex - count)
        self._select_frame(newframe)
Tim Peters's avatar
Tim Peters committed
819 820 821
    do_u = do_up

    def do_down(self, arg):
822 823 824 825
        """d(own) [count]
        Move the current frame count (default one) levels down in the
        stack trace (to a newer frame).
        """
Tim Peters's avatar
Tim Peters committed
826
        if self.curindex + 1 == len(self.stack):
827
            self.error('Newest frame')
828 829 830 831
            return
        try:
            count = int(arg or 1)
        except ValueError:
832
            self.error('Invalid frame count (%s)' % arg)
833 834 835
            return
        if count < 0:
            newframe = len(self.stack) - 1
Tim Peters's avatar
Tim Peters committed
836
        else:
837 838
            newframe = min(len(self.stack) - 1, self.curindex + count)
        self._select_frame(newframe)
Tim Peters's avatar
Tim Peters committed
839 840
    do_d = do_down

Alexandre Vassalotti's avatar
Alexandre Vassalotti committed
841
    def do_until(self, arg):
842 843 844 845 846 847 848
        """unt(il) [lineno]
        Without argument, continue execution until the line with a
        number greater than the current one is reached.  With a line
        number, continue execution until a line with a number greater
        or equal to that is reached.  In both cases, also stop when
        the current frame returns.
        """
849 850 851 852
        if arg:
            try:
                lineno = int(arg)
            except ValueError:
853
                self.error('Error in argument: %r' % arg)
854 855
                return
            if lineno <= self.curframe.f_lineno:
856 857
                self.error('"until" line number is smaller than current '
                           'line number')
858 859 860 861
                return
        else:
            lineno = None
        self.set_until(self.curframe, lineno)
Alexandre Vassalotti's avatar
Alexandre Vassalotti committed
862 863 864
        return 1
    do_unt = do_until

Tim Peters's avatar
Tim Peters committed
865
    def do_step(self, arg):
866 867 868 869 870
        """s(tep)
        Execute the current line, stop at the first possible occasion
        (either in a function that is called or in the current
        function).
        """
Tim Peters's avatar
Tim Peters committed
871 872 873 874 875
        self.set_step()
        return 1
    do_s = do_step

    def do_next(self, arg):
876 877 878 879
        """n(ext)
        Continue execution until the next line in the current function
        is reached or it returns.
        """
Tim Peters's avatar
Tim Peters committed
880 881 882 883
        self.set_next(self.curframe)
        return 1
    do_n = do_next

884
    def do_run(self, arg):
885 886 887 888 889 890
        """run [args...]
        Restart the debugged python program. If a string is supplied
        it is splitted with "shlex", and the result is used as the new
        sys.argv.  History, breakpoints, actions and debugger options
        are preserved.  "restart" is an alias for "run".
        """
891 892 893 894 895
        if arg:
            import shlex
            argv0 = sys.argv[0:1]
            sys.argv = shlex.split(arg)
            sys.argv[:0] = argv0
896
        # this is caught in the main debugger loop
897 898 899 900
        raise Restart

    do_restart = do_run

Tim Peters's avatar
Tim Peters committed
901
    def do_return(self, arg):
902 903 904
        """r(eturn)
        Continue execution until the current function returns.
        """
Tim Peters's avatar
Tim Peters committed
905 906 907 908 909
        self.set_return(self.curframe)
        return 1
    do_r = do_return

    def do_continue(self, arg):
910 911 912
        """c(ont(inue))
        Continue execution, only stop when a breakpoint is encountered.
        """
Tim Peters's avatar
Tim Peters committed
913 914 915 916
        self.set_continue()
        return 1
    do_c = do_cont = do_continue

917
    def do_jump(self, arg):
918 919 920 921 922 923 924 925 926 927
        """j(ump) lineno
        Set the next line that will be executed.  Only available in
        the bottom-most frame.  This lets you jump back and execute
        code again, or jump forward to skip code that you don't want
        to run.

        It should be noted that not all jumps are allowed -- for
        instance it is not possible to jump into the middle of a
        for loop or out of a finally clause.
        """
928
        if self.curindex + 1 != len(self.stack):
929
            self.error('You can only jump within the bottom frame')
930 931 932 933
            return
        try:
            arg = int(arg)
        except ValueError:
934
            self.error("The 'jump' command requires a line number")
935 936 937 938 939 940 941
        else:
            try:
                # Do the jump, fix up our copy of the stack, and display the
                # new position
                self.curframe.f_lineno = arg
                self.stack[self.curindex] = self.stack[self.curindex][0], arg
                self.print_stack_entry(self.stack[self.curindex])
942
            except ValueError as e:
943
                self.error('Jump failed: %s' % e)
944 945
    do_j = do_jump

946
    def do_debug(self, arg):
947 948 949 950 951
        """debug code
        Enter a recursive debugger that steps through the code
        argument (which is an arbitrary expression or statement to be
        executed in the current environment).
        """
952 953
        sys.settrace(None)
        globals = self.curframe.f_globals
Benjamin Peterson's avatar
Benjamin Peterson committed
954
        locals = self.curframe_locals
955
        p = Pdb(self.completekey, self.stdin, self.stdout)
Guido van Rossum's avatar
Guido van Rossum committed
956
        p.prompt = "(%s) " % self.prompt.strip()
957
        self.message("ENTERING RECURSIVE DEBUGGER")
Guido van Rossum's avatar
Guido van Rossum committed
958
        sys.call_tracing(p.run, (arg, globals, locals))
959
        self.message("LEAVING RECURSIVE DEBUGGER")
960 961 962
        sys.settrace(self.trace_dispatch)
        self.lastcmd = p.lastcmd

Tim Peters's avatar
Tim Peters committed
963
    def do_quit(self, arg):
964 965 966
        """q(uit)\nexit
        Quit from the debugger. The program being executed is aborted.
        """
967
        self._user_requested_quit = 1
Tim Peters's avatar
Tim Peters committed
968 969
        self.set_quit()
        return 1
970

Tim Peters's avatar
Tim Peters committed
971
    do_q = do_quit
972
    do_exit = do_quit
Tim Peters's avatar
Tim Peters committed
973

974
    def do_EOF(self, arg):
975 976 977 978
        """EOF
        Handles the receipt of EOF as a command.
        """
        self.message('')
979
        self._user_requested_quit = 1
980 981 982
        self.set_quit()
        return 1

Tim Peters's avatar
Tim Peters committed
983
    def do_args(self, arg):
984 985 986
        """a(rgs)
        Print the argument list of the current function.
        """
Benjamin Peterson's avatar
Benjamin Peterson committed
987 988
        co = self.curframe.f_code
        dict = self.curframe_locals
Tim Peters's avatar
Tim Peters committed
989 990 991 992 993
        n = co.co_argcount
        if co.co_flags & 4: n = n+1
        if co.co_flags & 8: n = n+1
        for i in range(n):
            name = co.co_varnames[i]
994 995 996 997
            if name in dict:
                self.message('%s = %r' % (name, dict[name]))
            else:
                self.message('%s = *** undefined ***' % (name,))
Tim Peters's avatar
Tim Peters committed
998 999 1000
    do_a = do_args

    def do_retval(self, arg):
1001 1002 1003
        """retval
        Print the return value for the last return of a function.
        """
Benjamin Peterson's avatar
Benjamin Peterson committed
1004
        if '__return__' in self.curframe_locals:
1005
            self.message(repr(self.curframe_locals['__return__']))
Tim Peters's avatar
Tim Peters committed
1006
        else:
1007
            self.error('Not yet returned!')
Tim Peters's avatar
Tim Peters committed
1008 1009
    do_rv = do_retval

1010
    def _getval(self, arg):
Tim Peters's avatar
Tim Peters committed
1011
        try:
Benjamin Peterson's avatar
Benjamin Peterson committed
1012
            return eval(arg, self.curframe.f_globals, self.curframe_locals)
Tim Peters's avatar
Tim Peters committed
1013
        except:
1014 1015
            exc_info = sys.exc_info()[:2]
            self.error(traceback.format_exception_only(*exc_info)[-1].strip())
1016 1017 1018
            raise

    def do_p(self, arg):
1019 1020 1021
        """p(rint) expression
        Print the value of the expression.
        """
1022
        try:
1023
            self.message(repr(self._getval(arg)))
1024 1025
        except:
            pass
1026 1027
    # make "print" an alias of "p" since print isn't a Python statement anymore
    do_print = do_p
Tim Peters's avatar
Tim Peters committed
1028

1029
    def do_pp(self, arg):
1030 1031 1032
        """pp expression
        Pretty-print the value of the expression.
        """
1033
        try:
1034
            self.message(pprint.pformat(self._getval(arg)))
1035 1036
        except:
            pass
Tim Peters's avatar
Tim Peters committed
1037 1038

    def do_list(self, arg):
1039
        """l(ist) [first [,last] | .]
1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051

        List source code for the current file.  Without arguments,
        list 11 lines around the current line or continue the previous
        listing.  With . as argument, list 11 lines around the current
        line.  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.

        The current line in the current frame is indicated by "->".
        If an exception is being debugged, the line where the
        exception was originally raised or propagated is indicated by
        ">>", if it differs from the current line.
1052
        """
Tim Peters's avatar
Tim Peters committed
1053 1054
        self.lastcmd = 'list'
        last = None
1055
        if arg and arg != '.':
Tim Peters's avatar
Tim Peters committed
1056
            try:
1057 1058 1059 1060
                if ',' in arg:
                    first, last = arg.split(',')
                    first = int(first.strip())
                    last = int(last.strip())
Tim Peters's avatar
Tim Peters committed
1061
                    if last < first:
1062
                        # assume it's a count
Tim Peters's avatar
Tim Peters committed
1063 1064
                        last = first + last
                else:
1065 1066 1067 1068
                    first = int(arg.strip())
                    first = max(1, first - 5)
            except ValueError:
                self.error('Error in argument: %r' % arg)
Tim Peters's avatar
Tim Peters committed
1069
                return
1070
        elif self.lineno is None or arg == '.':
Tim Peters's avatar
Tim Peters committed
1071 1072 1073 1074 1075 1076 1077 1078
            first = max(1, self.curframe.f_lineno - 5)
        else:
            first = self.lineno + 1
        if last is None:
            last = first + 10
        filename = self.curframe.f_code.co_filename
        breaklist = self.get_file_breaks(filename)
        try:
1079 1080
            lines = linecache.getlines(filename, self.curframe.f_globals)
            self._print_lines(lines[first-1:last], first, breaklist,
1081
                              self.curframe)
1082 1083 1084
            self.lineno = min(last, len(lines))
            if len(lines) < last:
                self.message('[EOF]')
Tim Peters's avatar
Tim Peters committed
1085 1086 1087 1088
        except KeyboardInterrupt:
            pass
    do_l = do_list

1089 1090 1091 1092 1093 1094 1095
    def do_longlist(self, arg):
        """longlist | ll
        List the whole source code for the current function or frame.
        """
        filename = self.curframe.f_code.co_filename
        breaklist = self.get_file_breaks(filename)
        try:
1096
            lines, lineno = getsourcelines(self.curframe)
1097 1098 1099
        except IOError as err:
            self.error(err)
            return
1100
        self._print_lines(lines, lineno, breaklist, self.curframe)
1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111
    do_ll = do_longlist

    def do_source(self, arg):
        """source expression
        Try to get source code for the given object and display it.
        """
        try:
            obj = self._getval(arg)
        except:
            return
        try:
1112
            lines, lineno = getsourcelines(obj)
1113 1114 1115
        except (IOError, TypeError) as err:
            self.error(err)
            return
1116
        self._print_lines(lines, lineno)
1117

1118
    def _print_lines(self, lines, start, breaks=(), frame=None):
1119
        """Print a range of lines."""
1120 1121 1122 1123 1124
        if frame:
            current_lineno = frame.f_lineno
            exc_lineno = self.tb_lineno.get(frame, -1)
        else:
            current_lineno = exc_lineno = -1
1125 1126 1127 1128 1129 1130 1131 1132
        for lineno, line in enumerate(lines, start):
            s = str(lineno).rjust(3)
            if len(s) < 4:
                s += ' '
            if lineno in breaks:
                s += 'B'
            else:
                s += ' '
1133
            if lineno == current_lineno:
1134
                s += '->'
1135
            elif lineno == exc_lineno:
1136 1137 1138
                s += '>>'
            self.message(s + '\t' + line.rstrip())

Tim Peters's avatar
Tim Peters committed
1139
    def do_whatis(self, arg):
1140 1141 1142
        """whatis arg
        Print the type of the argument.
        """
Tim Peters's avatar
Tim Peters committed
1143
        try:
1144
            value = self._getval(arg)
Tim Peters's avatar
Tim Peters committed
1145
        except:
1146
            # _getval() already printed the error
Tim Peters's avatar
Tim Peters committed
1147 1148 1149
            return
        code = None
        # Is it a function?
1150 1151 1152 1153
        try:
            code = value.__code__
        except Exception:
            pass
Tim Peters's avatar
Tim Peters committed
1154
        if code:
1155
            self.message('Function %s' % code.co_name)
Tim Peters's avatar
Tim Peters committed
1156 1157
            return
        # Is it an instance method?
1158 1159 1160 1161
        try:
            code = value.__func__.__code__
        except Exception:
            pass
Tim Peters's avatar
Tim Peters committed
1162
        if code:
1163 1164 1165 1166 1167
            self.message('Method %s' % code.co_name)
            return
        # Is it a class?
        if value.__class__ is type:
            self.message('Class %s.%s' % (value.__module__, value.__name__))
Tim Peters's avatar
Tim Peters committed
1168 1169
            return
        # None of the above...
1170
        self.message(type(value))
Tim Peters's avatar
Tim Peters committed
1171 1172

    def do_alias(self, arg):
1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195
        """alias [name [command [parameter parameter ...] ]]
        Create an alias called 'name' that executes 'command'.  The
        command must *not* be enclosed in quotes.  Replaceable
        parameters can be indicated by %1, %2, and so on, while %* is
        replaced by all the parameters.  If no command is given, the
        current alias for name is shown. If no name is given, all
        aliases are listed.

        Aliases may be nested and can contain anything that can be
        legally typed at the pdb prompt.  Note!  You *can* override
        internal pdb commands with aliases!  Those internal commands
        are then hidden until the alias is removed.  Aliasing is
        recursively applied to the first word of the command line; all
        other words in the line are left alone.

        As an example, here are two useful aliases (especially when
        placed in the .pdbrc file):

        # Print instance variables (usage "pi classInst")
        alias pi for k in %1.__dict__.keys(): print "%1.",k,"=",%1.__dict__[k]
        # Print instance variables in self
        alias ps pi self
        """
Eric S. Raymond's avatar
Eric S. Raymond committed
1196
        args = arg.split()
Tim Peters's avatar
Tim Peters committed
1197
        if len(args) == 0:
1198
            keys = sorted(self.aliases.keys())
Tim Peters's avatar
Tim Peters committed
1199
            for alias in keys:
1200
                self.message("%s = %s" % (alias, self.aliases[alias]))
Tim Peters's avatar
Tim Peters committed
1201
            return
1202
        if args[0] in self.aliases and len(args) == 1:
1203
            self.message("%s = %s" % (args[0], self.aliases[args[0]]))
Tim Peters's avatar
Tim Peters committed
1204
        else:
Eric S. Raymond's avatar
Eric S. Raymond committed
1205
            self.aliases[args[0]] = ' '.join(args[1:])
Tim Peters's avatar
Tim Peters committed
1206 1207

    def do_unalias(self, arg):
1208 1209 1210
        """unalias name
        Delete the specified alias.
        """
Eric S. Raymond's avatar
Eric S. Raymond committed
1211
        args = arg.split()
Tim Peters's avatar
Tim Peters committed
1212
        if len(args) == 0: return
1213
        if args[0] in self.aliases:
Tim Peters's avatar
Tim Peters committed
1214 1215
            del self.aliases[args[0]]

1216
    # List of all the commands making the program resume execution.
1217 1218
    commands_resuming = ['do_continue', 'do_step', 'do_next', 'do_return',
                         'do_quit', 'do_jump']
1219

Tim Peters's avatar
Tim Peters committed
1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237
    # Print a traceback starting at the top stack frame.
    # The most recently entered frame is printed last;
    # this is different from dbx and gdb, but consistent with
    # the Python interpreter's stack trace.
    # It is also consistent with the up/down commands (which are
    # compatible with dbx and gdb: up moves towards 'main()'
    # and down moves towards the most recent stack frame).

    def print_stack_trace(self):
        try:
            for frame_lineno in self.stack:
                self.print_stack_entry(frame_lineno)
        except KeyboardInterrupt:
            pass

    def print_stack_entry(self, frame_lineno, prompt_prefix=line_prefix):
        frame, lineno = frame_lineno
        if frame is self.curframe:
1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262
            prefix = '> '
        else:
            prefix = '  '
        self.message(prefix +
                     self.format_stack_entry(frame_lineno, prompt_prefix))

    # Provide help

    def do_help(self, arg):
        """h(elp)
        Without argument, print the list of available commands.
        With a command name as argument, print help about that command.
        "help pdb" shows the full pdb documentation.
        "help exec" gives help on the ! command.
        """
        if not arg:
            return cmd.Cmd.do_help(self, arg)
        try:
            try:
                topic = getattr(self, 'help_' + arg)
                return topic()
            except AttributeError:
                command = getattr(self, 'do_' + arg)
        except AttributeError:
            self.error('No help for %r' % arg)
Tim Peters's avatar
Tim Peters committed
1263
        else:
1264 1265 1266
            self.message(command.__doc__.rstrip())

    do_h = do_help
1267

Tim Peters's avatar
Tim Peters committed
1268
    def help_exec(self):
1269 1270 1271 1272 1273 1274 1275 1276 1277 1278
        """(!) 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)
        """
        self.message(self.help_exec.__doc__.strip())
1279

Tim Peters's avatar
Tim Peters committed
1280 1281 1282
    def help_pdb(self):
        help()

1283 1284
    # other helper functions

Tim Peters's avatar
Tim Peters committed
1285
    def lookupmodule(self, filename):
1286 1287 1288 1289 1290 1291
        """Helper function for break/clear parsing -- may be overridden.

        lookupmodule() translates (possibly incomplete) file or module name
        into an absolute file name.
        """
        if os.path.isabs(filename) and  os.path.exists(filename):
Tim Peters's avatar
Tim Peters committed
1292
            return filename
1293 1294 1295
        f = os.path.join(sys.path[0], filename)
        if  os.path.exists(f) and self.canonic(f) == self.mainpyfile:
            return f
Tim Peters's avatar
Tim Peters committed
1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307
        root, ext = os.path.splitext(filename)
        if ext == '':
            filename = filename + '.py'
        if os.path.isabs(filename):
            return filename
        for dirname in sys.path:
            while os.path.islink(dirname):
                dirname = os.readlink(dirname)
            fullname = os.path.join(dirname, filename)
            if os.path.exists(fullname):
                return fullname
        return None
1308

1309
    def _runscript(self, filename):
1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320
        # The script has to run in __main__ namespace (or imports from
        # __main__ will break).
        #
        # So we clear up the __main__ and set several special variables
        # (this gets rid of pdb's globals and cleans old variables on restarts).
        import __main__
        __main__.__dict__.clear()
        __main__.__dict__.update({"__name__"    : "__main__",
                                  "__file__"    : filename,
                                  "__builtins__": __builtins__,
                                 })
1321 1322 1323 1324 1325 1326 1327 1328 1329

        # When bdb sets tracing, a number of call and line events happens
        # BEFORE debugger even reaches user's code (and the exact sequence of
        # events depends on python version). So we take special measures to
        # avoid stopping before we reach the main script (see user_line and
        # user_call for details).
        self._wait_for_mainpyfile = 1
        self.mainpyfile = self.canonic(filename)
        self._user_requested_quit = 0
1330 1331 1332
        with open(filename, "rb") as fp:
            statement = "exec(compile(%r, %r, 'exec'))" % \
                        (fp.read(), self.mainpyfile)
1333
        self.run(statement)
1334

1335 1336 1337 1338 1339 1340
# Collect all command help into docstring

# unfortunately we can't guess this order from the class definition
_help_order = [
    'help', 'where', 'down', 'up', 'break', 'tbreak', 'clear', 'disable',
    'enable', 'ignore', 'condition', 'commands', 'step', 'next', 'until',
1341 1342 1343
    'jump', 'return', 'retval', 'run', 'continue', 'list', 'longlist',
    'args', 'print', 'pp', 'whatis', 'source', 'alias', 'unalias',
    'debug', 'quit',
1344 1345
]

1346
docs = set()
1347 1348 1349 1350 1351 1352
for _command in _help_order:
    __doc__ += getattr(Pdb, 'do_' + _command).__doc__.strip() + '\n\n'
__doc__ += Pdb.help_exec.__doc__

del _help_order, _command

1353 1354
# Simplified interface

1355
def run(statement, globals=None, locals=None):
Tim Peters's avatar
Tim Peters committed
1356
    Pdb().run(statement, globals, locals)
1357 1358

def runeval(expression, globals=None, locals=None):
Tim Peters's avatar
Tim Peters committed
1359
    return Pdb().runeval(expression, globals, locals)
1360 1361

def runctx(statement, globals, locals):
Tim Peters's avatar
Tim Peters committed
1362 1363
    # B/W compatibility
    run(statement, globals, locals)
1364

1365 1366
def runcall(*args, **kwds):
    return Pdb().runcall(*args, **kwds)
1367

1368
def set_trace():
1369
    Pdb().set_trace(sys._getframe().f_back)
1370 1371 1372

# Post-Mortem interface

Christian Heimes's avatar
Christian Heimes committed
1373 1374 1375 1376 1377 1378
def post_mortem(t=None):
    # handling the default
    if t is None:
        # sys.exc_info() returns (type, value, traceback) if an exception is
        # being handled, otherwise it returns None
        t = sys.exc_info()[2]
1379 1380 1381
    if t is None:
        raise ValueError("A valid traceback must be passed if no "
                         "exception is being handled")
Christian Heimes's avatar
Christian Heimes committed
1382

Tim Peters's avatar
Tim Peters committed
1383 1384
    p = Pdb()
    p.reset()
Benjamin Peterson's avatar
Benjamin Peterson committed
1385
    p.interaction(None, t)
1386 1387

def pm():
Tim Peters's avatar
Tim Peters committed
1388
    post_mortem(sys.last_traceback)
1389 1390 1391 1392


# Main program for testing

1393
TESTCMD = 'import x; x.main()'
1394

Guido van Rossum's avatar
Guido van Rossum committed
1395
def test():
Tim Peters's avatar
Tim Peters committed
1396
    run(TESTCMD)
1397 1398 1399

# print help
def help():
1400 1401
    import pydoc
    pydoc.pager(__doc__)
1402

1403 1404 1405 1406 1407 1408 1409 1410 1411 1412
_usage = """\
usage: pdb.py [-c command] ... pyfile [arg] ...

Debug the Python program given by pyfile.

Initial commands are read from .pdbrc files in your home directory
and in the current directory, if they exist.  Commands supplied with
-c are executed after commands from .pdbrc files.

To let the script run until an exception occurs, use "-c continue".
1413 1414
To let the script run up to a given line X in the debugged file, use
"-c 'until X'"."""
1415

1416
def main():
1417 1418 1419 1420 1421 1422
    import getopt

    opts, args = getopt.getopt(sys.argv[1:], 'hc:', ['--help', '--command='])

    if not args:
        print(_usage)
Tim Peters's avatar
Tim Peters committed
1423
        sys.exit(2)
1424

1425 1426 1427 1428 1429 1430 1431 1432 1433
    commands = []
    for opt, optarg in opts:
        if opt in ['-h', '--help']:
            print(_usage)
            sys.exit()
        elif opt in ['-c', '--command']:
            commands.append(optarg)

    mainpyfile = args[0]     # Get script filename
1434
    if not os.path.exists(mainpyfile):
1435
        print('Error:', mainpyfile, 'does not exist')
Tim Peters's avatar
Tim Peters committed
1436
        sys.exit(1)
1437

1438
    sys.argv[:] = args      # Hide "pdb.py" and pdb options from argument list
1439

1440 1441
    # Replace pdb's dir with script's dir in front of module search path.
    sys.path[0] = os.path.dirname(mainpyfile)
1442

1443 1444
    # Note on saving/restoring sys.argv: it's a good idea when sys.argv was
    # modified by the script being debugged. It's a bad idea when it was
1445 1446
    # changed by the user from the command line. There is a "restart" command
    # which allows explicit specification of command line arguments.
1447
    pdb = Pdb()
1448
    pdb.rcLines.extend(commands)
1449
    while True:
1450 1451 1452 1453
        try:
            pdb._runscript(mainpyfile)
            if pdb._user_requested_quit:
                break
1454
            print("The program finished and will be restarted")
1455 1456
        except Restart:
            print("Restarting", mainpyfile, "with arguments:")
1457
            print("\t" + " ".join(args))
1458 1459
        except SystemExit:
            # In most cases SystemExit does not warrant a post-mortem session.
1460
            print("The program exited via sys.exit(). Exit status:", end=' ')
1461
            print(sys.exc_info()[1])
1462 1463
        except:
            traceback.print_exc()
1464 1465
            print("Uncaught exception. Entering post mortem debugging")
            print("Running 'cont' or 'step' will restart the program")
1466
            t = sys.exc_info()[2]
Benjamin Peterson's avatar
Benjamin Peterson committed
1467
            pdb.interaction(None, t)
1468 1469
            print("Post mortem debugger finished. The " + mainpyfile +
                  " will be restarted")
1470 1471 1472


# When invoked as main program, invoke the debugger on a script
1473 1474 1475
if __name__ == '__main__':
    import pdb
    pdb.main()