Pycopia enhanced debugger package

Provides a debugger that utilizes the pycopia CLI toolkit to provide a nicer user experience. It also adds new commands.

The pycopia.autodebug module is special. You don’t actually use anything from it. But simply importing it will set up the Python interpreter to enter the debugger on any uncaught exception. Rather than get a plain stack trace and exiting, you have a change to inspect the program.

This is usually used in module self-test code, like this:

if __name__ == "__main__":
    from pycopia import autodebug
    # some self test
    # ...


Like the standard debugger, but inherits CLI toolkit functionality such as aliases, shell escapes, history. You can also invoke your text editor on the current line.

Debugger that can be used instead of the pdb module. This one provides a nicer command interface by using the CLI module.

class pycopia.debugger.Debugger(skip=None, io=None)[source]

Produce a reasonable default.

interaction(frame, traceback)[source]
print_exc(ex, val)[source]
set_trace(frame=None, start=0)[source]

Start debugging from frame, or start frames back from caller’s frame. If frame is not specified, debugging starts from caller’s frame.

setup(f, t)[source]
user_call(frame, argument_list)[source]

This method is called when there is the remote possibility that we ever need to stop in this function.

user_exception(frame, exc_tuple)[source]

This function is called if an exception occurs, but only if we are to stop at or just below this level.


This function is called when we stop or break at this line.

user_return(frame, return_value)[source]

This function is called when a return trap is set here.

class pycopia.debugger.DebuggerCommands(ui, aliases=None)[source]

Print <expression> Print the value of the expression.


Print the arguments of the current function.


where 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.


brk [-t] [breakpoint] ([file:]lineno | function) [, condition] With a line number argument, set a break there in the current file. With a function name, set a break at first executable line of that function. Without argument, list all breaks. 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.


clear ... Three possibilities, tried in this order: clear -> clear all breaks, ask for confirmation clear file:lineno -> clear all breaks at file:lineno clear bpno bpno ... -> clear breakpoints by number

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.

Note that the argument is different from previous versions of the debugger (in python distributions 1.5.1 and before) where a linenumber was used instead of either filename:lineno or breakpoint numbers.


condition bpnumber str_condition str_condition is a string specifying an expression which must evaluate to true before the breakpoint is honored. If str_condition is absent, any existing condition is removed; i.e., the breakpoint is made unconditional.


Continue execution, only stop when a breakpoint is encountered.


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).


disable bpnumber [bpnumber ...] Disables the breakpoints given as a space separated list of bp numbers.


Display the full documentation for the debugger.


Move the current frame one level down in the stack trace (to an older frame).


Open your editor at the current location.


enable bpnumber [bpnumber ...] Enables the breakpoints given as a space separated list of bp numbers.


execute <statement> Execute <statement> in current frame context.


ignore bpnumber count Sets the ignore count for the given breakpoint number. 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.


jump lineno Set the next line that will be executed.


list [first [,last]] List source code for the current file. Without arguments, list 20 lines around the current line or continue the previous listing. With one argument, list 20 lines centered at that line. With two arguments, list the given range; if the second argument is less than the first, it is a count.


Continue execution until the next line in the current function is reached or it returns.


quit or exit - Quit from the debugger. The program being executed is aborted.


Continue execution until the current function returns.


Show return value.


search <pattern> Search the source file for the regular expression pattern.


show [<name>...] Shows the current frame’s object and values. If parameter names are given then show only those local names.


Execute the current line, stop at the first possible occasion (either in a function that is called or in the current function).


Move the current frame one level up in the stack trace (to a newer frame).


whatis arg Prints the type of the argument.


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.

class pycopia.debugger.DebuggerParser(cmdobj=None, logfile=None, historyfile=None)[source]
class pycopia.debugger.DebuggerTheme(ps1='> ', ps2='more> ', ps3='choose', ps4='-> ')[source]
pycopia.debugger.checkline(filename, lineno, ui)[source]

Return line number of first line at or after input argument such that if the input points to a ‘def’, the returned line number is the first non-blank/non-comment line to follow. If the input points to a blank or comment line, return 0. At end of file, also return 0.

pycopia.debugger.debug(method, *args, **kwargs)[source]

Run the method and debug any exception, except syntax or user interrupt.

pycopia.debugger.find_function(funcname, filename)[source][source]

Helper function for break/clear parsing.[source]

Start debugging with the system’s last traceback.

pycopia.debugger.post_mortem(t, exc=None, val=None, io=None)[source]

Start debugging at the given traceback., globals=None, locals=None)[source]
pycopia.debugger.run_editor(fname, lineno)[source]
pycopia.debugger.runeval(expression, globals=None, locals=None)[source]
pycopia.debugger.set_trace(frame=None, start=0)[source]

Table Of Contents

Previous topic

Pycopia CLI toolkit

Next topic

Pycopia Process package