PyMiniRacer (Original - Deprecated)

Warnings

• breaking The `py-mini-racer` library (sqreen/PyMiniRacer) is deprecated and no longer actively maintained. The recommended successor project is `mini-racer` (bpcreech/PyMiniRacer), which provides updated V8 versions and continued development. Users are strongly encouraged to migrate.
  Fix: Migrate to the `mini-racer` library by installing `pip install mini-racer` and updating import statements if necessary. Consult the `mini-racer` documentation for migration details.
• breaking As of v0.6.0, V8 was switched to single-threaded mode by default to prevent crashes after process forks. If your application relied on multi-threaded V8 operations within the same process or expected specific behavior after forking, this change might affect stability or performance.
  Fix: Review application architecture for multi-process or multi-threaded JavaScript execution. If multi-threading within V8 is critical, investigate the `mini-racer` successor which might offer different configuration options or alternative solutions.
• breaking Version 0.6.0 switched V8 to strict mode by default. JavaScript code that previously ran without issues in non-strict mode (e.g., using undeclared variables, duplicate parameter names) might now throw errors.
  Fix: Ensure all JavaScript code executed within PyMiniRacer is compliant with ECMAScript strict mode. This typically involves fixing common JavaScript 'sloppy mode' practices.
• gotcha Building PyMiniRacer from source is a resource-intensive process, requiring several GB of disk space and approximately 60 minutes. Furthermore, the V8 build system historically required a Python 2.7 executable.
  Fix: Prefer installing pre-built wheels (`pip install py-mini-racer`). If building from source is necessary, ensure you have sufficient disk space, time, and the correct Python 2.7 environment for the V8 build steps (even if using Python 3 for the final package). Consider using the `mini-racer` package, which has more modern build processes.
• gotcha The `eval()` method in `py-mini-racer` only supports returning primitive data types (numbers, strings, buffers). To return composite types like JavaScript objects or arrays, you must use the `call()` method.
  Fix: Use `ctx.call("functionName", args...)` when expecting JavaScript objects, arrays, or other composite structures as return values. Use `ctx.eval("jsExpression")` for primitive returns.
• gotcha This version of PyMiniRacer does not support attaching Python objects or functions to the JavaScript context, meaning you cannot directly call Python code from JavaScript.
  Fix: Design your application to handle callbacks from JavaScript to Python using alternative mechanisms (e.g., polling for results, or re-evaluating context in Python). The successor `mini-racer` introduced `wrap_py_function` for this functionality in v0.12.0.

Install

• pip install py-mini-racer Install py-mini-racer

Imports

• MiniRacer

  from py_mini_racer import MiniRacer

  The primary class for interacting with the V8 engine.

Quickstart

This quickstart demonstrates how to initialize a `MiniRacer` context and execute basic JavaScript code using `eval()` and `call()`. `eval()` is suitable for primitive return types, while `call()` is used for composite types like objects, which are serialized via JSON.

from py_mini_racer import MiniRacer

# Create a new MiniRacer context
ctx = MiniRacer()

# Evaluate JavaScript code
result = ctx.eval("1 + 1")
print(f"1 + 1 = {result}")

# Evaluate more complex JavaScript with variables
ctx.eval("var x = {company: 'Acme'};")
company_name = ctx.eval("x.company")
print(f"Company name: {company_name}")

# Use .call() for composite types, .eval() for primitives
def_func = ctx.eval("var fun = () => ({ foo: 1 });")
composite_result = ctx.call("fun")
print(f"Composite result: {composite_result}")