1 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 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451
|
The Extended Python Debugger Pydb
=======================
To use the debugger in its simplest form:
>>> import pydb
>>> pydb.run('<a statement>')
The debugger's prompt is '(Pydb) '. This will stop in the first
function call in <a statement>.
Alternatively, if a statement terminated with an unhandled exception,
you can use pydb's post-mortem facility to inspect the contents of the
traceback:
>>> <a statement>
<exception traceback>
>>> import pydb
>>> pydb.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.
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. 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 ".pydbrc" 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
=================
($) 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.:
(Pydb) global list_options; list_options = ['-l']
(Pydb)
alias [name [command]]
Creates 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 pydb prompt. Note! You *can* override
internal pydb 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 .pydbrc 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
b(reak) [ ([filename:]lineno | function) [, condition] ]
Without an argument, use the current point stopped in the
program.
With a filename:line number argument, set a break there. If
filename is omitted, use the current file. With a function
name, set a break at the first executable line of that
function.
Each breakpoint is assigned a number to which all the other
breakpoint commands refer. Multiple breakpoints at one place
are permitted, and useful with conditional arguments.
The condition argument, if present, is a string which must
evaluate to true in order for the breakpoint to be honored.
cd DIRECTORY
Set working directory to DIRECTORY for debugger and program
being debugged.
cl(ear) {[file:]linenumber | function}
Clear breakpoint at specified line or function.
Argument may be line number, function name, or "*" and an
address. If line number is specified, all breakpoints in that
line are cleared. If function is specified, breakpoints at
beginning of function are cleared. If an address is
specified, breakpoints at what address are cleared.
With no argument, clears all breakpoints in the line that the
selected frame is executing in.
See also the 'delete' command which clears breakpoints by number.
complete cmd-prefix
Print a list of commands names that start with cmd-prefix.
This is command is only availaible if readline supports it.
condition bpnumber condition
condition is 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.
c(ontinue)
Continue execution, only stop when a breakpoint is encountered.
commands [bpnumber]
>...
>end
(Pydb)
Set commands to be executed when a breakpoint is hit.
Give breakpoint number as the argument after "commands".
With no bpnumber argument, commands refers to the last one set.
The commands themselves follow starting on the next line.
Type a line containing "end" to terminate the commands.
To remove all commands from a breakpoint, type commands and
follow it immediately with end; that is, give no commands.
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, and quit) 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 see no sign that the breakpoint
was reached.
delete [bpnumber [bpnumber...]]
Delete some breakpoints. Arguments are breakpoint numbers
with spaces in between. To delete all breakpoints, give no
argument. those breakpoints. Without argument, clear all
breaks (but first ask confirmation).
See also the 'clear' command which clears breakpoints by
line/file number..
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.
disassemble [arg]
With no argument disassemble at the current frame location.
With a numeric argument, disassemble at the frame location at that
line number. With a class, method, function or code argument
disassemble that.
display [format] EXP
Print value of expression EXP each time the program stops.
FMT may be used before EXP and may be one of 'c' for char,
'x' for hex, 'o' for ocatl, 'f' for float or 's' for string.
With no argument, display all currently requested auto-display
expressions. Use "undisplay" to cancel display requests previously
made.
down [count]
Move the current frame one level down in the stack trace
(to a newer frame). With a count, which can be a positive
or a negative value, move that many positions.
enable bpnumber [bpnumber ...]
Enables the breakpoints specified.
examine expression
Print the type of the expression and prettyprint its value.
Alias is x (same as in Perl).
finish
Continue execution until the current function returns.
At that point the retval command can be used to show the
return value.
frame position
Move the current frame to the specified frame number. A negative
number indicates position from the end, so "frame -1" moves to
the newest frame, and "frame 0" moves to the oldest frame.
h(elp)
Without an argument, print the list of available commands. With
a command name as argument, print help about that command
(this is currently not implemented).
ignore bpnumber count
Sets 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.
i(nfo) [suboption]
In general, shows information about the program being debugged.
Without argument, print the list of available info commands.
With an argument, print info about that command. Suboptions follow:
Without argument, print the list of available info commands.
With an argument, print info about that command. Suboptions follow:
info args -- Argument variables of current stack frame
info break -- Status of user-settable breakpoints
info display -- Expressions to display when program stops,
with code numbers.
info globals -- Global variables of current stack frame
info line -- Current line number in source file. If a function name is
given the starting line of the function is reported.
info locals -- Local variables of current stack frame
info program -- Execution status of the program
info source -- Information about the current Python file
jump lineno
Set the next line that will be executed.
l(ist) [- | first [last or count]]
List source code. Without arguments, list LISTSIZE lines
centered around the current line or continue the previous
listing. "list -" lists LISTSIZE lines before a previous
listing. With one argument other than "-", list LISTSIZE lines
centered around the specified position. With two arguments,
list the given range; if the second argument is less than the
first, it is a count. First and last can be either a function
name, a line number or file:line
n(ext) [count]
Continue execution until the next line in the current function
is reached or it returns. The difference between next and step
is that step stops inside a called function, while next
executes called functions at (nearly) full speed, only
stopping at the next line in the current function.
p expression
Print the value of the expression.
pp expression
Prettyprint the value of the expression.
pwd
Print working directory.
q(uit)
Quit the debugger. The program being executed is aborted. For
now, kill is a synonym for quit.
restart
Restart debugger and program via an exec call. All state
is lost, and new copy of the debugger is used.
Sometimes in debugging it is necessary to modify module code
when one finds a bugs in them. Python will not notice
dynamically that a module has changed and thus not reimport
, so in such a situation one must use "restart" rather than
"run".
return
Make selected stack frame return to its caller. Control
remains in the debugger, but when you continue execution will
resume at the return statement found inside the subroutine or
method. At present we are only able to perform this if we are
in a subroutine that has a 'return' statement in it.
See also retval and finish.
retval
Show the value that is to be returned from a function.
This command is useful after a "finish" command or stepping just
after a "return" statement. To change the value, make an
assignment to the variable __return__.
The short command name is rv.
See also finish and return.
run [args...]
Run (or restart the debugged python program. If a string is
supplied that becomes the new command arguments.
History, breakpoints, actions nd debugger options are
preserved. ' R' is a short command alias for run.
Note that there may be situations where "run" doesn't have the
effect you want and you may have to use "restart" instead. See
restart for more info.
set *subcommand*
In general sets the debugger environment.
With a subcommand, this command modifies parts of the debugger
environment. You can see these environment settings with the
"show" command.
set args *arg*...
Set argument list to give program being debugged when it is
started. Follow this command with any number of args, to be passed
to the program. Set number of source lines debugger will list by
default.
set history filename
Set the filename in which to record the command history
set history save
Set saving of the history record on exit
set history size
Set the size of the command history
set linetrace {on|off}
Set line execution tracing. If 'on', lines will be shown before they
are run.
set linetrace delay *float*
Set delay after listing a line. This only has an effect if linetrace
is in effect. This is useful if tracing inside a GUI that is displaying
the position in the source text. A value like 0.5 is probably sufficient.
set listsize *int*
Set number of source lines debugger will list by default.
set logging on
set logging off
set logging file FILENAME
set logging overwrite [on|off]
set logging redirect [on|off]
set prompt *string*
Set debugger's prompt
show *subcommand*
Generic command for showing things about the debugger.
show args -- Show argument list to give program being debugged when
it is started
show cmdtrace -- Show if we are to show debugger commands before running
show commands -- Show the history of commands you typed.
This command Is available only if the readline module available
and supports the history saving.
show history -- Generic command for showing command history parameters
show interactive -- Show if we are interactive or not
show linetrace -- Show the line tracing status
show listsize -- Show number of source lines gdb will list by
default
show prompt -- Show the current debugger prompt
show version -- Show what version of this is
source FILE
Read commands from a file named FILE.
Note that the file '.pydbrc' is read automatically
in this way when pydb is started.
An error in any command terminates execution of the command
file and control is returned to the console.
For tracking down problems with command files, see the "set
cmdtrace on" debugger command.
s(tep) [count]
Execute the current line, stop at the first possible occasion
(either in a function that is called or in the current function).
tbreak [ ([filename:]lineno | function) [, condition] ]
Set a temporary breakpoint. Arguments are like the "break" command.
Like "break" except the breakoint is only temporary,
so it will be deleted when hit.
unalias name
Deletes the specified alias.
undisplay
Cancel some expressions to be displayed when program stops.
Arguments are the code numbers of the expressions to stop displaying.
No argument means cancel all automatic-display expressions.
"delete display" has the same effect as this command.
Do "info display" to see current list of code numbers.
up [count]
Move the current frame one level up in the stack trace
(to an older frame). With a count, which can be a positive
or a negative value, move that many positions.
whatis arg
Prints the type of the argument.
where [count]
Print a stack trace, with the most recent frame at the bottom.
With a positive number, print at most many entries.
An arrow indicates the "current frame", which determines the
context of most commands. bt and T are short command names for
this.
|