Types

Useful Python types used in jsrun.

JavaScriptError

Bases: Exception

Raised when JavaScript code running in the runtime throws an exception.

The runtime surfaces JavaScript exceptions as JavaScriptError instances that preserve structured metadata from V8, giving callers access to the original error class, message, stack trace, and individual frames.

Attributes:

Name	Type	Description
name	str | None	JavaScript error class name (e.g. "TypeError"). None when non-Error values are thrown.
message	str | None	Error message string when available.
stack	str | None	V8 formatted stack trace string if provided.
frames	list[JsFrame]	Parsed stack frames populated with optional function_name, file_name, line_number, and column_number keys.

Example

>>> try:
...     runtime.eval("throw new TypeError('Invalid value')")
... except JavaScriptError as err:
...     print(err.name, err.message)
...     for frame in err.frames:
...         print(frame.get("function_name"), frame.get("file_name"))

RuntimeTerminated

Bases: RuntimeError

Raised when JavaScript execution is aborted by Runtime.terminate().

JsUndefined

Sentinel representing the JavaScript undefined value in Python.

undefined module-attribute

undefined: JsUndefined

JsFunction

Proxy for a JavaScript function returned from the runtime.

Instances execute on the underlying V8 isolate. Calling the proxy returns either a direct value (for synchronous JavaScript functions) or an awaitable object when the JavaScript side returns a pending Promise.

__call__

__call__(*args: Any, timeout: float | int | timedelta | None = ...) -> Any | Awaitable[Any]

Invoke the JavaScript function with the provided arguments. If the JS function finishes synchronously, its return value is produced directly. Otherwise, the result is awaitable and must be awaited.

Parameters:

Name	Type	Description	Default
*args	Any	Arguments forwarded into JavaScript	()
timeout	float | int | timedelta | None	Optional timeout (seconds as float/int, or datetime.timedelta)	...

Returns:

Type	Description
Any | Awaitable[Any]	Either the JavaScript return value or an awaitable resolving to it.

call_async

call_async(*args: Any, timeout: float | int | timedelta | None = ...) -> Awaitable[Any]

Always invoke the JavaScript function asynchronously, returning an awaitable regardless of whether the underlying JS completes synchronously.

close

close() -> Awaitable[None]

Release the function handle.

After closing, the proxy can no longer be awaited.

RuntimeStats

Structured snapshot of runtime resource usage and execution counters.

Instances are returned from Runtime.get_stats() and provide read-only insight into the V8 heap, total execution time, and active resources currently managed by the runtime.

Attributes:

Name	Type	Description
heap_total_bytes	int	Total heap size in bytes allocated by V8
heap_used_bytes	int	Currently used heap memory in bytes
external_memory_bytes	int	External memory tracked by V8 (e.g., ArrayBuffers)
physical_total_bytes	int	Physical memory in bytes (RSS)
total_execution_time_ms	int	Cumulative execution time in milliseconds
last_execution_time_ms	int	Duration of the most recent execution in milliseconds
last_execution_kind	str | None	Type of last operation (e.g., "eval_async", "call_function_sync")
eval_sync_count	int	Number of synchronous eval operations
eval_async_count	int	Number of asynchronous eval operations
eval_module_sync_count	int	Number of synchronous module evaluations
eval_module_async_count	int	Number of asynchronous module evaluations
call_function_async_count	int	Number of asynchronous function calls
call_function_sync_count	int	Number of synchronous function calls
active_async_ops	int	Currently active async operations
open_resources	int	Number of open resources (timers, streams, etc.)
active_timers	int	Active setTimeout timers
active_intervals	int	Active setInterval timers
active_js_streams	int	Active JavaScript ReadableStreams exposed to Python
active_py_streams	int	Active Python async iterables exposed to JavaScript
total_js_streams	int	Total JavaScript streams created
total_py_streams	int	Total Python streams created
bytes_streamed_js_to_py	int	Total bytes transferred from JavaScript to Python
bytes_streamed_py_to_js	int	Total bytes transferred from Python to JavaScript

heap_total_bytes property

heap_total_bytes: int

Total heap size in bytes allocated by V8.

heap_used_bytes property

heap_used_bytes: int

Currently used heap memory in bytes.

external_memory_bytes property

