Add docs

Author: gaogaotiantian

Doc/library/bdb.rst

@@ -118,7 +118,7 @@ The :mod:`bdb` module also defines two classes:
 
       Count of the number of times a :class:`Breakpoint` has been hit.
 
-.. class:: Bdb(skip=None)
+.. class:: Bdb(skip=None, backend='settrace')
 
    The :class:`Bdb` class acts as a generic Python debugger base class.
 
@@ -132,9 +132,22 @@ The :mod:`bdb` module also defines two classes:
    frame is considered to originate in a certain module is determined
    by the ``__name__`` in the frame globals.
 
+   The *backend* argument specifies the backend to use for :class:`Bdb`. It
+   can be either ``'settrace'`` or ``'monitoring'``. ``'settrace'`` uses
+   :func:`sys.settrace` which has the best backward compatibility. The
+   ``'monitoring'`` backend uses the new :mod:`sys.monitoring` that was
+   introduced in Python 3.12, which can be much more efficient because it
+   can disable unused events. We are trying to keep the exact interfaces
+   for both backends, but there are some differences. The debugger developers
+   are encouraged to use the ``'monitoring'`` backend to achieve better
+   performance.
+
    .. versionchanged:: 3.1
       Added the *skip* parameter.
 
+   .. versionchanged:: 3.14
+      Added the *backend* parameter.
+
    The following methods of :class:`Bdb` normally don't need to be overridden.
 
    .. method:: canonic(filename)
@@ -146,6 +159,16 @@ The :mod:`bdb` module also defines two classes:
       <os.path.abspath>`. A *filename* with angle brackets, such as ``"<stdin>"``
       generated in interactive mode, is returned unchanged.
 
+   .. method:: start_trace(self)
+
+      Start tracing. For ``'settrace'`` backend, this method is equivalent to
+      ``sys.settrace(self.trace_dispatch)``
+
+   .. method:: stop_trace(self)
+
+      Stop tracing. For ``'settrace'`` backend, this method is equivalent to
+      ``sys.settrace(None)``
+
    .. method:: reset()
 
       Set the :attr:`!botframe`, :attr:`!stopframe`, :attr:`!returnframe` and
@@ -364,6 +387,24 @@ The :mod:`bdb` module also defines two classes:
       Return all breakpoints that are set.
 
 
+   Derived classes and clients can call the following methods to disable and
+   restart events to achieve better performance. These methods only work
+   when using the ``'monitoring'`` backend.
+
+   .. method:: disable_current_event()
+
+      Disable the current event until the next time :func:`restart_events` is
+      called. This is helpful when the debugger is not interested in the current
+      line.
+
+   .. method:: restart_events()
+
+      Restart all the disabled events. This function is automatically called in
+      ``dispatch_*`` methods after ``user_*`` methods are called. If the
+      ``dispatch_*`` methods are not overridden, the disabled events will be
+      restarted after each user interaction.
+
+
    Derived classes and clients can call the following methods to get a data
    structure representing a stack trace.
 

Doc/library/pdb.rst

@@ -194,13 +194,32 @@ slightly different way:
    Enter post-mortem debugging of the exception found in
    :data:`sys.last_exc`.
 
+.. function:: set_default_backend(backend)
+
+   There are two supported backends for pdb: ``'settrace'`` and ``'monitoring'``.
+   See :class:`bdb.Bdb` for details. The user can set the default backend to
+   use if none is specified when instantiating :class:`Pdb`. If no backend is
+   specified, the default is ``'settrace'``.
+
+   .. note::
+
+      :func:`breakpoint` and :func:`set_trace` will not be affected by this
+      function. They always use ``'monitoring'`` backend.
+
+   .. versionadded:: 3.14
+
+.. function:: get_default_backend()
+
+   Returns the default backend for pdb.
+
+   .. versionadded:: 3.14
 
 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, \
-               nosigint=False, readrc=True, mode=None)
+               nosigint=False, readrc=True, mode=None, backend=None)
 
    :class:`Pdb` is the debugger class.
 
@@ -226,6 +245,10 @@ access further features, you have to do this yourself:
    or ``None`` (for backwards compatible behaviour, as before the *mode*
    argument was added).
 
+   The *backend* argument specifies the backend to use for the debugger. If ``None``
+   is passed, the default backend will be used. See :func:`set_default_backend`.
+   Otherwise the supported backends are ``'settrace'`` and ``'monitoring'``.
+
    Example call to enable tracing with *skip*::
 
       import pdb; pdb.Pdb(skip=['django.*']).set_trace()
@@ -245,6 +268,9 @@ access further features, you have to do this yourself:
    .. versionadded:: 3.14
       Added the *mode* argument.
 
+   .. versionadded:: 3.14
+      Added the *backend* argument.
+
    .. method:: run(statement, globals=None, locals=None)
                runeval(expression, globals=None, locals=None)
                runcall(function, *args, **kwds)

Doc/whatsnew/3.14.rst

@@ -350,6 +350,11 @@ ast
   that the root node type is appropriate.
   (Contributed by Irit Katriel in :gh:`130139`.)
 
+bdb
+---
+
+* The :mod:`bdb` module now supports the :mod:`sys.monitoring` backend.
+  (Contributed by Tian Gao in :gh:`124533`.)
 
 calendar
 --------
@@ -684,6 +689,12 @@ pdb
   the quit and call :func:`sys.exit`, instead of raising :exc:`bdb.BdbQuit`.
   (Contributed by Tian Gao in :gh:`124704`.)
 
+* :mod:`pdb` now supports two backends: :func:`sys.settrace` and
+  :mod:`sys.monitoring`. Using :mod:`pdb` CLI or :func:`breakpoint` will
+  always use the :mod:`sys.monitoring` backend. Explicitly instantiating
+  :class:`pdb.Pdb` and its derived classes will use the :func:`sys.settrace`
+  backend by default, which is configurable.
+  (Contributed by Tian Gao in :gh:`124533`.)
 
 pickle
 ------