#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 cfc219c..99dea6d 100644
--- a/Doc/library/pdb.rst
+++ b/Doc/library/pdb.rst
@@ -1,4 +1,3 @@
-
 .. _debugger:
 
 :mod:`pdb` --- The Python Debugger
@@ -53,7 +52,16 @@ useful than quitting the debugger upon program's exit.
 .. versionadded:: 2.4
    Restarting post-mortem behavior added.
 
-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
@@ -70,10 +78,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
@@ -117,7 +125,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:
@@ -351,3 +390,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.