Metadata-Version: 2.1
Name: mini-racer
Version: 0.8.0
Summary: Minimal, modern embedded V8 for Python.
Project-URL: Homepage, https://github.com/bpcreech/PyMiniRacer
Author-email: bpcreech <mini-racer@bpcreech.com>, Sqreen <support@sqreen.com>
License-Expression: ISC
License-File: AUTHORS.md
License-File: LICENSE
Keywords: py_mini_racer
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.8
Description-Content-Type: text/markdown

[![PyPI status indicator](https://img.shields.io/pypi/v/mini_racer.svg)](https://pypi.python.org/pypi/mini_racer)
[![Github workflow status indicator](https://github.com/bpcreech/PyMiniRacer/actions/workflows/build.yml/badge.svg)](https://github.com/bpcreech/PyMiniRacer/actions/workflows/build.yml)
[![ISC License](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)

Minimal, modern embedded V8 for Python.

![MiniRacer logo: a V8 with a very snakey 8](https://github.com/bpcreech/PyMiniRacer/raw/main/py_mini_racer.png)

## Features

- Latest ECMAScript support
- Web Assembly support
- Unicode support
- Thread safe
- Re-usable contexts

MiniRacer can be easily used by Django or Flask projects to minify assets, run babel or
WASM modules.

## New home! (As of March 2024)

PyMiniRacer was created by [Sqreen](https://github.com/sqreen), and originally lived at
<https://github.com/sqreen/PyMiniRacer> with the PyPI package
[`py-mini-racer`](https://pypi.org/project/py-mini-racer/).

As of March 2024, after a few years without updates, [I](https://bpcreech.com) 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`](https://pypi.org/project/mini-racer/) (*note: no `py-`*). It now
has [a new version](https://bpcreech.com/PyMiniRacer/history/#070-2024-03-06) for the
first time since 2021!

## Examples

MiniRacer is straightforward to use:

```sh
    $ pip install mini-racer
```

and then:

```python
    $ 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:

```python
    >>> ctx.eval("x.company")
    'Sqreen'
```

While `eval` only supports returning primitive data types such as strings, `call`
supports returning composite types such as objects:

```python
    >>> ctx.call("fun")
    {'foo': 1}
```

Composite values are serialized using JSON. Use a custom JSON encoder when sending
non-JSON encodable parameters:

```python
    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)
```

```python
    >>> 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:

```python
    >>> ctx.execute("[1,2,3].includes(5)")
    False
```

MiniRacer supports [the ECMA `Intl` API](https://tc39.es/ecma402/):

```python
    # Indonesian dates!
    >>> ctx.eval('Intl.DateTimeFormat(["ban", "id"]).format(new Date())')
    '16/3/2024'
```

V8 heap information can be retrieved:

```python
    >>> 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`](https://github.com/bpcreech/PyMiniRacer/blob/master/tests/test_wasm.py).

## Compatibility

PyMiniRacer is compatible with Python 3.8-3.12 and is based on `ctypes`.

PyMiniRacer is distributed using [wheels](https://pythonwheels.com/) on
[PyPI](https://pypi.org/). The wheels are intended to provide compatibility with:

| OS                              | x86_64 | aarch64 |
| ------------------------------- | ------ | ------- |
| macOS ≥ 10.9                    | ✓      | ✓       |
| Windows ≥ 10                    | ✓      | ✖       |
| Ubuntu ≥ 20.04                  | ✓      | ✓       |
| Debian ≥ 11                     | ✓      | ✓       |
| RHEL ≥ 8                        | ✓      | ✓       |
| 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.

## Developing and releasing PyMiniRacer

See [the contribution guide](CONTRIBUTING.md).

## Credits

Built with love by [Sqreen](https://www.sqreen.com).

PyMiniRacer launch was described in
[`this blog post`](https://web.archive.org/web/20230526172627/https://blog.sqreen.com/embedding-javascript-into-python/).

PyMiniRacer is inspired by [mini_racer](https://github.com/SamSaffron/mini_racer), built
for the Ruby world by Sam Saffron.

In 2024, PyMiniRacer was revived, and adopted by [Ben Creech](https://bpcreech.com).
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/>.
## Release history


## 0.8.0 (2024-03-18)

- General overhaul of C++ implementation to better adhere to modern best practice. This
    should have no visible impact except for the following notes...
- Exposed the hard memory limit as a context-specific (as opposed to `eval`-specific)
    limit, since that's how it worked all along anyway. The `max_memory` `eval` argument
    still works for backwards compatibility purposes.
- Correct message type of some exceptions to `str` instead of `bytes` (they should all
    be `str` now).
- Added better messages for JS parse errors.
- Added backtraces for more JS errors.
- Added some really basic Python typing.

## 0.7.0 (2024-03-06)

- Update V8 to 12.2
- Drop Python 2 support
- Fix small Python 3.12 issue and add testing for Python 3.9-3.12
- Add aarch64 support for Mac and Linux
- Revamp DLL loading to be compliant with Python 3.9-style resource loading. This may
    present a small breaking change for advanced usage; the `EXTENSION_PATH` and
    `EXTENSION_NAME` module variables, and `MiniRacer.v8_flags` and `MiniRacer.ext`
    class variable have all been removed.
- Add support for the [ECMAScript internalization API](https://v8.dev/docs/i18n) and
    thus [the ECMA `Intl` API](https://tc39.es/ecma402/) 
- Use [fast startup snapshots](https://v8.dev/blog/custom-startup-snapshots)
- Switch from setuptools to Hatch
- Switch from tox to Hatch
- Switch from flake8 and isort to Hatch's wrapper of Ruff
- Switch from Sphinx to mkdocs (and hatch-mkdocs)
- Switch from unittest to pytest
- Add ARCHITECTURE.md and lots of code comments

## 0.6.0 (2020-04-20)

- Update V8 to 8.9
- Optimize function calls without arguments
- Switch V8 to single threaded mode to avoid crashes after fork
- Switch to strict mode by default
- Revamp documentation

## 0.5.0 (2020-02-25)

- Update V8 to 8.8

## 0.4.0 (2020-09-22)

- Universal wheels for Linux, Mac and Windows
- Fallback to source package for Alpine Linux

## 0.3.0 (2020-06-29)

- Introduce a strict mode
- Fix array conversion when size changes dynamically (CVE-2020-25489)

## 0.2.0 (2020-03-11)

- Support for Alpine Linux
- Avoid pip private modules in setup.py

## 0.2.0b1 (2020-01-09)

- Support for Windows 64 bits
- Support for Python 3.8
- Upgrade V8 to 7.8
- Support soft memory limits

## 0.1.18 (2019-01-04)

- Support memory and time limits

## 0.1.17 (2018-19-12)

- Upgrade libv8
- Fix a memory leak

## 0.1.16 (2018-07-11)

- Add wheel for Python without PyMalloc

## 0.1.15 (2018-06-18)

- Add wheel for Python 3.7

## 0.1.14 (2018-05-25)

- Add support for pip 10
- Update package metadata

## 0.1.13 (2018-03-15)

- Add heap_stats function
- Fix issue with returned strings containing null bytes

## 0.1.12 (2018-17-04)

- Remove dependency to enum

## 0.1.11 (2017-07-11)

- Add compatibility for centos6

## 0.1.10 (2017-03-31)

- Add the possibility to pass a custom JSON encoder in call.

## 0.1.9 (2017-03-24)

- Fix the compilation for Ubuntu 12.04 and glibc \< 2.17.

## 0.1.8 (2017-03-02)

- Update targets build for better compatibility with old Mac OS X and linux platforms.

## 0.1.7 (2016-10-04)

- Improve general performances of the JS execution.
- Add the possibility to build a different version of V8 (for example with debug
    symbols).
- Fix a conflict that could happens between statically linked libraries and dynamic
    ones.

## 0.1.6 (2016-08-12)

- Add error message when py_mini_racer sdist fails to build asking to update pip in
    order to download the pre-compiled wheel instead of the source distribution.

## 0.1.5 (2016-08-04)

- Build py_mini_racer against a static Python. When built against a shared library
    python, it doesn't work with a static Python.

## 0.1.4 (2016-08-04)

- Ensure JSEvalException message is converted to unicode

## 0.1.3 (2016-08-04)

- Fix extension loading for python3
- Add a make target for building distributions (sdist + wheels)
- Fix eval conversion for python 3

## 0.1.2 (2016-08-03)

- Fix date support
- Fix Dockerfile for generating python3 wheels

## 0.1.1 (2016-08-02)

- Fix sdist distribution.

## 0.1.0 (2016-08-01)

- First release on PyPI.
