API Reference

This page contains the public API reference for pyisolate.

Main Classes

class pyisolate.ExtensionBase

Bases: ExtensionLocal

Base class for all PyIsolate extensions, providing lifecycle hooks and RPC wiring.

__init__() → None

async stop() → None

Stop the extension and clean up resources.

async before_module_loaded() → None

Hook called before the extension module is imported.

create_caller(object_type: type[proxied_type], object_id: str) → proxied_type

Create a proxy for calling methods on a remote object.

emit_event(name: str, payload: dict) → None

Emit a named event to the host process via RPC.

Payload must be JSON-serializable (dicts, lists, strings, numbers, booleans, None). Non-serializable payloads raise immediately.

async on_module_loaded(module: ModuleType) → None

Hook called after the extension module is successfully loaded.

register_callee(object_instance: object, object_id: str) → None

Expose an object for remote calls from the host process.

use_remote(proxied_singleton: type[ProxiedSingleton]) → None

Configure a ProxiedSingleton class to resolve to remote instances.

class pyisolate.ExtensionManager(extension_type: type[T], config: ExtensionManagerConfig)

Bases: Generic[T]

Manager for loading and supervising isolated extensions.

__init__(extension_type: type[T], config: ExtensionManagerConfig) → None

Initialize the ExtensionManager.

Parameters:

• extension_type – Base class that all managed extensions inherit from.

• config – Manager configuration (e.g., root path for virtualenvs).

load_extension(config: ExtensionConfig) → T

Load an extension with the given configuration.

Creates the venv (if isolated), installs dependencies, starts the child process, and returns a proxy that forwards calls to the isolated extension.

stop_all_extensions() → None

Stop all managed extensions and clean up resources.

Configuration

class pyisolate.ExtensionManagerConfig

Bases: TypedDict

Configuration for the ExtensionManager.

Controls where isolated virtual environments are created for extensions.

venv_root_path: str

Root directory where isolated venvs will be created (one subdir per extension).

class pyisolate.ExtensionConfig

Bases: TypedDict

Configuration for a single extension managed by PyIsolate.

name: str

Unique name for the extension (used for venv directory naming).

module_path: str

Filesystem path to the extension package containing __init__.py.

isolated: bool

Whether to run the extension in an isolated venv versus the host process.

dependencies: list[str]

List of pip requirement specifiers to install into the extension venv.

apis: list[type[ProxiedSingleton]]

ProxiedSingleton classes exposed to this extension for shared services.

share_torch: bool

If True, reuse host torch via torch.multiprocessing and zero-copy tensors.

share_cuda_ipc: bool

If True, attempt CUDA IPC-based tensor transport (Linux only, requires share_torch).

sandbox: dict[str, Any]

Configuration for the sandbox (e.g. writable_paths, network access).

sandbox_mode: SandboxMode

Sandbox enforcement mode. Default is REQUIRED (fail if bwrap unavailable). Set to DISABLED only if you fully trust all code and accept the security risk.

env: dict[str, str]

Environment variable overrides for the child process.

package_manager: NotRequired[str]

‘uv’ (default) or ‘conda’.

Type:

Backend package manager

execution_model: NotRequired[str]

‘host-coupled’ (default for uv) or ‘sealed_worker’.

Type:

Runtime boundary

sealed_host_ro_paths: NotRequired[list[str]]

Optional sealed-worker-only absolute host paths to mount read-only for imports.

conda_channels: NotRequired[list[str]]

Conda channels to use (required when package_manager=’conda’).

conda_dependencies: NotRequired[list[str]]

Conda-forge dependency specifications.

conda_platforms: NotRequired[list[str]]

Target platforms for conda environment (defaults to current platform).

cuda_wheels: NotRequired[CUDAWheelConfig]

Optional custom CUDA wheel resolution configuration for selected dependencies.

Utilities

class pyisolate.ProxiedSingleton(*args: Any, **kwargs: Any)

Bases: object

Cross-process singleton with RPC-proxied method calls.

__init__() → None

classmethod get_remote_id() → str