Runtime Patches¶
Runtime patches for standard library and third party modules. These patches mostly emulate script isolation and missing POSIX features like signals and subprocesses.
Note
PytoRuntime interpreters share the same instance of all bundled modules (standard library and third party), while scripts imported from outside the app bundle are isolated between interpreters.
Third Party¶
Applied globally if the modules exist.
cv2
OpenCV Python binary extension loader
- cv2.autorotate(frame, cam)¶
Returns an auto rotated frame captured with hardware camera.
By default, frames captured by hardware camera will be rotated correctly only if the device is in portrait mode. By calling this function, you can make sure things like face detection will work on any device orientation.
- Parameters:
frame – The frame captured by the camera.
cam – The camera used to capture the frame.
0for back and1for front.
distlib
Monkey patch for distlib vendored by pip to match Pyto’s shebang.
mesonbuild
Meson patch that changes the default prefix to that of the current environment, forces binary command names to ‘meson’, and ensures Ninja build files use relative paths to avoid non existen paths after app update.
PIL
Writing images to the console
- patches.PIL.show(image, title=None, **options)¶
Writes an image to the disk and shows it in the console using
sharing.quick_look(), which callsreceiveImageOutput.- Parameters:
image – The image to show.
title – The title of the image.
options – Additional options.
remove_previouscan be set toTrueto remove the previous image in case of a video stream.
toga
A patch to Toga’s iOS backend for Pyto
It works without changing the Toga’s source code, just import this module before or after importing toga. Don’t delete toga or rubicon from sys.modules or the patch will be undone.
Standard Library¶
Applied globally after loading a Python version, except for warnings and sysconfig that are isolated.
_signal
This patch enables signal handling in non main threads. PytoRuntime installs its own signal handlers that call the Python handler associated with the receiving thread. This works for the main thread of any pseudo interpreter unlike Python’s default implementation that works exclusively on the main interpreter’s main thread. In PytoRuntime, an interpreter can have multiple main threads if its run method is called simultaneously. They share module states but have different signal handlers.
In addition to the layer on top of the signal module, PytoRuntime’s CPython distribution contains a patched _Py_ThreadCanHandleSignals that returns 1 on any thread of the main interpreter so handlers do get called by PyErr_CheckSignals. The default interruption handler _signal.default_int_handler is also patched to raise a patches._signal.KilledBySignal exception with the received signal as an argument if it’s not SIGINT. Then the interpreter can receive a signal through PytoRuntime’s layer, and then simulate a CPython signal with PyErr_SetInterruptEx that will call the patched default interrupt signal handler. If you just raise an exception from a signal handler, it will just get printed without interrupting execution.
- patches._signal.CRASH_SIGNALS: list[int] = [11, 10, 4, 8, 6, 12, 24, 25]¶
List of signals that mean a crash. These signals don’t trigger
patches._signal.KilledBySignalbut they do trigger signal handlers, pauses the thread for ever and exits the interpreter which will throw ankilled(signal:).
- exception patches._signal.KilledBySignal(signal)¶
BaseExceptiontype used internally for uncaught signals.
- patches._signal.getsignal(signal: int) callable | None¶
Returns the handler for the given signal.
- Parameters:
signal – Signal number.
- Return type:
callable | None
- patches._signal.old_signal(signalnum, handler, /)¶
Original
_signal.signalfunction.
- patches._signal.signal(signal: int, handler: callable) callable | None¶
Sets a handler for the given signal and returns the old one. Raises
ValueErrorif the current thread is not the main thread of the interpreter.- Parameters:
signal – The signal to set a handler for.
handler – The handler to set for the given signal. Takes the signal number and
Noneas its frame.
- Return type:
callable | None
atexit
This patch enables atexit handlers to called after a script finishes.
- class patches.atexit.CleanupFunction(func, *args, **kwargs)¶
A clenaup function that stores its arguments.
- patches.atexit.register(func: callable, *args, **kwargs)¶
Register a function to be called when the current interpreter’s script finishes.
- Parameters:
func – The function to register.
args – The arguments to pass to the function.
kwargs – The keyword arguments to pass to the function.
- patches.atexit.run_cleanup()¶
Runs registered functions for the current interpreter and unregisters them.
- patches.atexit.unregister(func: callable)¶
Unregister a function that was previosuly registered for the current interpreter.
- Parameters:
func – The function to unregister.
ctypes
Patches ctypes.pythonapi to point to the intepreter’s dynamic library instead of the main executable.
- patches.ctypes.pythonapi = <PyDLL '/Users/emma/Developer/pyto-runtime/dist/Framework/DerivedData/Build/Products/Release-maccatalyst/PytoRuntime.bundle/Contents/Frameworks/Python314.framework/Python314', handle 8bf16760>¶
Current interpreter’s dynamic library.
curses
Manages multiple curses states by saving and restoring them with newterm and set_term.
When PytoRuntime.Interpreter.focus is called on an interpreter, PytoRuntime calls patches.curses.set_term() if curses.set_term() was called by one of its threads.
- class patches.curses.Screen(sp_ptr, in_fp, out_fp)¶
Wrapper for a ncurses
SCREEN *and theFILE *backing it.- close()¶
Destroy the
SCREENand close theFILE *objects opened by newterm wrapper.
- set()¶
Make this screen the
CURRENT_SCREEN(set_term).
- class patches.curses.Window(_screen)¶
A proxy for
curses.windowthat is alway equivalent to the current interpreter’s window.
- patches.curses.delscreen(screen: Screen | int)¶
Destroy screen and close underlying FILE*s.
- Parameters:
screen – Screen instance or raw pointer.
- patches.curses.focused_terminal: str | None = None¶
The interpreter id of the focused terminal.
- patches.curses.newterm(termname: str | None, out_fd: int, in_fd: int) Screen¶
Creates a new
SCREENusing the provided output/input file descriptors.- Parameters:
termname – Terminal type.
out_fd – integer file descriptor (must be valid FD).
in_fd – integer file descriptor (must be valid FD).
- Return type:
Screen
- patches.curses.screens: dict[str, window] = {}¶
Stored curses.window instances, keyed by interpreter id.
- patches.curses.set_term(screen: Screen | int)¶
Set given Screen as
CURRENT_SCREEN.- Parameters:
screen – Screen instance or raw pointer.
- patches.curses.wrapper(func: callable, /, *args, **kwds)¶
Wrapper for
curses.wrapperthat passes and focuses the current interpreter’s window.- Parameters:
func – The function to wrap. It receives the current interpreter’s window as its first argument.
args – The arguments to pass to the function.
kwds – The keyword arguments to pass to the function.
fcntl
ioctl TTY simulation
This adds support for TIOCGWINSZ, TIOCSWINSZ and FIONREAD operations to ioctl for sys.stdin, sys.stdout and sys.stderr if they simulate TTY features.
- patches.fcntl.ioctl(fd: int, op: int, arg=None, mutate_flag=True, /)¶
Wrapped
fcntl.ioctlthat adds support forTIOCGWINSZ,TIOCSWINSZandFIONREAD.- Parameters:
fd – The file descriptor to use.
op – The operation to perform.
arg – The argument to use.
mutate_flag – Whether to mutate the argument.
functools
Cache isolation
Isolates caches between scripts.
- patches.functools.apply_patch()¶
Install patched versions of lru_cache and cache.
- patches.functools.clear_cache(script_path)¶
Clear every cached function registered under script_path, then drop it.
logging
Isolation for the logging module
This patch make logging ignore NameError if Pyto already cleaned up the logging module and global names are not available.
- patches.logging.shutdown(*args, **kwargs)¶
Perform cleanup actions on application exit.
os
Various os module patches.
- patches.os.chdir(dir: str)¶
Sets the current working directory only for the current thread with
pthread_chdir_np.patches.threading.Threaduses this to set the working directory for a new thread to that of its parent.- Parameters:
dir – The directory to change to.
- patches.os.get_terminal_size(fd=None) terminal_size¶
Returns the size of the terminal using
termios.- Parameters:
fd – The file descriptor to use.
- Return type:
os.terminal_size
- patches.os.replace_all(self, new_env: dict)¶
A method added to
os.environthat replaces all environment variables.- Parameters:
new_env – The new environment variables.
- patches.os.system(cmd: str) int¶
Executes a command in a pseudo subprocess with
patches.subprocess.Popenin shell mode.- Parameters:
cmd – The command to execute.
- Return type:
int
platform
Patch for the platform module.
- patches.platform.platform_system() str¶
Returns
Pytoas the platform name.- Return type:
str
readline
Manages multiple readline states.
It works with a patched version of editline that changed global variables to thread local variables.
- class patches.readline.EditLine(state: c_void_p, history: c_void_p, fd: int)¶
Stores the state of an editline session.
- fd: int¶
File descriptor of standard input.
- history: c_void_p¶
Pointer to the History struct.
- state: c_void_p¶
Pointer to the EditLine struct.
- patches.readline.clear_state()¶
Frees the editline state for the current interpreter.
- patches.readline.initialize_state()¶
Initializes the editline state for the current thread. If there is already a state for this thread, sets it for the current thread state.
- patches.readline.terminals = {6161412096: EditLine(state=512305055232, history=c_void_p(512289194560), fd=3)}¶
Maps thread ids to their
patches.readline.EditLineinstance.
shutil
Implements get_terminal_size() and which.
- patches.shutil.get_terminal_size(fallback=(80, 24)) terminal_size¶
Gets the size of the terminal with termios and returns it.
- Parameters:
fallback – The fallback size to use if the terminal size cannot be determined.
- Return type:
os.terminal_size
- patches.shutil.which(prog: str, mode: str | None = None, path: str | None = None) str¶
Returns the basename of the program.
- Parameters:
prog – The program to find.
mode – The mode to use (ignored).
path – The path to search in (ignored).
socketserver
Provides a function to close all socket servers started by an interpreter.
- patches.socketserver.active_servers = []¶
List of all active socket servers.
- patches.socketserver.cleanup()¶
Shutdown all socket servers started by the current interpreter.
- patches.socketserver.init_server(self, *args, **kwargs)¶
Overloaded initializer of
socketserver.BaseServerthat stores the current interpreter id onselfand registers the server.
subprocess
Subprocess simulation with threads and ios_system.
- class patches.subprocess.Popen(args, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, preexec_fn=None, close_fds=True, shell=False, cwd=None, env=None, universal_newlines=None, startupinfo=None, creationflags=0, restore_signals=True, start_new_session=False, pass_fds=(), *, user=None, group=None, extra_groups=None, encoding=None, errors=None, text=None, umask=-1, pipesize=-1)¶
Popen patch creating fake subprocesses. Can run ios_system command line utilities, executable scripts with shebangs, the Python interpreter and shell builtin commands. Shell builtin commands and Python console scripts need
shell_to beTrue.- communicate(input=None, timeout=None)¶
Interact with process: Send data to stdin and close it. Read data from stdout and stderr, until end-of-file is reached. Wait for process to terminate.
The optional “input” argument should be data to be sent to the child process, or None, if no data should be sent to the child. communicate() returns a tuple (stdout, stderr).
By default, all communication is in bytes, and therefore any “input” should be bytes, and the (stdout, stderr) will be bytes. If in text mode (indicated by self.text_mode), any “input” should be a string, and (stdout, stderr) will be strings decoded according to locale encoding, or by “encoding” if set. Text mode is triggered by setting any of text, encoding, errors or universal_newlines.
- send_signal(sig)¶
Send a signal to the process.
- wait(timeout=None)¶
Wait for child process to terminate; returns self.returncode.
- exception patches.subprocess.ShellExit(code=0)¶
An exception indicating that the shell should exit.
sys
This sys module patch manages a different state per pseudo interpreter associated to its threads allowing isolated i/o streams, paths, command line arguments and module trees.
- class patches.sys.ArgvProxy(_argv, sys)¶
Proxy set to
sys.argvthat returns thesys.argvof the current thread in case of using the unpatchedsysmodule.
- class patches.sys.MetaPathProxy(_path, sys)¶
Proxy set to
sys.meta_paththat returns thesys.meta_pathof the current thread in case of using the unpatchedsysmodule.- insert(i, v)¶
S.insert(index, value) – insert value before index
- class patches.sys.ModulesProxy(modules, sys)¶
Proxy set to
sys.modulesthat returns thesys.modulesof the current thread in case of using the unpatchedsysmodule.PytoRuntimes patched CPython sets this value as its interpreter modules dict with an added function called
__PyImport_SetModulesDict.- get(k[, d]) D[k] if k in D, else d. d defaults to None.¶
- items() a set-like object providing a view on D's items¶
- keys() a set-like object providing a view on D's keys¶
- values() an object providing a view on D's values¶
- class patches.sys.StreamProxy(_stream: int, _stream_obj: IO[Any], sys: ModuleType)¶
Proxy set to
sys.stdin,sys.stdoutandsys.stderrthat returns thesys.stdin,sys.stdoutandsys.stderrof the current thread in case of using the unpatchedsysmodule.
- class patches.sys.Sys(sys)¶
Proxy for the
sysmodule with interpreter local properties.- instances: dict[str, dict[Any]]¶
Dictionaries containing the interpreter local properties, keyed by interpreter id.
- main: dict[str, weakref.ref] = {'interpreter-0': <weakref at 0x10ef22390; to 'module'>}¶
__main__modules mapped to their interpreter ids.
Unique shared instance of this class.
- class patches.sys.SysArgv(argv)¶
Proxy for the
sys.argvlist with interpreter local values.- insert(i, v)¶
S.insert(index, value) – insert value before index
- class patches.sys.SysPath(path)¶
Proxy for the
sys.pathlist with interpreter local values.- insert(i, v)¶
S.insert(index, value) – insert value before index
threading
Maps threads to their interpreter for context isolation.
- class patches.threading.Thread(group=None, target=None, name=None, args=(), kwargs=None, *, daemon=None, context=None)¶
Subclass of
threading.Threadthat maps threads to their interpreter for context isolation. It passes the parent thread’s intepreter id to the new thread, which is written to ascript_pathattribute called like this because early versions of Pyto allowed one script to be executed at a time. But the value does not correspond to a path and is a unique identifier.It also installs signal handlers and sets the working directory to that of the parent’s thread.
- run()¶
Method representing the thread’s activity.
You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.
- start()¶
Start the thread’s activity.
It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.
This method will raise a RuntimeError if called more than once on the same thread object.
venv
Monkey patch for venv to match Pyto’s venv creation.
- patches.venv.EnvBuilder_init(self, *args, **kwargs)¶
Initializes the environment builder and unconditionally disables
pipas it is bundled with Pyto.
- patches.venv.create_configuration(self, context)¶
Sets the Python binary to
bin/python.
- patches.venv.ensure_directories(self, env_dir)¶
Sets the Python directory to
bin.
- patches.venv.post_setup(self, context)¶
Hook for post-setup modification of the venv.
- patches.venv.setup_python(self, context)¶
Set up a Python executable in the environment.
warnings
Changes warnings color to yellow if current environment can colorize text.
- patches.warnings.showwarning(message, category, filename, lineno, file=None, line=None)¶
Replacement for
warnings.showwarningthat colorizes the warning message to yellow if the current environment can colorize text.
webbrowser
Replacement for webbrowser module that uses sharing to open URLs.
- class patches.webbrowser.MobileSafari(name='')¶
Mobile Safari web browser (which is just the default web browser since iOS supports changing it).