]> granicus.if.org Git - python/commitdiff
New documentation page for the bdb module.
authorGeorg Brandl <georg@python.org>
Wed, 12 Sep 2007 18:03:51 +0000 (18:03 +0000)
committerGeorg Brandl <georg@python.org>
Wed, 12 Sep 2007 18:03:51 +0000 (18:03 +0000)
(This doesn't need to be merged to Py3k.)

Doc/library/bdb.rst [new file with mode: 0644]
Doc/library/debug.rst [new file with mode: 0644]
Doc/library/index.rst
Doc/library/pdb.rst

diff --git a/Doc/library/bdb.rst b/Doc/library/bdb.rst
new file mode 100644 (file)
index 0000000..0e42be6
--- /dev/null
@@ -0,0 +1,337 @@
+: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
diff --git a/Doc/library/debug.rst b/Doc/library/debug.rst
new file mode 100644 (file)
index 0000000..7480087
--- /dev/null
@@ -0,0 +1,17 @@
+***********************
+Debugging and Profiling
+***********************
+
+These libraries help you with Python development: the debugger enables you to
+step through code, analyze stack frames and set breakpoints etc., and the
+profilers run code and give you a detailed breakdown of execution times,
+allowing you to identify bottlenecks in your programs.
+
+.. toctree::
+
+   bdb.rst
+   pdb.rst
+   profile.rst
+   hotshot.rst
+   timeit.rst
+   trace.rst
\ No newline at end of file
index 9f47b0ed4e80528e661950697f6169536b8f257d..b15c16c752bcb35bdc98b12b00efc2401445c297 100644 (file)
@@ -64,11 +64,7 @@ over 2500 additional components available from the `Python Package Index
    frameworks.rst
    tk.rst
    development.rst
-   pdb.rst
-   profile.rst
-   hotshot.rst
-   timeit.rst
-   trace.rst
+   debug.rst
    python.rst
    custominterp.rst
    restricted.rst
index 236c7fa84f55bcb29f1c54f298f8e18b5cf8dca7..ab277beccd4ca8c4a88f1479e01d409ff88e062b 100644 (file)
@@ -1,9 +1,8 @@
 
 .. _debugger:
 
-*******************
-The Python Debugger
-*******************
+:mod:`pdb` --- The Python Debugger
+==================================
 
 .. module:: pdb
    :synopsis: The Python debugger for interactive interpreters.