STPyV8 Documentation

In STPyV8, V8 isolates maintain completely separate states. To ensure stability, follow these threading rules:

1. No Cross-Isolate Object Sharing: Objects created within one isolate must never be used in another isolate.
2. Single-Threaded Access: An isolate can be entered by at most one thread at any given time.
3. Parallelism: While a single isolate is restricted to one thread, you can create multiple isolates and use them in parallel across multiple threads.
4. Synchronization: Use the JSIsolate context management (Locker/Unlocker API) to synchronize access to an isolate.

Every JSContext has a global object that is accessible from both Python and JavaScript.

• From Python: Use the JSContext.locals attribute to access or modify global variables.
• From JavaScript: Use the global namespace directly.

STPyV8 handles type conversion, function calls, and exception translation between the two languages automatically.

with JSContext() as ctxt:
    ctxt.eval("a = 1")
    print(ctxt.locals.a)     # 1

    ctxt.locals.a = 2
    print(ctxt.eval("a"))    # 2

A JSContext is a sandboxed execution context that provides its own set of built-in objects and functions. To execute JavaScript code, you must enter a context.

Best Practice: Use the Python with statement to ensure the context is entered and exited correctly, which automatically handles resource release.

Manual Lifecycle:

1. Create an instance: ctxt = JSContext()
2. Enter the context: ctxt.enter()
3. Execute code: ctxt.eval("code")
4. Leave the context: ctxt.leave()

# Recommended way using context manager
with JSContext() as ctxt:
    print(ctxt.eval("1+2")) # 3

Instead of using JSContext.eval for immediate execution, you can use JSEngine.compile to parse JavaScript code into a JSScript object. This approach is more efficient for reusing the same code across different contexts and allows for code inspection via the Abstract Syntax Tree (AST).

To use this pattern:

1. Create a JSEngine instance.
2. Call engine.compile(source) to get a JSScript object.
3. Use JSScript.run() to execute the compiled code.
4. Access JSScript.source to retrieve the original source string.

from STPyV8 import *

with JSContext() as ctxt:
    with JSEngine() as engine:
        s = engine.compile("1+2")

        print(s.source) # "1+2"
        print(s.run())  # 3

If no pre-built wheels are available for your specific platform and Python version, you must build STPyV8 from source.

Requirements:

• Boost: STPyV8 requires Boost.Python. While most Linux distributions provide Boost packages, you may need to download and build the latest version from the Boost website if packages are unavailable.

Build Commands: Use setup.py to build and install the package. You can also run tests using pytest or create a distribution package using bdist.

# Build and install
$ python setup.py build
$ sudo python setup.py install

# Run tests (requires pytest)
$ pytest tests

# Build a distribution package (Linux/Mac)
$ python setup.py bdist

For most users, STPyV8 can be installed directly from PyPI. STPyV8 officially supports Python 3.9+.

Starting from version v12.0.267.14, manual installation of boost-python and other Boost dependencies is no longer required when using the PyPI package.

$ pip install stpyv8

STPyV8 automatically translates JavaScript exceptions into Python exceptions. Well-known JavaScript exceptions are mapped to their Python equivalents, while other exceptions are wrapped in a JSError instance. You can use standard try...except blocks in Python to catch these.

from STPyV8 import JSContext, JSError

with JSContext() as ctxt:
    try:
        ctxt.eval("throw Error('test');")
    except JSError as e:
        print(e)            # JSError: Error: test (  @ 1 : 6 )  -> throw Error('test');
        print(e.name)       # Error
        print(e.message)   # test