Mention remote debugging in pdb.rst

Author: ivonastojanovic

Doc/library/pdb.rst

@@ -16,7 +16,9 @@ The module :mod:`pdb` defines an interactive source code debugger for Python
 programs.  It supports setting (conditional) breakpoints and single stepping at
 the source line level, inspection of stack frames, source code listing, and
 evaluation of arbitrary Python code in the context of any stack frame.  It also
-supports post-mortem debugging and can be called under program control.
+supports post-mortem debugging and can be called under program control. The 
+:mod:`pdb` module also supports remote attaching to a running Python process
+using a ``-p PID`` command-line option.
 
 .. index::
    single: Pdb (class in pdb)
@@ -80,7 +82,10 @@ 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 ...]
+
+Remote debugging is supported by attaching to a running Python process using 
+the ``-p`` option and a PID.
 
 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 +109,27 @@ 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.
+
+   .. versionchanged:: 3.14
+      Added the ``-p`` and ``--pid`` options. This feature leverages :pep:`768` 
+      and the :func:`sys.remote_exec` function to attach to the remote process 
+      and send the PDB commands to it.
+
+
+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
+
+This will connect to the Python process with the given PID and allow you to
+debug it interactively. Notice that due to how the Python interpreter works,
+attaching to a remote 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