external_memory_bytes: int

External memory tracked by V8 (e.g., ArrayBuffers).

physical_total_bytes property

physical_total_bytes: int

Physical memory in bytes (RSS).

total_execution_time_ms property

total_execution_time_ms: int

Cumulative execution time in milliseconds.

last_execution_time_ms property

last_execution_time_ms: int

Duration of the most recent execution in milliseconds.

last_execution_kind property

last_execution_kind: str | None

Type of last operation (e.g., "eval_async", "call_function_sync").

eval_sync_count property

eval_sync_count: int

Number of synchronous eval operations.

eval_async_count property

eval_async_count: int

Number of asynchronous eval operations.

eval_module_sync_count property

eval_module_sync_count: int

Number of synchronous module evaluations.

eval_module_async_count property

eval_module_async_count: int

Number of asynchronous module evaluations.

call_function_async_count property

call_function_async_count: int

Number of asynchronous function calls.

call_function_sync_count property

call_function_sync_count: int

Number of synchronous function calls.

active_async_ops property

active_async_ops: int

Currently active async operations.

open_resources property

open_resources: int

Number of open resources (timers, streams, etc.).

active_timers property

active_timers: int

Active setTimeout timers.

active_intervals property

active_intervals: int

Active setInterval timers.

active_js_streams property

active_js_streams: int

Active JavaScript ReadableStreams exposed to Python.

active_py_streams property

active_py_streams: int

Active Python async iterables exposed to JavaScript.

total_js_streams property

total_js_streams: int

Total JavaScript streams created.

total_py_streams property

total_py_streams: int

Total Python streams created.

bytes_streamed_js_to_py property

bytes_streamed_js_to_py: int

Total bytes transferred from JavaScript to Python.

bytes_streamed_py_to_js property

bytes_streamed_py_to_js: int

Total bytes transferred from Python to JavaScript.

InspectorConfig

Configuration for enabling the Chrome DevTools inspector.

__init__

__init__(host: str = '127.0.0.1', port: int = 9229, *, wait_for_connection: bool = False, break_on_next_statement: bool = False, target_url: str | None = None, display_name: str | None = None) -> None

Create a new inspector configuration.

Parameters:

Name	Type	Description	Default
host	str	Host interface to bind (defaults to 127.0.0.1)	'127.0.0.1'
port	int	TCP port for the DevTools server	9229
wait_for_connection	bool	Block execution until a debugger connects	False
break_on_next_statement	bool	Pause on the first statement after a debugger attaches	False
target_url	str | None	Optional string reported to DevTools for the inspected target	None
display_name	str | None	Optional display title surfaced in chrome://inspect	None

endpoint

endpoint() -> str

Return the host:port pair that DevTools should connect to.

InspectorEndpoints

Runtime inspector metadata exposing DevTools URLs.

Attributes:

Name	Type	Description
id	str	Unique identifier for the inspector session
websocket_url	str	WebSocket URL for the Chrome DevTools Protocol
devtools_frontend_url	str	DevTools frontend URL to open in Chrome
title	str	Display title for the inspector target
description	str	Description of the inspector target
target_url	str	URL of the target being inspected
favicon_url	str	Favicon URL for the inspector target
host	str	Host address where the inspector is listening

SnapshotBuilder

Build a V8 snapshot covering a custom bootstrap script.

Use execute_script() to run multiple scripts before calling build() to produce the serialized bytes.

__init__

__init__(*, bootstrap: str | None = None, enable_console: bool | None = False) -> None

Create a snapshot builder.

Parameters:

Name	Type	Description	Default
bootstrap	str | None	Optional JavaScript source run before any scripts added via execute_script.	None
enable_console	bool | None	Whether console APIs remain available while preparing the snapshot. Defaults to False (console is disabled by default).	False

execute_script

execute_script(name: str, source: str) -> None

Run a JavaScript script inside the snapshot builder.

Parameters:

Name	Type	Description	Default
name	str	Identifier used in stack traces / debugging.	required
source	str	Source text to compile and execute. The code is executed as a classic script (not an ES module), so import / export syntax is rejected. Wrap CommonJS bundles or other globals in an IIFE before calling this method so only plain script statements reach V8.	required

build

build() -> bytes

Finalize the snapshot and return its serialized bytes.