Skip to content

Runtime API

Core APIs for creating isolates, contexts, scopes, scripts, modules, snapshots, profiles, inspector sessions, and runtime diagnostics.

Isolate

Owns one V8 isolate until it is consumed to create a context, builder, or scope.

__new__(snapshot: StartupData | bytes | bytearray | memoryview | None = None) -> Isolate

Create a new V8 isolate, optionally initialized from snapshot startup data.

create_context() -> Context

Consume this isolate and create a fresh execution context.

create_context_builder() -> ContextBuilder

Consume this isolate and return a ContextBuilder for configuring globals and HostAPI.

create_context_from_snapshot(index: int = 0) -> Context

Consume this isolate and create a context from a snapshot context index.

create_scope() -> Scope

Consume this isolate and create a low-level scope for compiling a standalone script.

heap_code_statistics() -> dict[str, int]

Return V8 heap statistics for generated code and metadata.

heap_space_statistics() -> list[dict[str, int | str]]

Return per-space V8 heap statistics for this isolate.

heap_statistics() -> dict[str, int | bool]

Return V8 heap statistics for this isolate.

low_memory_notification() -> None

Notify V8 that the host is under low-memory pressure.

memory_pressure(level: Literal[none, moderate, critical]) -> None

Set V8's memory pressure level for this isolate.

request_garbage_collection_for_testing(collection_type: Literal[full, minor] = 'full') -> None

Request a V8 garbage collection cycle for testing.

ContextBuilder

Builder for configuring a context before it is created.

build() -> Context

Consume this builder and create the configured context.

class_(cls: _C | None = None, *, name: str | None = None) -> _C | Callable[[_C], _C] 

class_(cls: _C, *, name: str | None = None) -> _C

class_(cls: None = None, *, name: str | None = None) -> Callable[[_C], _C]

Register a Python class as a JavaScript constructor template for this context.

host_function(function: _F | None = None, *, name: str | None = None) -> _F | Callable[[_F], _F] 

host_function(function: _F, *, name: str | None = None) -> _F

host_function(function: None = None, *, name: str | None = None) -> Callable[[_F], _F]

Register a Python callable as a JavaScript global function for this context.

is_alive() -> bool

Return whether this builder can still build a context.

set_global(name: str, value: _JSValueLike) -> None

Queue a global value to install when the context is built.

set_microtasks_policy(policy: str) -> None

Set the microtask policy to "auto" or "explicit".

use_profile(profile: BaseProfile) -> None

Copy host functions, host classes, and HostAPI installers from a profile.

use_snapshot(index: int = 0) -> None

Build the context from a snapshot context index.

Context

A V8 execution context tied to one isolate.

cancel_terminate_execution() -> bool

Cancel a pending termination request for JavaScript execution.

compile(source: str | String, *, filename: str = '<script>', source_map_url: str | None = None, cached_data: bytes | bytearray | memoryview | None = None) -> Script

Compile JavaScript source as a reusable script.

compile_function(source: str | String, arguments: Sequence[str] | None = None, *, filename: str = '<function>', source_map_url: str | None = None, cached_data: bytes | bytearray | memoryview | None = None) -> Function

Compile JavaScript source as a function object.

compile_module(source: str, specifier: str = '<module>') -> Module

Compile an ECMAScript module with the given specifier.

compile_wasm_module(wire_bytes: bytes | bytearray | memoryview, cache: WasmModuleCache | None = None) -> WasmModule

Compile a WebAssembly module from wire bytes.

deserialize(data: bytes | bytearray | memoryview) -> Value

Deserialize bytes produced by serialize into a JavaScript value.

eval(source: str, timeout_ms: int | None = None) -> Value

Compile and run JavaScript source immediately.

from_python(value: _JSValueLike) -> Value

Convert a Python object into a JavaScript value in this context.

get_global(name: str) -> Value

Read a global property from this context.

heap_code_statistics() -> dict[str, int]

Return V8 heap statistics for generated code and metadata.

heap_space_statistics() -> list[dict[str, int | str]]

Return per-space V8 heap statistics for this context's isolate.

heap_statistics() -> dict[str, int | bool]

Return V8 heap statistics for this context's isolate.

inspector() -> Inspector

Return the inspector object installed for this context.

is_alive() -> bool

Return whether this context still owns a live V8 context and isolate.

low_memory_notification() -> None

Notify V8 that the host is under low-memory pressure.

memory_pressure(level: Literal[none, moderate, critical]) -> None

Set V8's memory pressure level for this context's isolate.

new_array_buffer(value: int | bytes | bytearray | memoryview) -> ArrayBuffer

Create an ArrayBuffer from a byte length or bytes-like object.

new_external(payload: object) -> External

Create a V8 external value that owns a Python payload.

new_object(internal_field_count: int = 0) -> Object

Create a new V8 object, optionally with internal fields.

new_private(name: str | String | None = None, *, for_api: bool = False) -> Private

