Python Wrapper for Google V8 Engine

13.1.201.22 · active · verified Sun Apr 12

STPyV8 is a Python wrapper for the Google V8 JavaScript engine, enabling seamless interoperability between Python 3 and JavaScript. It serves as a modern fork of the original PyV8 project, continuously updated by Cloudflare to align with the latest Google V8 engine branches and Python 3 versions. The library receives frequent updates, often coinciding with new V8 releases, and provides pre-built wheels for various platforms.

Warnings

breaking STPyV8 requires Python 3.9 or newer for recent versions. Attempting to install or use with older Python versions may lead to build failures or runtime errors.
Fix: Ensure your Python environment is 3.9+ (e.g., `python3.9 -m pip install stpyv8`).
gotcha When building STPyV8 from source (e.g., if no pre-built wheel is available for your platform/Python version), you will need a C++ compiler (GCC/clang on Linux/macOS, MSVC on Windows), Python development headers, and potentially Boost libraries (though less common for recent versions).
Fix: Refer to the official GitHub repository for detailed build instructions specific to your operating system. For many users, `pip install stpyv8` will automatically fetch a pre-built wheel, avoiding source compilation.
gotcha For complex JavaScript code, the underlying V8 engine may require an ICU data file (`icudtl.dat`). If this file is not correctly packaged with your STPyV8 installation (e.g., when building from source or with certain distribution methods), V8 operations can fail silently or with errors.
Fix: Manually copy `icudtl.dat` to the appropriate STPyV8 ICU data folder (e.g., `/usr/share/stpyv8` on Linux, `/Library/Application Support/STPyV8/` on macOS). This file is usually included in zip releases alongside the wheels if manual installation is needed.
gotcha STPyV8's direct `eval()` might not fully support modern JavaScript ES Modules (`import`/`export` syntax) out-of-the-box, potentially leading to `SyntaxError: Cannot use import statement outside a module`.
Fix: Consider bundling your JavaScript code using tools like Webpack or Rollup to produce a single, self-contained file without `import`/`export` statements. Alternatively, explore if V8's module loading capabilities can be exposed or configured within STPyV8's `JSContext`.
gotcha There are reported issues with STPyV8 in multi-threaded environments, including segmentation faults when used in separate threads. The presence of dual garbage collectors (Python and V8) can also lead to complexities and potential memory management issues in scenarios involving long-lived objects spanning both VMs.
Fix: Exercise caution when using STPyV8 in threaded applications. If possible, isolate V8 context creation and usage to a single thread. Design your application to minimize long-lived Python objects exposed to JavaScript or vice-versa to mitigate potential GC conflicts. Monitor GitHub issues for updates on threading stability.

Install

pip install stpyv8 Install via pip

Imports

STPyV8
```
import STPyV8
```
JSContext
```
from STPyV8 import JSContext
```
JSClass
```
from STPyV8 import JSClass
```

Quickstart

This example demonstrates how to initialize a V8 JavaScript context, evaluate a simple JavaScript expression, and export a Python class method to be callable from within the JavaScript context.

import STPyV8

with STPyV8.JSContext() as ctxt:
    result = ctxt.eval("'Hello, ' + 'STPyV8!'");
    print(result)

# Exporting a Python function to JavaScript
class MyFunctions(STPyV8.JSClass):
    def multiply(self, a, b):
        return a * b

my_funcs = MyFunctions()
with STPyV8.JSContext(my_funcs) as ctxt:
    js_code = "this.multiply(5, 3);"
    multiplication_result = ctxt.eval(js_code)
    print(f"Multiplication result: {multiplication_result}")

view raw JSON →