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. 0 for back and 1 for 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 calls receiveImageOutput.

Parameters:
  • image – The image to show.

  • title – The title of the image.

  • options – Additional options. remove_previous can be set to True to 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.KilledBySignal but they do trigger signal handlers, pauses the thread for ever and exits the interpreter which will throw an killed(signal:).

exception patches._signal.KilledBySignal(signal)

BaseException type 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.signal function.

patches._signal.signal(signal: int, handler: callable) → callable | None

Sets a handler for the given signal and returns the old one. Raises ValueError if 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 None as 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 the FILE * backing it.

close()

Destroy the SCREEN and close the FILE * objects opened by newterm wrapper.

set()

Make this screen the CURRENT_SCREEN (set_term).

class patches.curses.Window(_screen)

A proxy for curses.window that 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 SCREEN using 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.terminals: dict[str, Screen] = {}

Stored Screen instances, keyed by interpreter id.

patches.curses.wrapper(func: callable, /, *args, **kwds)

Wrapper for curses.wrapper that 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.ioctl that adds support for TIOCGWINSZ, TIOCSWINSZ and FIONREAD.

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.Thread uses 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.environ that 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.Popen in shell mode.

Parameters:

cmd – The command to execute.

Return type:

int

platform

Patch for the platform module.

patches.platform.platform_system() → str

Returns Pyto as 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.EditLine instance.

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.BaseServer that stores the current interpreter id on self and 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 be True.

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.argv that returns the sys.argv of the current thread in case of using the unpatched sys module.

class patches.sys.MetaPathProxy(_path, sys)

Proxy set to sys.meta_path that returns the sys.meta_path of the current thread in case of using the unpatched sys module.

insert(i, v)

S.insert(index, value) – insert value before index

class patches.sys.ModulesProxy(modules, sys)

Proxy set to sys.modules that returns the sys.modules of the current thread in case of using the unpatched sys module.

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.stdout and sys.stderr that returns the sys.stdin, sys.stdout and sys.stderr of the current thread in case of using the unpatched sys module.

class patches.sys.Sys(sys)

Proxy for the sys module 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.

shared = <module 'sys' (built-in)>

Unique shared instance of this class.

class patches.sys.SysArgv(argv)

Proxy for the sys.argv list with interpreter local values.

insert(i, v)

S.insert(index, value) – insert value before index

class patches.sys.SysPath(path)

Proxy for the sys.path list 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.Thread that maps threads to their interpreter for context isolation. It passes the parent thread’s intepreter id to the new thread, which is written to a script_path attribute 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 pip as 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.showwarning that 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).