Create a V8 private key, optionally using the API-visible key namespace.

new_string(value: str) -> String

Create a V8 string in this context.

parse_json(source: str) -> Value

Parse JSON source into a JavaScript value.

perform_microtask_checkpoint() -> None

Run V8's microtask checkpoint for this isolate.

private_for_api(name: str | String | None = None) -> Private

Create or retrieve a V8 API private key.

request_garbage_collection_for_testing(collection_type: Literal[full, minor] = 'full') -> None

Request a V8 garbage collection cycle for testing.

run_event_loop_once(timeout_ms: int | None = None) -> bool

Run at most one queued host task or timer.

run_until_idle(max_tasks: int | None = None) -> int

Run queued host tasks until the queue is idle or max_tasks is reached.

serialize(value: _JSValueLike) -> bytes

Serialize a JavaScript-compatible value using V8's structured clone format.

set_global(name: str, value: _JSValueLike) -> bool

Set a global property on this context.

set_microtasks_policy(policy: str) -> None

Set the microtask policy to "auto" or "explicit" for this context's isolate.

terminate_execution() -> bool

Request termination of currently running JavaScript execution.

wasm_module_from_compiled(compiled: CompiledWasmModule) -> WasmModule

Recreate a WebAssembly module object from a compiled module handle.

Scope

Low-level V8 handle scope used for creating strings and compiling a single script.

compile(source: String) -> Script

Compile a string into a script, consuming this scope.

is_alive() -> bool

Return whether this scope still owns its isolate.

new_string(value: str) -> String

Create a V8 string in this scope.

Script

Compiled JavaScript script bound to a context.

cached_data_rejected: bool property

Return whether supplied cached data was rejected by V8.

resource_name: str | None property

Return the resource name supplied at compile time.

script_id: int property

Return V8's script id for this script.

source: str property

Return the source text used to compile this script.

source_map_url: str | None property

Return the source map URL supplied at compile time.

source_mapping_url: str | None property

Return the source mapping URL discovered by V8.

source_url: str | None property

Return the source URL discovered by V8.

create_code_cache() -> bytes

Create V8 code-cache bytes for this script.

run(timeout_ms: int | None = None) -> Value

Run the compiled script and return its result.

Module

Compiled ECMAScript module bound to a context.

specifier: str property

Return this module's specifier.

status: str property

Return V8's current module status name.

evaluate(timeout_ms: int | None = None) -> Value

Evaluate this instantiated module and return the completion value.

instantiate(imports: _ModuleImportsLike | None = None) -> bool

Instantiate this module, optionally resolving imports from a dict.

namespace() -> Value

Return the module namespace object.

BaseProfile

Reusable collection of host functions, host classes, and HostAPI installers.

__new__() -> BaseProfile

Create an empty profile.

class_(cls: _C | None = None, *, name: str | None = None) -> _C | Callable[[_C], _C] 

class_(cls: _C, *, name: str | None = None) -> _C

class_(cls: None = None, *, name: str | None = None) -> Callable[[_C], _C]

Register a Python class as a JavaScript constructor template.

Can be used directly or as a decorator. Methods and properties visible on the Python class are exposed through V8 object templates.

class_count() -> int

Return the number of registered host classes.

host_function(function: _F | None = None, *, name: str | None = None) -> _F | Callable[[_F], _F] 

host_function(function: _F, *, name: str | None = None) -> _F

host_function(function: None = None, *, name: str | None = None) -> Callable[[_F], _F]

Register a Python callable as a JavaScript global function.

Can be used directly or as a decorator. When name is omitted, the callable's __name__ is used as the JavaScript global name.

host_function_count() -> int

Return the number of registered host functions.

install(apis: Iterable[api.HostAPI]) -> BaseProfile

Install HostAPI instances into this profile and return the profile.

StartupData

Raw V8 startup snapshot data.

byte_length: int property

Return the number of bytes in this snapshot.

__bytes__() -> bytes

Return this snapshot as bytes.

__len__() -> int

Return the snapshot byte length.

__new__(data: bytes | bytearray | memoryview) -> StartupData

Wrap snapshot bytes.

__repr__() -> str

Return a debug representation.

can_be_rehashed() -> bool

Return whether V8 can rehash this snapshot for the current build.

is_valid() -> bool

Return whether this snapshot is valid for the linked V8.

to_bytes() -> bytes

Return this snapshot as bytes.

SnapshotCreator

Builder for creating V8 startup snapshots.

__new__(existing_snapshot: StartupData | bytes | bytearray | memoryview | None = None) -> SnapshotCreator

Create a snapshot creator, optionally seeded from existing startup data.

__repr__() -> str

Return a debug representation.

add_context(source: str | None = None, *, timeout_ms: int | None = None) -> int

Add a context snapshot and return its index.

create_blob(function_code_handling: Literal[clear, keep] = 'clear') -> StartupData

Finish the snapshot and return startup data.

