Mini Racer

0.14.1 · active · verified Sun Apr 12

Mini Racer is a minimal, modern embedded V8 JavaScript engine for Python. It allows executing JavaScript code directly within Python applications. As of version 0.14.1, it provides a stable API for evaluating JS, calling functions, and managing execution contexts. The project has a relatively frequent release cadence, with minor updates and bug fixes appearing every few weeks or months.

Warnings

breaking The import path for `MiniRacer` changed significantly. Direct class import `from py_mini_racer import MiniRacer` is now required.
Fix: Update your import statements from `import py_mini_racer; mr = py_mini_racer.MiniRacer()` to `from py_mini_racer import MiniRacer; mr = MiniRacer()`.
breaking JavaScript errors no longer propagate as generic Python exceptions but raise a specific `MiniRacerEvalError`.
Fix: Wrap your `mr.eval()` and `mr.call()` calls in `try...except MiniRacerEvalError` blocks to catch and handle JS errors correctly.
breaking The `v8_args` parameter was removed from the `MiniRacer` constructor.
Fix: Remove the `v8_args` parameter when initializing `MiniRacer`. Custom V8 arguments are no longer directly configurable via the constructor.
breaking The `timeout` parameter was removed from the `MiniRacer` constructor. While it was briefly available in v0.12.x, it was removed from the constructor in v0.13.0.
Fix: Do not pass a `timeout` argument to the `MiniRacer` constructor. The `timeout` parameter remains available for the `eval()` and `call()` methods for per-operation timeouts.
gotcha A `MiniRacer` instance is NOT thread-safe. Accessing a single instance from multiple threads concurrently can lead to crashes or undefined behavior.
Fix: Instantiate a separate `MiniRacer` object for each thread that needs to execute JavaScript code. Alternatively, use a thread-safe mechanism like a queue or a lock to serialize access to a single instance.

Install

pip install mini-racer Install latest version

Imports

MiniRacer
```
from py_mini_racer import MiniRacer
```
Since v0.12.0, the `MiniRacer` class is directly importable from the `py_mini_racer` module. Previously, it was accessed as `py_mini_racer.MiniRacer`.
MiniRacerEvalError
```
from py_mini_racer import MiniRacerEvalError
```
Used for catching JavaScript execution errors.

Quickstart

This quickstart demonstrates how to initialize a `MiniRacer` context, evaluate JavaScript code, call a JavaScript function with Python arguments, and handle JavaScript execution errors using `MiniRacerEvalError`.

from py_mini_racer import MiniRacer, MiniRacerEvalError

# Initialize a MiniRacer context
mr = MiniRacer()

# Evaluate JavaScript code to define a function
mr.eval("function add(a, b) { return a + b; }")

# Call the JavaScript function with Python arguments
result = mr.call("add", 1, 2)
print(f"Result of add(1, 2): {result}")

# Evaluate a simple expression (e.g., getting V8 version)
js_version = mr.eval("process.versions.v8")
print(f"V8 version: {js_version}")

# Demonstrate error handling
try:
    mr.eval("throw new Error('Something went wrong!');")
excep MiniRacerEvalError as e:
    print(f"Caught MiniRacerEvalError: {e}")

view raw JSON →