Merged revisions 72322 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r72322 | georg.brandl | 2009-05-05 10:54:11 +0200 (Di, 05 Mai 2009) | 1 line

  #5142: add module skipping feature to pdb.
........

1 files changed, 49 insertions, 4 deletions

diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst
index 63ade97..0b29c2c 100644
--- a/Doc/library/pdb.rst
+++ b/Doc/library/pdb.rst
@@ -1,4 +1,3 @@
-
 .. _debugger:
 
 :mod:`pdb` --- The Python Debugger
@@ -50,7 +49,16 @@ after normal exit of the program), pdb will restart the program. Automatic
 restarting preserves pdb's state (such as breakpoints) and in most cases is more
 useful than quitting the debugger upon program's exit.
 
-Typical usage to inspect a crashed program is::
+The typical usage to break into the debugger from a running program is to
+insert ::
+
+   import pdb; pdb.set_trace()
+
+at the location you want to break into the debugger.  You can then step through
+the code following this statement, and continue running without debugger using
+the ``c`` command.
+
+The typical usage to inspect a crashed program is::
 
    >>> import pdb
    >>> import mymodule
@@ -67,10 +75,10 @@ Typical usage to inspect a crashed program is::
    -> print(spam)
    (Pdb)
 
+
 The module defines the following functions; each enters the debugger in a
 slightly different way:
 
-
 .. function:: run(statement[, globals[, locals]])
 
    Execute the *statement* (given as a string) under debugger control.  The
@@ -113,7 +121,38 @@ slightly different way:
 
 .. function:: pm()
 
-   Enter post-mortem debugging of the traceback found in ``sys.last_traceback``.
+   Enter post-mortem debugging of the traceback found in
+   :data:`sys.last_traceback`.
+
+
+The ``run_*`` functions and :func:`set_trace` are aliases for instantiating the
+:class:`Pdb` class and calling the method of the same name.  If you want to
+access further features, you have to do this yourself:
+
+.. class:: Pdb(completekey='tab', stdin=None, stdout=None, skip=None)
+
+   :class:`Pdb` is the debugger class.
+
+   The *completekey*, *stdin* and *stdout* arguments are passed to the
+   underlying :class:`cmd.Cmd` class; see the description there.
+
+   The *skip* argument, if given, must be an iterable of glob-style module name
+   patterns.  The debugger will not step into frames that originate in a module
+   that matches one of these patterns. [1]_
+
+   Example call to enable tracing with *skip*::
+
+      import pdb; pdb.Pdb(skip=['django.*']).set_trace()
+
+   .. versionadded:: 2.7
+      The *skip* argument.
+
+   .. method:: run(statement[, globals[, locals]])
+               runeval(expression[, globals[, locals]])
+               runcall(function[, argument, ...])
+               set_trace()
+
+      See the documentation for the functions explained above.
 
 
 .. _debugger-commands:
@@ -336,3 +375,9 @@ run [*args* ...]
 
 q(uit)
    Quit from the debugger. The program being executed is aborted.
+
+
+.. rubric:: Footnotes
+
+.. [1] Whether a frame is considered to originate in a certain module
+       is determined by the ``__name__`` in the frame globals.