QuickJS Python Wrapper

1.19.4 · maintenance · verified Wed Apr 15

QuickJS is a Python wrapper around the QuickJS C library. It enables Python applications to execute JavaScript code and seamlessly translates Python types like str, float, bool, list, and dict to and from JavaScript. The library handles QuickJS's underlying thread-hostile nature by ensuring that all calls to the same JS runtime are managed within the same thread. The current version is 1.19.4, with releases occurring periodically, though the primary GitHub repository is currently archived.

Warnings

gotcha The `Context` class is thread-hostile, meaning that all interactions with a `Context` instance or objects derived from it must occur within the same Python thread. The `Function` class, however, is designed to be thread-safe.
Fix: Prefer using `Function` for thread-safe operations. If using `Context` directly, ensure all calls are serialized to a single thread or use separate `Context` instances per thread.
breaking The official GitHub repository (PetterS/quickjs) linked by PyPI is marked as 'Archived due to lack of maintenance'. While PyPI still shows recent releases (e.g., 1.19.4 in November 2023), this indicates that the primary development source is no longer actively maintained. Future updates, bug fixes, or compatibility with newer Python/QuickJS versions might be uncertain or originate from unlinked forks.
Fix: Monitor PyPI and other community resources for information on alternative forks or maintenance efforts if new features or critical updates are required beyond existing releases.
gotcha Installation on Windows systems often requires a C++ compiler (e.g., Microsoft C++ Build Tools) if pre-built wheels are not available for your specific Python version and architecture. Without it, `pip install quickjs` may fail during the 'Building wheel' step.
Fix: For Windows, install 'Desktop development with C++' tools via the Visual Studio Installer. Alternatively, try `pip install --only-binary :all: quickjs` or upgrade Python to a version for which official wheels are provided.
gotcha QuickJS is a minimalist JavaScript engine and does not include browser-specific APIs like `setTimeout`, `setInterval`, or DOM manipulation functions by default. Attempting to use these will result in `ReferenceError`.
Fix: If such functionality is required, you must explicitly provide Python implementations to the JavaScript context using `add_callable` or similar mechanisms, or use a more comprehensive JavaScript runtime if browser APIs are essential.

Install

pip install quickjs Install latest version

Imports

Function
```
from quickjs import Function
```
The primary class for executing JavaScript functions.
Context
```
from quickjs import Context
```
Allows for lower-level interaction with the QuickJS runtime context, but is thread-hostile.

Quickstart

This example demonstrates how to define and execute a simple JavaScript function using the `quickjs.Function` class. Python values are automatically converted to JavaScript types, and the return value is converted back to a Python type.

from quickjs import Function

# Create a callable JavaScript function from Python
f = Function("f", """
function adder(a, b) {
    return a + b;
}
function f(a, b) {
    return adder(a, b);
}
""")

# Call the JavaScript function from Python
result = f(1, 2)
print(f"Result of JavaScript function call: {result}")

assert result == 3

view raw JSON →