Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

Minimal, modern embedded V8 for Python.

Project description

===============================
Python Mini Racer
===============================

.. image:: https://img.shields.io/pypi/v/py_mini_racer.svg
:target: https://pypi.python.org/pypi/py_mini_racer

Minimal, modern embedded V8 for Python.

* Free software: ISC license

.. image:: https://github.com/sqreen/PyMiniRacer/raw/master/data/py_mini_racer.png

Features
--------

* Unicode support
* Thread safe
* Re-usable contexts
* Binary object is Python agnostic

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

Examples
--------

py_mini_racer is straightforward to use:

.. code-block:: python

>>> from py_mini_racer import py_mini_racer
>>> ctx = py_mini_racer.MiniRacer()
>>> ctx.eval('1+1')
2
>>> ctx.eval("var x = {company: 'Sqreen'}; x.company")
u'Sqreen'
>>> print ctx.eval(u"'\N{HEAVY BLACK HEART}'")

>>> ctx.eval("var fun = () => ({ foo: 1 });")
>>> ctx.call("fun")
{u'foo': 1}

Variables are kept inside of a context:

.. code-block:: python

>>> ctx.eval("x.company")
u'Sqreen'


You can give directly a custom JSON encoder when sending non-JSON encodable
parameters:

.. code-block:: 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)


.. code-block:: python

>>> ctx.eval("var f = function(args) { return args; }")
>>> ctx.call("f", datetime.now(), encoder=CustomEncoder)
u'2017-03-31T16:51:02.474118'


PyMiniRacer is ES6 capable:

.. code-block:: python

>>> ctx.eval("[1,2,3].includes(5)")
False

V8 heap information can be retrieved:

.. code-block:: python

>>> ctx.heap_stats()
{u'total_physical_size': 1613896,
u'used_heap_size': 1512520,
u'total_heap_size': 3997696,
u'total_heap_size_executable': 3145728,
u'heap_size_limit': 1501560832}


Compatibility
-------------

PyMiniRacer is compatible with Python 2 and Python 3. Wheels are generated for python 2.7 and python 3.4 to python 3.6.

Binary builds availability
--------------------------

The PyMiniRacer binary builds have been tested on x86_64 with:

* OSX 10.10
* Ubuntu >= 12.04
* Debian >= 7
* CentOS >= 6

You need pip >= 8.1 to install the wheels - you can check and upgrade yours in
this way:

.. code-block:: bash

$ pip --version
$ pip install --upgrade pip

It should work on any Linux with a libc >= 2.12 and a wheel compatible pip (>=
8.1).

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.

Installation
------------

We built Python wheels (prebuilt binaries) for OSX 64 bits and Linux 64 bits -
most recent distributions. You need pip >= 1.4 and setuptools >= 0.8.

.. code:: bash

$ pip install py-mini-racer

Build
-----

You can build v8 with the command:

.. code:: bash

$ python setup.py build_v8

You can also build the ctype extension:

.. code:: bash

$ python setup.py build_ext

Which automatically builds v8.

You can generate a wheel with the command:

.. code:: bash

$ python setup.py bdist_wheel

which builds v8, the extension, and generates a wheel.

Notes for building on macOS
'''''''''''''''''''''''''

The legacy Python binary builds (OSX 10.6) need to be downloaded from:
https://www.python.org/downloads/

They will allow to build a wheel compatible with former OSX versions.

If you're having build issues, you may either have to run the build a second time (which will be much faster than the first run) or run the following command before running the first build:

``export LDSHARED="clang++ -bundle -undefined dynamic_lookup -arch i386 -arch x86_64"``

Notes for building on Travis
'''''''''''''''''''''''''

The V8 build is cached in order to make the Travis builds faster.

Whenever V8 is updated, the caches need to be flushed `on Travis here`_.

.. _`on Travis here`: https://travis-ci.org/sqreen/PyMiniRacer/caches

Tests
-----

If you want to run the tests, you need to build V8 first, then launch:

.. code:: bash

$ python setup.py test --addopts tests

Credits
-------

Built with love by Sqreen_.

.. _Sqreen: https://www.sqreen.io

PyMiniRacer launch was described in `this blog post`_.

.. _`this blog post`: https://blog.sqreen.io/embedding-javascript-into-python/

PyMiniRacer is inspired by mini_racer_, built for the Ruby world by Sam Saffron.

.. _`mini_racer`: https://github.com/SamSaffron/mini_racer

Tools used in rendering this package:

* Cookiecutter_
* `cookiecutter-pypackage`_

.. _Cookiecutter: https://github.com/audreyr/cookiecutter
.. _`cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage

Todo
----

Export V8 version.
Fix circular structures export.




History
-------

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.


Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
py_mini_racer-0.1.18-cp27-cp27-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp27
py_mini_racer-0.1.18-cp27-cp27m-macosx_10_6_intel.whl (4.8 MB) Copy SHA256 hash SHA256 Wheel cp27
py_mini_racer-0.1.18-cp27-cp27m-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp27
py_mini_racer-0.1.18-cp27-cp27mu-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp27
py_mini_racer-0.1.18-cp27-cp27u-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp27
py_mini_racer-0.1.18-cp34-cp34-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp34
py_mini_racer-0.1.18-cp34-cp34m-macosx_10_6_intel.whl (4.8 MB) Copy SHA256 hash SHA256 Wheel cp34
py_mini_racer-0.1.18-cp34-cp34m-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp34
py_mini_racer-0.1.18-cp35-cp35-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp35
py_mini_racer-0.1.18-cp35-cp35m-macosx_10_6_intel.whl (4.8 MB) Copy SHA256 hash SHA256 Wheel cp35
py_mini_racer-0.1.18-cp35-cp35m-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp35
py_mini_racer-0.1.18-cp36-cp36-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp36
py_mini_racer-0.1.18-cp36-cp36m-macosx_10_6_intel.whl (4.8 MB) Copy SHA256 hash SHA256 Wheel cp36
py_mini_racer-0.1.18-cp36-cp36m-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp36
py_mini_racer-0.1.18-cp37-cp37-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp37
py_mini_racer-0.1.18-cp37-cp37m-macosx_10_6_intel.whl (4.8 MB) Copy SHA256 hash SHA256 Wheel cp37
py_mini_racer-0.1.18-cp37-cp37m-manylinux1_x86_64.whl (6.1 MB) Copy SHA256 hash SHA256 Wheel cp37
py_mini_racer-0.1.18.tar.gz (330.3 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page