Minimal, modern embedded V8 for Python.
MiniRacer can be easily used by Django or Flask projects to minify assets, run babel or WASM modules.
PyMiniRacer was created by Sqreen, and originally lived at
https://github.com/sqreen/PyMiniRacer with the PyPI package
py-mini-racer.
As of March 2024, after a few years without updates, I have
reached out to the original Sqreen team. We agreed that I should fork PyMiniRacer,
giving it a new home at https://github.com/bpcreech/PyMiniRacer with a new PyPI
package mini-racer (note: no py-). It now
has a new version for the
first time since 2021!
MiniRacer is straightforward to use:
$ pip install mini-racer
and then:
$ python3
>>> from py_mini_racer import MiniRacer
>>> ctx = MiniRacer()
>>> ctx.eval("1+1")
2
>>> ctx.eval("var x = {company: 'Sqreen'}; x.company")
'Sqreen'
>>> print(ctx.eval("'❤'"))
❤
>>> ctx.eval("var fun = () => ({ foo: 1 });")
Variables are kept inside of a context:
>>> ctx.eval("x.company")
'Sqreen'
You can evaluate whole scripts within JavaScript, or define and return JavaScript function objects and call them from Python (new in v0.11.0):
>>> square = ctx.eval("a => a*a")
>>> square(4)
16
JavaScript Objects and Arrays are modeled in Python as dictionaries and lists (or, more
precisely,
MutableMapping
and
MutableSequence
instances), respectively (new in v0.11.0):
>>> obj = ctx.eval("var obj = {'foo': 'bar'}; obj")
>>> obj["foo"]
'bar'
>>> list(obj.keys())
['foo']
>>> arr = ctx.eval("var arr = ['a', 'b']; arr")
>>> arr[1]
'b'
>>> 'a' in arr
True
>>> arr.append(obj)
>>> ctx.eval("JSON.stringify(arr)")
'["a","b",{"foo":"bar"}]'
Meanwhile, call uses JSON to transfer data between JavaScript and Python, and converts
data in bulk:
>>> ctx.call("fun")
{'foo': 1}
Composite values are serialized using JSON. Use a custom JSON encoder when sending non-JSON encodable parameters:
import json
from datetime import datetime
class CustomEncoder(json.JSONEncoder):
def default(self, obj):
if isinstance(obj, datetime):
return obj.isoformat()
return json.JSONEncoder.default(self, obj)
>>> ctx.eval("var f = function(args) { return args; }")
>>> ctx.call("f", datetime.now(), encoder=CustomEncoder)
'2017-03-31T16:51:02.474118'
MiniRacer is ES6 capable:
>>> ctx.execute("[1,2,3].includes(5)")
False
MiniRacer supports asynchronous execution using JS Promise instances (new in
v0.10.0):
>>> promise = ctx.eval(
... "new Promise((res, rej) => setTimeout(() => res(42), 10000))")
>>> promise.get() # blocks for 10 seconds, and then:
42
You can use JS Promise instances with Python async (new in v0.10.0):
>>> import asyncio
>>> async def demo():
... promise = ctx.eval(
... "new Promise((res, rej) => setTimeout(() => res(42), 10000))")
... return await promise
...
>>> asyncio.run(demo()) # blocks for 10 seconds, and then:
42
JavaScript null and undefined are modeled in Python as None and JSUndefined,
respectively:
>>> list(ctx.eval("[undefined, null]"))
[JSUndefined, None]
You can install callbacks from JavaScript to Python (new in v0.12.0):
>>> async def read_file(fn):
... with open(fn) as f: # (or aiofiles would be even better here)
... return f.read()
...
>>> async def get_dictionary():
... async with ctx.wrap_py_function(read_file) as jsfunc:
... # "Install" our JS function on the global "this" object:
... ctx.eval('this')['read_file'] = jsfunc
... d = await ctx.eval('this.read_file("/usr/share/dict/words")')
... return d.split()
...
>>> dictionary = asyncio.run(get_dictionary())
>>> print(dictionary[0:10])
['A', 'AA', 'AAA', "AA's", 'AB', 'ABC', "ABC's", 'ABCs', 'ABM', "ABM's"]
Note that adding Python callbacks may degrade the security properties of PyMiniRacer! See PyMiniRacer's security goals.
MiniRacer supports the ECMA Intl API:
# Indonesian dates!
>>> ctx.eval('Intl.DateTimeFormat(["ban", "id"]).format(new Date())')
'16/3/2024'
V8 heap information can be retrieved:
>>> ctx.heap_stats()
{'total_physical_size': 1613896,
'used_heap_size': 1512520,
'total_heap_size': 3997696,
'total_heap_size_executable': 3145728,
'heap_size_limit': 1501560832}
A WASM example is available in the
tests.
PyMiniRacer is compatible with Python 3.8-3.12 and is based on ctypes.
PyMiniRacer is distributed using wheels on PyPI. The wheels are intended to provide compatibility with:
| OS | x86_64 | aarch64 |
|---|---|---|
| macOS ≥ 10.9 | ✓ | ✓ |
| Windows ≥ 10 | ✓ | ✖ |
| Ubuntu ≥ 20.04 | ✓ | ✓ |
| Debian ≥ 11 | ✓ | ✓ |
| RHEL ≥ 9 | ✓ | ✓ |
| other Linuxes with glibc ≥ 2.31 | ✓ | ✓ |
| Alpine ≥ 3.19 | ✓ | ✓ |
| other Linux with musl ≥ 1.2 | ✓ | ✓ |
If you have a up-to-date pip and it doesn't use a wheel, you might have an environment for which no wheel is built. Please open an issue.
Built with love by Sqreen.
PyMiniRacer launch was described in
this blog post.
PyMiniRacer is inspired by mini_racer, built for the Ruby world by Sam Saffron.
In 2024, PyMiniRacer was revived, and adopted by Ben Creech. Upon discussion with the original Sqreen authors, we decided to re-launch PyMiniRacer as a fork under https://github.com/bpcreech/PyMiniRacer and https://pypi.org/project/mini-racer/.
wrap_py_function while
we're tearing it down.Add optional context manager and .close() semantics to Python MiniRacer class.
Fixed a potential hang on MiniRacer teardown if MiniRacer is executing a microtask which loops infinitely.
Switch C++ side of MiniRacer to a more straightforward object lifecycle management model.
Added support for installing callbacks from JS back into Python, using MiniRacer.wrap_py_function.
Refactored the Python implementation into many internal files. This should mostly not
present a breaking change, except for code which reaches into internal
(_-prefixed) variables.
Fixed Python crash on long-running microtasks, introduced in v0.8.1 (before which long-running microtasks would probably not run at all).
Fixed memory leak on the exception object reported when an eval times out.
Hardened the memory management of JS value interchange, context tracking, and asynchronous task tracking between C++ and Python.
Added exhaustive typing (now with a MyPy pre-commit to verify!)
Added a test asserting that the v8 sandbox is enabled on all platforms we build wheels for.
Added a MutableMapping (dict-like) interface for all derivatives of JS Objects,
and a MutableSequence (list-like) interface for JS Arrays. You can now use
Pythonic idioms to read and write Object properties and Array elements in Python,
including recursively (i.e., you can read Objects embedded in other objects, and
embed your own).
Added ability to directly call JSFunction objects from Python. E.g.,
mr.eval("a => a*a")(4) parses the given number-squaring code into a function,
returns a handle to that function to Python, calls it with the number 4, and
recieves the result of 16.
Added a JSUndefined Python object to model JavaScript undefined. This is needed to
properly implement the above interface for reading Object and Array elements.
Unfortunately, this may present a breaking change for users who assume JavaScript
undefined is modeled as Python None.
Removed an old optimization for eval on simple no-argument function calls (i.e.,
myfunc()). The optimization only delivered about a 17% speedup on no-op calls (and
helped relatively less on calls which actually did work), and for the purpose of
optimizing repeated calls to the same function, it's now redundant with extracting
and calling the function from Python, e.g., mr.eval("myfunc")().
Hardening (meaning "fixing potential but not-yet-seen bugs") related to freeing
BinaryValue instances (which convey data from C++ to Python).
More hardening related to race conditions on teardown of the MiniRacer object in the
unlikely condition that eval operations are still executing on the C++ side, and
abandoned on the Python side, when Python attempts to garbage collect the
MiniRacer object.
Updated to V8 12.3 from V8 12.2 now that Chromium stable is on 12.3.
Added Python-side support for JS Promises. You can now return a JS Promise from code
executed by MiniRacer.eval, and PyMiniRacer will convert it to a Python object
which has a blocking promise.get() method, and also supports await promise in
async Python functions.
Added a setTimeout and clearTimeout. These common functions live in the Web API
standard, not the ECMAScript standard, and thus don't come with V8, but they're so
ubiquitious we now ship an implemention with PyMiniRacer.
Revamped JS execution model to be out-of-thread. Python/C++ interaction now happens via callbacks.
Consequently, Control+C (KeyboardInterrupt) now interrupts JS execution.
Hardened C++-side thread safety model, resolving potential race conditions introduced in v0.8.1 (but not actually reported as happening anywhere).
Further improved JS exception reporting; exception reports now show the offending code where possible.
Introduced timeout_sec parameter to eval, call, and execute to replace the
timeout, which unfortunately uses milliseconds (unlike the Python standard
library). In the future we may emit deprecation warnings for use of timeout.
eval-specific)
limit, since that's how it worked all along anyway. The max_memory eval argument
still works for backwards compatibility purposes.str instead of bytes (they should all
be str now).EXTENSION_PATH and
EXTENSION_NAME module variables, and MiniRacer.v8_flags and MiniRacer.ext
class variable have all been removed.Intl APIFAQs
Minimal, modern embedded V8 for Python.
We found that mini-racer demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.
Security News
Research
Socket researchers found a malicious Maven package impersonating the legitimate ‘XZ for Java’ library, introducing a backdoor for remote code execution.