gh-131591: Add remote debugging attachment protocol documentation by ivonastojanovic · Pull Request #132638 · python/cpython · GitHub

Issue: Implement PEP 768 – Safe external debugger interface for CPython #131591

📚 Documentation preview 📚: https://cpython-previews--132638.org.readthedocs.build/en/132638/howto/remote_debugging.html

All commit authors signed the Contributor License Agreement.

Add a developer-facing document describing the protocol used by remote_exec(pid, script) to execute Python code in a running process. This is intended to guide debugger and tool authors in reimplementing the protocol.

@hugovk @willingc I will review this today but it would awesome if you can give this a go as well :)

Thank you, very clearly written.

From a quick look at the first section. (Edit: I was reviewing when Hugo posted his, there is some overlap)

Everything needs to be wrapped to 79 chars -- this affects almost every line.

This is a spec so we should write in a more formal way. The formal tone is better suited for this technical documentation because it establishes the necessary precision required when explaining technical operations like memory manipulation and code injection. This formality isn't just stylistic preference—it serves a functional purpose by reducing ambiguity. @ivonastojanovic here are a bunch of advice on how to change the tone:

Maintain consistent formality: Avoid casual phrases like "That's why" or constructions that directly address the reader as "you." Instead, use more objective phrasing such as "This protocol requires two pieces of information."
Use passive voice (some times): While active voice is generally clearer, technical documentation often benefits from passive voice where the focus should be on processes rather than actors (e.g., "The PyRuntime structure is located" rather than "You need to find the PyRuntime structure").
Minimize colloquial language: Replace informal transitions like "Next up" with more formal alternatives such as "Subsequently" or "The following step involves."

Maybe a short summary about the life time of the remote script shall be added to the documentation, too?
See #132712 (comment).

Signed-off-by: Pablo Galindo <pablogsal@gmail.com>

LGTM

I added a bunch of paragraphs with architecture-specific hints on how to do the diferent parts (specially since macOS and Windows are a bit more arcane).

Fantastic job @ivonastojanovic! ✨

@pablogsal Sorry I missed this ping last week. I just skimmed the docs, and it looks great! Hope all is well. Your name came up a bunch at PyTexas in my chats with Bloomberg folks. 😄

@pablogsal Sorry I missed this ping last week. I just skimmed the docs, and it looks great! Hope all is well. Your name came up a bunch at PyTexas in my chats with Bloomberg folks. 😄

Thanks @willingc ❤️

bedevere-app Bot added awaiting review docs Documentation in the Doc dir skip news labels Apr 17, 2025

github-project-automation Bot added this to Docs PRs Apr 17, 2025

github-project-automation Bot moved this to Todo in Docs PRs Apr 17, 2025

bedevere-app Bot mentioned this pull request Apr 17, 2025

Implement PEP 768 – Safe external debugger interface for CPython #131591

Closed

gh-131591 : Add remote debugging attachment protocol documentation

34c64f1

Add a developer-facing document describing the protocol used by remote_exec(pid, script) to execute Python code in a running process. This is intended to guide debugger and tool authors in reimplementing the protocol.

pablogsal self-requested a review April 17, 2025 14:43

pablogsal self-assigned this Apr 17, 2025

hugovk reviewed Apr 17, 2025

View reviewed changes

StanFromIreland reviewed Apr 17, 2025

View reviewed changes

Comment thread Doc/howto/remote_debugging.rst Outdated

Comment thread Doc/howto/remote_debugging.rst Outdated

Comment thread Doc/howto/remote_debugging.rst Outdated

Comment thread Doc/howto/remote_debugging.rst Outdated

chris-eibl reviewed Apr 17, 2025

View reviewed changes