gh-74614: bdb and pdb: Add watchpoint function

Doc/library/bdb.rst

@@ -20,10 +20,12 @@ The following exception is defined:
 
 The :mod:`bdb` module also defines two classes:
 
-.. class:: Breakpoint(self, file, line, temporary=False, cond=None, funcname=None)
+.. class:: Breakpoint(self, file, line, temporary=False, cond=None, funcname=None, \
+                      var_name=None, var_value=None, var_frame=None, \
+                      bptype='breakpoint')
 
-   This class implements temporary breakpoints, ignore counts, disabling and
-   (re-)enabling, and conditionals.
+   This class implements temporary breakpoints, watchpoints, 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
@@ -36,6 +38,12 @@ The :mod:`bdb` module also defines two classes:
    executed.  A :attr:`conditional <cond>` breakpoint always counts a
    :attr:`hit <hits>`.
 
+   When creating a watchpoint, *file* and *line* should be ``None``, and *cond*
+   , *funcname* are not used. *bptype* should be set to corresponding
+   watchpoiont type: ``watchpoint``, ``read watchpoint`` or
+   ``read/write watchpoint``.
+
+
    :class:`Breakpoint` instances have the following methods:
 
    .. method:: deleteMe()
@@ -61,6 +69,7 @@ The :mod:`bdb` module also defines two classes:
       formatted:
 
       * Breakpoint number.
+      * Breakpoint type.
       * Temporary status (del or keep).
       * File/line position.
       * Break condition.
@@ -69,6 +78,9 @@ The :mod:`bdb` module also defines two classes:
 
       .. versionadded:: 3.2
 
+      .. versionchanged:: 3.12
+         Breakpoint type will now changed by corresponding type.
+
    .. method:: bpprint(out=None)
 
       Print the output of :meth:`bpformat` to the file *out*, or if it is
@@ -232,6 +244,13 @@ The :mod:`bdb` module also defines two classes:
 
       Return True if any breakpoint exists for *frame*'s filename.
 
+   .. method:: watch_here(frame)
+
+      This method checks if there is a watchpoint in the filename and line
+      belonging to *frame* or, at least, in the current function.
+
+     .. versionadded:: 3.12
+
    Derived classes should override these methods to gain control over debugger
    operation.
 
@@ -298,15 +317,21 @@ The :mod:`bdb` module also defines two classes:
 
 
    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.
+   breakpoints and watchpoints.  These methods return a string containing an
+   error message if something went wrong, or ``None`` if all is well.
 
    .. method:: set_break(filename, lineno, temporary=False, cond=None, funcname=None)
 
       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:: set_watch(var_name, var_frame, bptype)
+
+      Set a new watchpoint. If the *var_name* does not exist in *var_frame*,
+      return a error message. bptype should be *watchpoint*, *read watchpoint*
+      or *read/write watchpoint*.
+
    .. method:: clear_break(filename, lineno)
 
       Delete the breakpoints in *filename* and *lineno*.  If none were set,

Doc/library/pdb.rst

@@ -318,15 +318,48 @@ can be overridden by the local file.
    If a second argument is present, it is an expression which must evaluate to
    true before the breakpoint is honored.
 
-   Without argument, list all breaks, including for each breakpoint, the number
-   of times that breakpoint has been hit, the current ignore count, and the
-   associated condition if any.
+   Without argument, list all breaks, including for each breakpoint or
+   watchpoint, the number of times that breakpoint has been hit, the current
+   ignore count, and the associated condition if any.
 
 .. pdbcommand:: tbreak [([filename:]lineno | function) [, condition]]
 
    Temporary breakpoint, which is removed automatically when it is first hit.
    The arguments are the same as for :pdbcmd:`break`.
 
+.. pdbcommand:: wa(tch) [expr]
+
+   Set a watchpoint for an expression. It will break when expression is written
+   into by program and the values changes.
+
+   Without argument, list all breaks, including for each breakpoint or
+   watchpoint, the number of times that breakpoint has been hit, the current
+   ignore count, and the associated condition if any.
+
+   .. versionadded:: 3.12
+
+.. pdbcommand:: rwa(tch) [expr]
+
+   Set a watchpoint for an expression. It will break when expression is
+   readed by program.
+
+   Without argument, list all breaks, including for each breakpoint or
+   watchpoint, the number of times that breakpoint has been hit, the current
+   ignore count, and the associated condition if any.
+
+   .. versionadded:: 3.12
+
+.. pdbcommand:: aw(atch) [expr]
+
+   Set a watchpoint for an expression. It will break when expression is
+   readed or written into by program.
+
+   Without argument, list all breaks, including for each breakpoint or
+   watchpoint, the number of times that breakpoint has been hit, the current
+   ignore count, and the associated condition if any.
+
+   .. versionadded:: 3.12
+
 .. pdbcommand:: cl(ear) [filename:lineno | bpnumber ...]
 
    With a *filename:lineno* argument, clear all the breakpoints at this line.