[3.14] Add documentation for remote debugging with pdb (pythonGH-134260) (python#134398)

Author: miss-islington

Doc/library/pdb.rst

@@ -80,7 +80,7 @@ The debugger's prompt is ``(Pdb)``, which is the indicator that you are in debug
 You can also invoke :mod:`pdb` from the command line to debug other scripts.  For
 example::
 
-   python -m pdb [-c command] (-m module | pyfile) [args ...]
+   python -m pdb [-c command] (-m module | -p pid | pyfile) [args ...]
 
 When invoked as a module, pdb will automatically enter post-mortem debugging if
 the program being debugged exits abnormally.  After post-mortem debugging (or
@@ -104,6 +104,24 @@ useful than quitting the debugger upon program's exit.
    .. versionchanged:: 3.7
       Added the ``-m`` option.
 
+.. option:: -p, --pid <pid>
+
+   Attach to the process with the specified PID.
+
+   .. versionadded:: 3.14
+
+
+To attach to a running Python process for remote debugging, use the ``-p`` or
+``--pid`` option with the target process's PID::
+
+   python -m pdb -p 1234
+
+.. note::
+
+   Attaching to a process that is blocked in a system call or waiting for I/O
+   will only work once the next bytecode instruction is executed or when the
+   process receives a signal.
+
 Typical usage to execute a statement under control of the debugger is::
 
    >>> import pdb

Lib/pdb.py

@@ -3490,7 +3490,8 @@ def help():
 _usage = """\
 Debug the Python program given by pyfile. Alternatively,
 an executable module or package to debug can be specified using
-the -m switch.
+the -m switch. You can also attach to a running Python process
+using the -p option with its PID.
 
 Initial commands are read from .pdbrc files in your home directory
 and in the current directory, if they exist.  Commands supplied with