| FazBrowse GitHub Viewer | Trending | | Home |
| Tools: [Download Repo ZIP] [Original HTTPS Page] |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1835,6 +1835,28 @@ always available. Unless explicitly noted otherwise, all variables are read-only | |||
| 1835 | 1835 | ||
| 1836 | 1836 | .. versionadded:: 3.12 | |
| 1837 | 1837 | ||
| 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 | + | ||
| 1838 | 1860 | .. function:: _enablelegacywindowsfsencoding() | |
| 1839 | 1861 | ||
| 1840 | 1862 | Changes the :term:`filesystem encoding and error handler` to 'mbcs' and | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -603,6 +603,13 @@ Miscellaneous options | |||
| 603 | 603 | ||
| 604 | 604 | .. versionadded:: 3.13 | |
| 605 | 605 | ||
| 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 | + | ||
| 606 | 613 | * :samp:`-X cpu_count={n}` overrides :func:`os.cpu_count`, | |
| 607 | 614 | :func:`os.process_cpu_count`, and :func:`multiprocessing.cpu_count`. | |
| 608 | 615 | *n* must be greater than or equal to 1. | |
@@ -1160,7 +1167,14 @@ conflict. | |||
| 1160 | 1167 | ||
| 1161 | 1168 | .. versionadded:: 3.13 | |
| 1162 | 1169 | ||
| 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. | ||
| 1163 | 1176 | ||
| 1177 | + .. versionadded:: 3.14 | ||
| 1164 | 1178 | ||
| 1165 | 1179 | .. envvar:: PYTHON_CPU_COUNT | |
| 1166 | 1180 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -660,6 +660,15 @@ also be used to improve performance. | |||
| 660 | 660 | Add ``-fstrict-overflow`` to the C compiler flags (by default we add | |
| 661 | 661 | ``-fno-strict-overflow`` instead). | |
| 662 | 662 | ||
| 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 | + | ||
| 663 | 672 | ||
| 664 | 673 | .. _debug-build: | |
| 665 | 674 | ||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -90,6 +90,79 @@ If you encounter :exc:`NameError`\s or pickling errors coming out of | |||
| 90 | 90 | New features | |
| 91 | 91 | ============ | |
| 92 | 92 | ||
| 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 | + | ||
| 93 | 166 | .. _whatsnew314-pep649: | |
| 94 | 167 | ||
| 95 | 168 | PEP 649: deferred evaluation of annotations | |
| Back | FazBrowse Home | New Git URL |
0 commit comments