PEP 768: Add some minor changes to the APIs and some clarifications

Author: pablogsal

peps/pep-0768.rst

@@ -143,6 +143,12 @@ are **never accessed during normal execution**. The ``debugger_pending_call`` fi
 indicates when a debugger has requested execution, while ``debugger_script``
 provides Python code to be executed when the interpreter reaches a safe point.
 
+The value for ``MAX_SCRIPT_SIZE`` will be a trade-off between binary size and
+how big debugging scripts can be. As most of the logic should be in libraries
+and arbitrary code can be executed with very short ammount of Python we are
+proposing to start with 4kb initially. This value can be extended in the future
+if we ever need to.
+
 
 Debug Offsets Table
 -------------------
@@ -191,7 +197,8 @@ When a debugger wants to attach to a Python process, it follows these steps:
 
 5. Write control information:
 
-   - Write python code to be executed into the ``debugger_script`` field in ``_PyRemoteDebuggerSupport``
+   - Write a string of Python code to be executed into the ``debugger_script``
+     field in ``_PyRemoteDebuggerSupport``.
    - Set ``debugger_pending_call`` flag in ``_PyRemoteDebuggerSupport``
    - Set ``_PY_EVAL_PLEASE_STOP_BIT`` in the ``eval_breaker`` field
 
@@ -232,6 +239,11 @@ is checked.
     }
 
 
+If the code being executed raises any Python exception it will be processed as
+an `unraisable exception
+<https://docs.python.org/3/c-api/exceptions.html#c.PyErr_WriteUnraisable>`__ in
+the thread where the code was executed.
+
 Python API
 ----------
 
@@ -242,13 +254,16 @@ arbitrary Python code within the context of a specified Python process:
 
 .. code-block:: python
 
-  def remote_exec(pid: int, code: str) -> None:
+  def remote_exec(pid: int, code: str, timeout: int = 0) -> None:
       """
       Executes a block of Python code in a given remote Python process.
 
       Args:
            pid (int): The process ID of the target Python process.
            code (str): A string containing the Python code to be executed.
+           timeout (int): An optional timeout for waiting for the remote
+              process to execute the code. If the timeout is exceeded a
+              ``TimeoutError`` will be raised.
       """
 
 An example usage of the API would look like:
@@ -258,7 +273,9 @@ An example usage of the API would look like:
     import sys
     # Execute a print statement in a remote Python process with PID 12345
     try:
-        sys.remote_exec(12345, "print('Hello from remote execution!')")
+        sys.remote_exec(12345, "print('Hello from remote execution!')", timeout=3)
+    except TimeoutError:
+        print(f"The remote process took too long to execute the code")
     except Exception as e:
         print(f"Failed to execute code: {e}")
 
@@ -341,7 +358,30 @@ debugging tool stability and reliability.
 Reference Implementation
 ========================
 
-https://github.com/pablogsal/cpython/commits/remote_pdb/
+A reference implementation with a prototype adding remote support for ``pdb``
+can be found `here
+<https://github.com/pablogsal/cpython/compare/60ff67d010078eca15a74b1429caf779ac4f9c74...remote_pdb>`__.
+
+Rejected Ideas
+==============
+
+Using a path as the debugger input
+----------------------------------
+
+We have selected that the mechanism for executing remote code is that tools
+write the code directly in the remote process to eliminate a possible security
+vulnerability in which the file to be executed can be altered by parties other
+than the debugger process if permissions are not set correctly or filesystem
+configurations allow for this to happen. It is also trivial to write code that
+executes the contents of a file so the current mechanism doesn't disallow tools
+that want to just execute files to just do so if they are ok with the security
+profile of such operation.
+
+Thanks
+======
+
+We would like to thank Carl Friedrich Bolz-Tereick for his insightful comments and suggestions
+when discussing this proposal.
 
 
 Copyright