Skip to content

Commit 80856d3

Browse files
pablogsalpablogsal
committed
Add more docs
1 parent 0c2b275 commit 80856d3

File tree

4 files changed

+118
-0
lines changed

4 files changed

+118
-0
lines changed

‎Doc/library/sys.rst‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1835,6 +1835,28 @@ always available. Unless explicitly noted otherwise, all variables are read-only
18351835

18361836
.. versionadded:: 3.12
18371837

1838+
1839+
.. function:: remote_exec(pid, script)
1840+
1841+
Executes a file containing Python code given by *script* in the remote
1842+
process with the given *pid*.
1843+
1844+
This function returns immediately, and the code will be executed by the
1845+
target process's main thread at the next available opportunity, similarly
1846+
to how signals are handled. There is no interface to determine when the
1847+
code has been executed. The caller is responsible for making sure that
1848+
the file still exists whenever the remote process tries to read it and that
1849+
it hasn't been overwritten.
1850+
1851+
The remote process must be running a CPython interpreter of the same major
1852+
and minor version as the local process. If either the local or remote
1853+
interpreter is pre-release (alpha, beta, or release candidate) then the
1854+
local and remote interpreters must be the same exact version.
1855+
1856+
.. availability:: Unix, Windows.
1857+
.. versionadded:: 3.14
1858+
1859+
18381860
.. function:: _enablelegacywindowsfsencoding()
18391861

18401862
Changes the :term:`filesystem encoding and error handler` to 'mbcs' and

‎Doc/using/cmdline.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -603,6 +603,13 @@ Miscellaneous options
603603

604604
.. versionadded:: 3.13
605605

606+
* ``-X disable_remote_debug`` disables the remote debugging support as described
607+
in :pep:`768`. This option is only available on some platforms and will do nothing
608+
if is not supported on the current system. See also
609+
:envvar:`PYTHON_DISABLE_REMOTE_DEBUG` and :pep:`768`.
610+
611+
.. versionadded:: 3.14
612+
606613
* :samp:`-X cpu_count={n}` overrides :func:`os.cpu_count`,
607614
:func:`os.process_cpu_count`, and :func:`multiprocessing.cpu_count`.
608615
*n* must be greater than or equal to 1.
@@ -1160,7 +1167,14 @@ conflict.
11601167

11611168
.. versionadded:: 3.13
11621169

1170+
.. envvar:: PYTHON_DISABLE_REMOTE_DEBUG
1171+
1172+
If this variable is set to a non-empty string, it disables the remote
1173+
debugging feature described in :pep:`768`.
1174+
1175+
See also the :option:`-X disable_remote_debug` command-line option.
11631176

1177+
.. versionadded:: 3.14
11641178

11651179
.. envvar:: PYTHON_CPU_COUNT
11661180

‎Doc/using/configure.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -660,6 +660,15 @@ also be used to improve performance.
660660
Add ``-fstrict-overflow`` to the C compiler flags (by default we add
661661
``-fno-strict-overflow`` instead).
662662

663+
.. option:: --without-remote-debug
664+
665+
Deactivate remote debugging support described in :pep:`768` (enabled by default).
666+
When this flag is provided the code that allows the interpreter to schedule the
667+
execution of a Python file in a separate process as described in :pep:`768` is
668+
not compiled.
669+
670+
..versionadded:: 3.14
671+
663672

664673
.. _debug-build:
665674

‎Doc/whatsnew/3.14.rst‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,79 @@ If you encounter :exc:`NameError`\s or pickling errors coming out of
9090
New features
9191
============
9292

93+
.. _whatsnew314-pep678:
94+
95+
PEP 768: Safe external debugger interface for CPython
96+
----------------------------------------------------
97+
98+
:pep:`768` introduces a zero-overhead debugging interface that allows debuggers and profilers
99+
to safely attach to running Python processes. This is a significant enhancement to Python's
100+
debugging capabilities, bringing them in line with other major programming languages.
101+
102+
The new interface provides safe execution points for attaching debugger code without modifying
103+
the interpreter's normal execution path or adding runtime overhead. This enables tools to
104+
inspect and interact with Python applications in real-time without stopping or restarting
105+
them — a crucial capability for high-availability systems and production environments.
106+
107+
For convenience, CPython implements this interface through the :mod:`sys` module with a
108+
:func:`sys.remote_exec` function::
109+
110+
sys.remote_exec(pid, script_path)
111+
112+
This function allows sending Python code to be executed in a target process at the next safe
113+
execution point. However, tool authors can also implement the protocol directly as described
114+
in the PEP, which details the underlying mechanisms used to safely attach to running processes.
115+
116+
Here's a simple example that inspects object types in a running Python process:
117+
118+
.. code-block:: python
119+
120+
import sys
121+
import tempfile
122+
import os
123+
124+
# Create a temporary script
125+
with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
126+
script_path = f.name
127+
f.write("""
128+
import gc
129+
import collections
130+
131+
# Collect all objects managed by the garbage collector
132+
gc.collect()
133+
134+
# Count objects by type
135+
type_counts = collections.Counter(type(obj).__name__
136+
for obj in gc.get_objects())
137+
138+
# Print the most common types
139+
print("Most common object types in process:")
140+
for type_name, count in type_counts.most_common(10):
141+
print(f" {type_name}: {count}")
142+
""")
143+
144+
try:
145+
# Execute in process with PID 1234
146+
print("Behold! An offering:")
147+
sys.remote_exec(1234, script_path)
148+
finally:
149+
os.unlink(script_path)
150+
151+
The debugging interface has been carefully designed with security in mind and includes several
152+
mechanisms to control access:
153+
154+
* A :envvar:`PYTHON_DISABLE_REMOTE_DEBUG` environment variable.
155+
* A :option:`-X disable-remote-debug` command-line option.
156+
* A ``--without-remote-debug`` configure flag to completely disable the feature at build time.
157+
158+
A key implementation detail is that the interface piggybacks on the interpreter's existing evaluation
159+
loop and safe points, ensuring zero overhead during normal execution while providing a reliable way
160+
for external processes to coordinate debugging operations.
161+
162+
See :pep:`768` for more details.
163+
164+
(Contributed by Pablo Galindo Salgado, Matt Wozniski, and Ivona Stojanovic in :gh:`131591`.)
165+
93166
.. _whatsnew314-pep649:
94167

95168
PEP 649: deferred evaluation of annotations

0 commit comments

Comments
 (0)