-:mod:`bdb` --- Debugger framework\r
-=================================\r
-\r
-.. module:: bdb\r
- :synopsis: Debugger framework.\r
-\r
-The :mod:`bdb` module handles basic debugger functions, like setting breakpoints\r
-or managing execution via the debugger.\r
-\r
-The following exception is defined:\r
-\r
-.. exception:: BdbQuit\r
-\r
- Exception raised by the :class:`Bdb` class for quitting the debugger.\r
-\r
-\r
-The :mod:`bdb` module also defines two classes:\r
-\r
-.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])\r
-\r
- This class implements temporary breakpoints, ignore counts, disabling and\r
- (re-)enabling, and conditionals.\r
-\r
- Breakpoints are indexed by number through a list called :attr:`bpbynumber`\r
- and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a\r
- single instance of class :class:`Breakpoint`. The latter points to a list of\r
- such instances since there may be more than one breakpoint per line.\r
-\r
- When creating a breakpoint, its associated filename should be in canonical\r
- form. If a *funcname* is defined, a breakpoint hit will be counted when the\r
- first line of that function is executed. A conditional breakpoint always\r
- counts a hit.\r
-\r
-:class:`Breakpoint` instances have the following methods:\r
-\r
-.. method:: Breakpoint.deleteMe()\r
-\r
- Delete the breakpoint from the list associated to a file/line. If it is the\r
- last breakpoint in that position, it also deletes the entry for the\r
- file/line.\r
-\r
-.. method:: Breakpoint.enable()\r
-\r
- Mark the breakpoint as enabled.\r
-\r
-.. method:: Breakpoint.disable()\r
-\r
- Mark the breakpoint as disabled.\r
-\r
-.. method:: Breakpoint.bpprint([out])\r
-\r
- Print all the information about the breakpoint:\r
-\r
- * The breakpoint number.\r
- * If it is temporary or not.\r
- * Its file,line position.\r
- * The condition that causes a break.\r
- * If it must be ignored the next N times.\r
- * The breakpoint hit count.\r
-\r
-\r
-.. class:: Bdb()\r
-\r
- The :class:`Bdb` acts as a generic Python debugger base class.\r
-\r
- This class takes care of the details of the trace facility; a derived class\r
- should implement user interaction. The standard debugger class\r
- (:class:`pdb.Pdb`) is an example.\r
-\r
-\r
-The following methods of :class:`Bdb` normally don't need to be overridden.\r
-\r
-.. method:: Bdb.canonic(filename)\r
-\r
- Auxiliary method for getting a filename in a canonical form, that is, as a\r
- case-normalized (on case-insensitive filesystems) absolute path, stripped\r
- of surrounding angle brackets.\r
-\r
-.. method:: Bdb.reset()\r
-\r
- Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and\r
- :attr:`quitting` attributes with values ready to start debugging.\r
-\r
-\r
-.. method:: Bdb.trace_dispatch(frame, event, arg)\r
-\r
- This function is installed as the trace function of debugged frames. Its\r
- return value is the new trace function (in most cases, that is, itself).\r
-\r
- The default implementation decides how to dispatch a frame, depending on the\r
- type of event (passed as a string) that is about to be executed. *event* can\r
- be one of the following:\r
-\r
- * ``"line"``: A new line of code is going to be executed.\r
- * ``"call"``: A function is about to be called, or another code block\r
- entered.\r
- * ``"return"``: A function or other code block is about to return.\r
- * ``"exception"``: An exception has occurred.\r
- * ``"c_call"``: A C function is about to be called.\r
- * ``"c_return"``: A C function has returned.\r
- * ``"c_exception"``: A C function has thrown an exception.\r
-\r
- For the Python events, specialized functions (see below) are called. For the\r
- C events, no action is taken.\r
-\r
- The *arg* parameter depends on the previous event.\r
-\r
- For more information on trace functions, see :ref:`debugger-hooks`. For more\r
- information on code and frame objects, refer to :ref:`types`.\r
-\r
-.. method:: Bdb.dispatch_line(frame)\r
-\r
- If the debugger should stop on the current line, invoke the :meth:`user_line`\r
- method (which should be overridden in subclasses). Raise a :exc:`BdbQuit`\r
- exception if the :attr:`Bdb.quitting` flag is set (which can be set from\r
- :meth:`user_line`). Return a reference to the :meth:`trace_dispatch` method\r
- for further tracing in that scope.\r
-\r
-.. method:: Bdb.dispatch_call(frame, arg)\r
-\r
- If the debugger should stop on this function call, invoke the\r
- :meth:`user_call` method (which should be overridden in subclasses). Raise a\r
- :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can\r
- be set from :meth:`user_call`). Return a reference to the\r
- :meth:`trace_dispatch` method for further tracing in that scope.\r
-\r
-.. method:: Bdb.dispatch_return(frame, arg)\r
-\r
- If the debugger should stop on this function return, invoke the\r
- :meth:`user_return` method (which should be overridden in subclasses). Raise\r
- a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can\r
- be set from :meth:`user_return`). Return a reference to the\r
- :meth:`trace_dispatch` method for further tracing in that scope.\r
-\r
-.. method:: Bdb.dispatch_exception(frame, arg)\r
-\r
- If the debugger should stop at this exception, invokes the\r
- :meth:`user_exception` method (which should be overridden in subclasses).\r
- Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set\r
- (which can be set from :meth:`user_exception`). Return a reference to the\r
- :meth:`trace_dispatch` method for further tracing in that scope.\r
-\r
-Normally derived classes don't override the following methods, but they may if\r
-they want to redefine the definition of stopping and breakpoints.\r
-\r
-.. method:: Bdb.stop_here(frame)\r
-\r
- This method checks if the *frame* is somewhere below :attr:`botframe` in the\r
- call stack. :attr:`botframe` is the frame in which debugging started.\r
-\r
-.. method:: Bdb.break_here(frame)\r
-\r
- This method checks if there is a breakpoint in the filename and line\r
- belonging to *frame* or, at least, in the current function. If the\r
- breakpoint is a temporary one, this method deletes it.\r
-\r
-.. method:: Bdb.break_anywhere(frame)\r
-\r
- This method checks if there is a breakpoint in the filename of the current\r
- frame.\r
-\r
-Derived classes should override these methods to gain control over debugger\r
-operation.\r
-\r
-.. method:: Bdb.user_call(frame, argument_list)\r
-\r
- This method is called from :meth:`dispatch_call` when there is the\r
- possibility that a break might be necessary anywhere inside the called\r
- function.\r
-\r
-.. method:: Bdb.user_line(frame)\r
-\r
- This method is called from :meth:`dispatch_line` when either\r
- :meth:`stop_here` or :meth:`break_here` yields True.\r
-\r
-.. method:: Bdb.user_return(frame, return_value)\r
-\r
- This method is called from :meth:`dispatch_return` when :meth:`stop_here`\r
- yields True.\r
-\r
-.. method:: Bdb.user_exception(frame, exc_info)\r
-\r
- This method is called from :meth:`dispatch_exception` when :meth:`stop_here`\r
- yields True.\r
-\r
-.. method:: Bdb.do_clear(arg)\r
-\r
- Handle how a breakpoint must be removed when it is a temporary one.\r
-\r
- This method must be implemented by derived classes.\r
-\r
-\r
-Derived classes and clients can call the following methods to affect the \r
-stepping state.\r
-\r
-.. method:: Bdb.set_step()\r
-\r
- Stop after one line of code.\r
-\r
-.. method:: Bdb.set_next(frame)\r
-\r
- Stop on the next line in or below the given frame.\r
-\r
-.. method:: Bdb.set_return(frame)\r
-\r
- Stop when returning from the given frame.\r
-\r
-.. method:: Bdb.set_trace([frame])\r
-\r
- Start debugging from *frame*. If *frame* is not specified, debugging starts\r
- from caller's frame.\r
-\r
-.. method:: Bdb.set_continue()\r
-\r
- Stop only at breakpoints or when finished. If there are no breakpoints, set\r
- the system trace function to None.\r
-\r
-.. method:: Bdb.set_quit()\r
-\r
- Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in\r
- the next call to one of the :meth:`dispatch_\*` methods.\r
-\r
-\r
-Derived classes and clients can call the following methods to manipulate\r
-breakpoints. These methods return a string containing an error message if\r
-something went wrong, or ``None`` if all is well.\r
-\r
-.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]])\r
-\r
- Set a new breakpoint. If the *lineno* line doesn't exist for the *filename*\r
- passed as argument, return an error message. The *filename* should be in\r
- canonical form, as described in the :meth:`canonic` method.\r
-\r
-.. method:: Bdb.clear_break(filename, lineno)\r
-\r
- Delete the breakpoints in *filename* and *lineno*. If none were set, an\r
- error message is returned.\r
-\r
-.. method:: Bdb.clear_bpbynumber(arg)\r
-\r
- Delete the breakpoint which has the index *arg* in the\r
- :attr:`Breakpoint.bpbynumber`. If `arg` is not numeric or out of range,\r
- return an error message.\r
-\r
-.. method:: Bdb.clear_all_file_breaks(filename)\r
-\r
- Delete all breakpoints in *filename*. If none were set, an error message is\r
- returned.\r
-\r
-.. method:: Bdb.clear_all_breaks()\r
-\r
- Delete all existing breakpoints.\r
-\r
-.. method:: Bdb.get_break(filename, lineno)\r
-\r
- Check if there is a breakpoint for *lineno* of *filename*.\r
-\r
-.. method:: Bdb.get_breaks(filename, lineno)\r
-\r
- Return all breakpoints for *lineno* in *filename*, or an empty list if none\r
- are set.\r
-\r
-.. method:: Bdb.get_file_breaks(filename)\r
-\r
- Return all breakpoints in *filename*, or an empty list if none are set.\r
-\r
-.. method:: Bdb.get_all_breaks()\r
-\r
- Return all breakpoints that are set.\r
-\r
-\r
-Derived classes and clients can call the following methods to get a data\r
-structure representing a stack trace.\r
-\r
-.. method:: Bdb.get_stack(f, t)\r
-\r
- Get a list of records for a frame and all higher (calling) and lower frames,\r
- and the size of the higher part.\r
-\r
-.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': '])\r
-\r
- Return a string with information about a stack entry, identified by a\r
- ``(frame, lineno)`` tuple:\r
-\r
- * The canonical form of the filename which contains the frame.\r
- * The function name, or ``"<lambda>"``.\r
- * The input arguments.\r
- * The return value.\r
- * The line of code (if it exists).\r
-\r
-\r
-The following two methods can be called by clients to use a debugger to debug a\r
-statement, given as a string.\r
-\r
-.. method:: Bdb.run(cmd, [globals, [locals]])\r
-\r
- Debug a statement executed via the :keyword:`exec` statement. *globals*\r
- defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.\r
-\r
-.. method:: Bdb.runeval(expr, [globals, [locals]])\r
-\r
- Debug an expression executed via the :func:`eval` function. *globals* and\r
- *locals* have the same meaning as in :meth:`run`.\r
-\r
-.. method:: Bdb.runctx(cmd, globals, locals)\r
-\r
- For backwards compatibility. Calls the :meth:`run` method.\r
-\r
-.. method:: Bdb.runcall(func, *args, **kwds)\r
-\r
- Debug a single function call, and return its result.\r
-\r
-\r
-Finally, the module defines the following functions:\r
-\r
-.. function:: checkfuncname(b, frame)\r
-\r
- Check whether we should break here, depending on the way the breakpoint *b*\r
- was set.\r
- \r
- If it was set via line number, it checks if ``b.line`` is the same as the one\r
- in the frame also passed as argument. If the breakpoint was set via function\r
- name, we have to check we are in the right frame (the right function) and if\r
- we are in its first executable line.\r
-\r
-.. function:: effective(file, line, frame)\r
-\r
- Determine if there is an effective (active) breakpoint at this line of code.\r
- Return breakpoint number or 0 if none.\r
- \r
- Called only if we know there is a breakpoint at this location. Returns the\r
- breakpoint that was triggered and a flag that indicates if it is ok to delete\r
- a temporary breakpoint.\r
-\r
-.. function:: set_trace()\r
-\r
- Starts debugging with a :class:`Bdb` instance from caller's frame.\r
+:mod:`bdb` --- Debugger framework
+=================================
+
+.. module:: bdb
+ :synopsis: Debugger framework.
+
+The :mod:`bdb` module handles basic debugger functions, like setting breakpoints
+or managing execution via the debugger.
+
+The following exception is defined:
+
+.. exception:: BdbQuit
+
+ Exception raised by the :class:`Bdb` class for quitting the debugger.
+
+
+The :mod:`bdb` module also defines two classes:
+
+.. class:: Breakpoint(self, file, line[, temporary=0[, cond=None [, funcname=None]]])
+
+ This class implements temporary breakpoints, ignore counts, disabling and
+ (re-)enabling, and conditionals.
+
+ Breakpoints are indexed by number through a list called :attr:`bpbynumber`
+ and by ``(file, line)`` pairs through :attr:`bplist`. The former points to a
+ single instance of class :class:`Breakpoint`. The latter points to a list of
+ such instances since there may be more than one breakpoint per line.
+
+ When creating a breakpoint, its associated filename should be in canonical
+ form. If a *funcname* is defined, a breakpoint hit will be counted when the
+ first line of that function is executed. A conditional breakpoint always
+ counts a hit.
+
+:class:`Breakpoint` instances have the following methods:
+
+.. method:: Breakpoint.deleteMe()
+
+ Delete the breakpoint from the list associated to a file/line. If it is the
+ last breakpoint in that position, it also deletes the entry for the
+ file/line.
+
+.. method:: Breakpoint.enable()
+
+ Mark the breakpoint as enabled.
+
+.. method:: Breakpoint.disable()
+
+ Mark the breakpoint as disabled.
+
+.. method:: Breakpoint.bpprint([out])
+
+ Print all the information about the breakpoint:
+
+ * The breakpoint number.
+ * If it is temporary or not.
+ * Its file,line position.
+ * The condition that causes a break.
+ * If it must be ignored the next N times.
+ * The breakpoint hit count.
+
+
+.. class:: Bdb()
+
+ The :class:`Bdb` acts as a generic Python debugger base class.
+
+ This class takes care of the details of the trace facility; a derived class
+ should implement user interaction. The standard debugger class
+ (:class:`pdb.Pdb`) is an example.
+
+
+The following methods of :class:`Bdb` normally don't need to be overridden.
+
+.. method:: Bdb.canonic(filename)
+
+ Auxiliary method for getting a filename in a canonical form, that is, as a
+ case-normalized (on case-insensitive filesystems) absolute path, stripped
+ of surrounding angle brackets.
+
+.. method:: Bdb.reset()
+
+ Set the :attr:`botframe`, :attr:`stopframe`, :attr:`returnframe` and
+ :attr:`quitting` attributes with values ready to start debugging.
+
+
+.. method:: Bdb.trace_dispatch(frame, event, arg)
+
+ This function is installed as the trace function of debugged frames. Its
+ return value is the new trace function (in most cases, that is, itself).
+
+ The default implementation decides how to dispatch a frame, depending on the
+ type of event (passed as a string) that is about to be executed. *event* can
+ be one of the following:
+
+ * ``"line"``: A new line of code is going to be executed.
+ * ``"call"``: A function is about to be called, or another code block
+ entered.
+ * ``"return"``: A function or other code block is about to return.
+ * ``"exception"``: An exception has occurred.
+ * ``"c_call"``: A C function is about to be called.
+ * ``"c_return"``: A C function has returned.
+ * ``"c_exception"``: A C function has thrown an exception.
+
+ For the Python events, specialized functions (see below) are called. For the
+ C events, no action is taken.
+
+ The *arg* parameter depends on the previous event.
+
+ For more information on trace functions, see :ref:`debugger-hooks`. For more
+ information on code and frame objects, refer to :ref:`types`.
+
+.. method:: Bdb.dispatch_line(frame)
+
+ If the debugger should stop on the current line, invoke the :meth:`user_line`
+ method (which should be overridden in subclasses). Raise a :exc:`BdbQuit`
+ exception if the :attr:`Bdb.quitting` flag is set (which can be set from
+ :meth:`user_line`). Return a reference to the :meth:`trace_dispatch` method
+ for further tracing in that scope.
+
+.. method:: Bdb.dispatch_call(frame, arg)
+
+ If the debugger should stop on this function call, invoke the
+ :meth:`user_call` method (which should be overridden in subclasses). Raise a
+ :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
+ be set from :meth:`user_call`). Return a reference to the
+ :meth:`trace_dispatch` method for further tracing in that scope.
+
+.. method:: Bdb.dispatch_return(frame, arg)
+
+ If the debugger should stop on this function return, invoke the
+ :meth:`user_return` method (which should be overridden in subclasses). Raise
+ a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set (which can
+ be set from :meth:`user_return`). Return a reference to the
+ :meth:`trace_dispatch` method for further tracing in that scope.
+
+.. method:: Bdb.dispatch_exception(frame, arg)
+
+ If the debugger should stop at this exception, invokes the
+ :meth:`user_exception` method (which should be overridden in subclasses).
+ Raise a :exc:`BdbQuit` exception if the :attr:`Bdb.quitting` flag is set
+ (which can be set from :meth:`user_exception`). Return a reference to the
+ :meth:`trace_dispatch` method for further tracing in that scope.
+
+Normally derived classes don't override the following methods, but they may if
+they want to redefine the definition of stopping and breakpoints.
+
+.. method:: Bdb.stop_here(frame)
+
+ This method checks if the *frame* is somewhere below :attr:`botframe` in the
+ call stack. :attr:`botframe` is the frame in which debugging started.
+
+.. method:: Bdb.break_here(frame)
+
+ This method checks if there is a breakpoint in the filename and line
+ belonging to *frame* or, at least, in the current function. If the
+ breakpoint is a temporary one, this method deletes it.
+
+.. method:: Bdb.break_anywhere(frame)
+
+ This method checks if there is a breakpoint in the filename of the current
+ frame.
+
+Derived classes should override these methods to gain control over debugger
+operation.
+
+.. method:: Bdb.user_call(frame, argument_list)
+
+ This method is called from :meth:`dispatch_call` when there is the
+ possibility that a break might be necessary anywhere inside the called
+ function.
+
+.. method:: Bdb.user_line(frame)
+
+ This method is called from :meth:`dispatch_line` when either
+ :meth:`stop_here` or :meth:`break_here` yields True.
+
+.. method:: Bdb.user_return(frame, return_value)
+
+ This method is called from :meth:`dispatch_return` when :meth:`stop_here`
+ yields True.
+
+.. method:: Bdb.user_exception(frame, exc_info)
+
+ This method is called from :meth:`dispatch_exception` when :meth:`stop_here`
+ yields True.
+
+.. method:: Bdb.do_clear(arg)
+
+ Handle how a breakpoint must be removed when it is a temporary one.
+
+ This method must be implemented by derived classes.
+
+
+Derived classes and clients can call the following methods to affect the
+stepping state.
+
+.. method:: Bdb.set_step()
+
+ Stop after one line of code.
+
+.. method:: Bdb.set_next(frame)
+
+ Stop on the next line in or below the given frame.
+
+.. method:: Bdb.set_return(frame)
+
+ Stop when returning from the given frame.
+
+.. method:: Bdb.set_trace([frame])
+
+ Start debugging from *frame*. If *frame* is not specified, debugging starts
+ from caller's frame.
+
+.. method:: Bdb.set_continue()
+
+ Stop only at breakpoints or when finished. If there are no breakpoints, set
+ the system trace function to None.
+
+.. method:: Bdb.set_quit()
+
+ Set the :attr:`quitting` attribute to True. This raises :exc:`BdbQuit` in
+ the next call to one of the :meth:`dispatch_\*` methods.
+
+
+Derived classes and clients can call the following methods to manipulate
+breakpoints. These methods return a string containing an error message if
+something went wrong, or ``None`` if all is well.
+
+.. method:: Bdb.set_break(filename, lineno[, temporary=0[, cond[, funcname]]])
+
+ Set a new breakpoint. If the *lineno* line doesn't exist for the *filename*
+ passed as argument, return an error message. The *filename* should be in
+ canonical form, as described in the :meth:`canonic` method.
+
+.. method:: Bdb.clear_break(filename, lineno)
+
+ Delete the breakpoints in *filename* and *lineno*. If none were set, an
+ error message is returned.
+
+.. method:: Bdb.clear_bpbynumber(arg)
+
+ Delete the breakpoint which has the index *arg* in the
+ :attr:`Breakpoint.bpbynumber`. If `arg` is not numeric or out of range,
+ return an error message.
+
+.. method:: Bdb.clear_all_file_breaks(filename)
+
+ Delete all breakpoints in *filename*. If none were set, an error message is
+ returned.
+
+.. method:: Bdb.clear_all_breaks()
+
+ Delete all existing breakpoints.
+
+.. method:: Bdb.get_break(filename, lineno)
+
+ Check if there is a breakpoint for *lineno* of *filename*.
+
+.. method:: Bdb.get_breaks(filename, lineno)
+
+ Return all breakpoints for *lineno* in *filename*, or an empty list if none
+ are set.
+
+.. method:: Bdb.get_file_breaks(filename)
+
+ Return all breakpoints in *filename*, or an empty list if none are set.
+
+.. method:: Bdb.get_all_breaks()
+
+ Return all breakpoints that are set.
+
+
+Derived classes and clients can call the following methods to get a data
+structure representing a stack trace.
+
+.. method:: Bdb.get_stack(f, t)
+
+ Get a list of records for a frame and all higher (calling) and lower frames,
+ and the size of the higher part.
+
+.. method:: Bdb.format_stack_entry(frame_lineno, [lprefix=': '])
+
+ Return a string with information about a stack entry, identified by a
+ ``(frame, lineno)`` tuple:
+
+ * The canonical form of the filename which contains the frame.
+ * The function name, or ``"<lambda>"``.
+ * The input arguments.
+ * The return value.
+ * The line of code (if it exists).
+
+
+The following two methods can be called by clients to use a debugger to debug a
+statement, given as a string.
+
+.. method:: Bdb.run(cmd, [globals, [locals]])
+
+ Debug a statement executed via the :keyword:`exec` statement. *globals*
+ defaults to :attr:`__main__.__dict__`, *locals* defaults to *globals*.
+
+.. method:: Bdb.runeval(expr, [globals, [locals]])
+
+ Debug an expression executed via the :func:`eval` function. *globals* and
+ *locals* have the same meaning as in :meth:`run`.
+
+.. method:: Bdb.runctx(cmd, globals, locals)
+
+ For backwards compatibility. Calls the :meth:`run` method.
+
+.. method:: Bdb.runcall(func, *args, **kwds)
+
+ Debug a single function call, and return its result.
+
+
+Finally, the module defines the following functions:
+
+.. function:: checkfuncname(b, frame)
+
+ Check whether we should break here, depending on the way the breakpoint *b*
+ was set.
+
+ If it was set via line number, it checks if ``b.line`` is the same as the one
+ in the frame also passed as argument. If the breakpoint was set via function
+ name, we have to check we are in the right frame (the right function) and if
+ we are in its first executable line.
+
+.. function:: effective(file, line, frame)
+
+ Determine if there is an effective (active) breakpoint at this line of code.
+ Return breakpoint number or 0 if none.
+
+ Called only if we know there is a breakpoint at this location. Returns the
+ breakpoint that was triggered and a flag that indicates if it is ok to delete
+ a temporary breakpoint.
+
+.. function:: set_trace()
+
+ Starts debugging with a :class:`Bdb` instance from caller's frame.
projects / python / commitdiff