From 436127d691f1b73c06b1495e7eb21189c9a31538 Mon Sep 17 00:00:00 2001
From: ivonastojanovic <80911834+ivonastojanovic@users.noreply.github.com>
Date: Tue, 20 May 2025 19:50:49 -0400
Subject: [PATCH] Add documentation for remote debugging with pdb (GH-134260)

* Mention remote debugging via -p PID in usage text

Adds a brief note to the pdb help summary about attaching to a running
process using the -p option, making the remote debugging feature
more visible.

* Mention remote debugging in pdb.rst
(cherry picked from commit 6856a04d68bc1b779b5756a8a7c0ef08d684a630)

Co-authored-by: ivonastojanovic <80911834+ivonastojanovic@users.noreply.github.com>
---
 Doc/library/pdb.rst | 20 +++++++++++++++++++-
 Lib/pdb.py          |  3 ++-
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/Doc/library/pdb.rst b/Doc/library/pdb.rst
index a0304edddf6478..f4b51664545be5 100644
--- a/Doc/library/pdb.rst
+++ b/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
diff --git a/Lib/pdb.py b/Lib/pdb.py
index f89d104fcddb9a..d9e9bc011dbcca 100644
--- a/Lib/pdb.py
+++ b/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