eval(source: str, timeout_ms: int | None = None) -> None

Execute JavaScript in the default snapshot context.

is_alive() -> bool

Return whether this creator can still produce a snapshot.

Inspector

V8 Inspector endpoint for a context.

context_group_id: int property

Return the inspector context group id.

name: str property

Return the inspector context name.

__repr__() -> str

Return a debug representation.

connect(state: str = '', *, trusted: bool = True, on_message: Callable[[str], object] | None = None) -> InspectorSession

Connect a protocol session to this inspector.

is_alive() -> bool

Return whether this inspector still owns an active V8 inspector.

InspectorSession

Connected V8 Inspector protocol session.

messages: list[str] property

Return queued inspector protocol messages.

__bool__() -> bool

Return whether the session has queued messages.

__len__() -> int

Return the number of queued inspector messages.

__repr__() -> str

Return a debug representation.

can_dispatch_method(method: str) -> bool staticmethod

Return whether an inspector protocol method can be dispatched.

clear_messages() -> None

Clear queued inspector protocol messages.

dispatch(message: str) -> None

Dispatch a raw inspector protocol message.

schedule_pause_on_next_statement(reason: str, detail: str) -> None

Schedule a debugger pause on the next JavaScript statement.

send(message: str | dict[str, object]) -> None

Send an inspector protocol request or notification.

take_messages() -> list[str]

Drain and return queued inspector protocol messages.

JavaScriptError

Bases: RuntimeError

Python exception carrying V8 exception, message, and stack metadata.

details: str | None property

Return V8's formatted message details when available.

end_column: int property

Return the zero-based end column.

end_position: int | None property

Return the end source position when V8 reports one.

error_level: int property

Return V8's message error level.

frames: list[StackFrame] property

Return stack frames, or an empty list when no stack trace is available.

is_opaque: bool property

Return whether the message is opaque.

is_shared_cross_origin: bool property

Return whether the message is shared cross-origin.

line_number: int | None property

Return the one-based source line number when V8 reports one.

message: str property

Return the exception message.

message_info: Message | None property

Return structured V8 message metadata when available.

script_resource_name: str | None property

Return the script resource name associated with the exception.

source_line: str | None property

Return the source line associated with the exception.

stack: str | None property

Return the formatted JavaScript stack string.

stack_trace: StackTrace | None property

Return structured stack trace frames when available.

start_column: int property

Return the zero-based start column.

start_position: int | None property

Return the start source position when V8 reports one.

wasm_function_index: int | None property

Return the WebAssembly function index when the error came from Wasm.

__new__(message: str) -> JavaScriptError

Create a JavaScriptError from a message string.

__str__() -> str

Return the formatted exception string.

Message

V8 message metadata associated with a JavaScript exception.

end_column: int property

Return the zero-based end column.

end_position: int | None property

Return the end source position when V8 reports one.

error_level: int property

Return V8's message error level.

is_opaque: bool property

Return whether the message is opaque.

is_shared_cross_origin: bool property

Return whether the message is shared cross-origin.

line_number: int | None property

Return the one-based source line number when V8 reports one.

script_resource_name: str | None property

Return the script resource name associated with the message.

source_line: str | None property

Return the source line associated with the message.

start_column: int property

Return the zero-based start column.

start_position: int | None property

Return the start source position when V8 reports one.

text: str property

Return V8's message text.

wasm_function_index: int | None property

Return the WebAssembly function index when the message came from Wasm.

__repr__() -> str

Return a debug representation.

__str__() -> str

Return V8's message text.

StackTrace

Structured JavaScript stack trace.

frames: list[StackFrame] property

Return stack frames.

text: str | None property

Return the formatted stack text when V8 provides one.

__getitem__(index: int) -> StackFrame

Return a stack frame by index.

__len__() -> int

Return the number of stack frames.

__repr__() -> str

Return a debug representation.

__str__() -> str

Return the formatted stack text, or an empty string.

StackFrame

One frame in a JavaScript stack trace.

column: int | None property

Return the zero-based source column.

function_name: str | None property

Return the JavaScript function name.

is_constructor: bool property

Return whether this frame is a constructor call.

is_eval: bool property

Return whether this frame came from eval.

is_user_javascript: bool property

Return whether V8 considers this user JavaScript.

is_wasm: bool property

Return whether this frame is WebAssembly.

line: int | None property

Return the one-based source line.

line_number: int | None property

Return the one-based source line.

script_id: int | None property

Return V8's script id.

script_name: str | None property

Return the script name.

script_name_or_source_url: str | None property

Return the script name or source URL.

script_source: str | None property

Return the script source when V8 provides it.

script_source_mapping_url: str | None property

Return the script source mapping URL.

__repr__() -> str

Return a debug representation.

cached_data_version_tag() -> int

Return V8's cached-data version tag for script code cache compatibility checks.

collect_garbage() -> int

Run Python's gc.collect(), then release pending V8 isolates in safe reverse creation order.