PythonMonkey v1.0.1 (dev)
|
PythonMonkey is a Mozilla SpiderMonkey JavaScript engine embedded into the Python Runtime, using the Python engine to provide the Javascript host environment.
We feature JavaScript Array and Object methods implemented on Python List and Dictionaries using the cPython C API, and the inverse using the Mozilla Firefox Spidermonkey JavaScript C++ API.
This project has reached MVP as of September 2024. It is under maintenance by Distributive.
External contributions and feedback are welcome and encouraged.
eval()
function in Python which accepts JS code and returns JS->Python coerced valuesrequire
function, returns a coerced dict of module exportsRead this if you want to build a local version.
./setup.sh
):poetry install
. This command automatically compiles the project and installs the project as well as dependencies into the poetry virtualenv. If you would like to build the docs, set the BUILD_DOCS
environment variable, like so: BUILD_DOCS=1 poetry install
. PythonMonkey supports multiple build types, which you can build by setting the BUILD_TYPE
environment variable, like so: BUILD_TYPE=Debug poetry install
. The build types are (case-insensitive):Release
: stripped symbols, maximum optimizations (default)DRelease
: same as Release
, except symbols are not strippedDebug
: minimal optimizationsSanitize
: same as Debug
, except with AddressSanitizer enabledProfile
: same as Debug
, except profiling is enabledNone
: don't compile (useful if you only want to build the docs)If you are using VSCode, you can just press Ctrl
+ Shift
+ B
to run build task - We have the tasks.json
file configured for you.
poetry install --no-root --only=dev
poetry run pytest ./tests/python
poetry run bash ./peter-jr ./tests/js/
For VSCode users, similar to the Build Task, we have a Test Task ready to use.
npm (Node.js) is required during installation only to populate the JS dependencies.
pythonmonkey
is available in the poetry virtualenv once you compiled the project using poetry.
Alternatively, you can build installable packages by running
and install them by pip install ./dist/*
.
Installing pythonmonkey
will also install the pminit
package as a dependency. However, pip uninstall
ing a package won't automatically remove its dependencies.
If you want to cleanly remove pythonmonkey
from your system, do the following:
poetry run gdb python
. See Python Wiki: DebuggingWithGdbIf you are using VSCode, it's more convenient to debug in VSCode's built-in debugger. Simply press F5
on an open Python file in the editor to start debugging - We have the launch.json
file configured for you.
These methods are exported from the pythonmonkey module. See definitions in python/pythonmonkey/pythonmonkey.pyi.
Evaluate JavaScript code. The semantics of this eval are very similar to the eval used in JavaScript; the last expression evaluated in the code
string is used as the return value of this function. To evaluate code
in strict mode, the first expression should be the string "use strict"
.
The eval function supports an options object that can affect how JS code is evaluated in powerful ways. They are largely based on SpiderMonkey's CompileOptions
. The supported option keys are:
filename
: set the filename of this code for the purposes of generating stack traces etc.lineno
: set the line number offset of this code for the purposes of generating stack traces etc.column
: set the column number offset of this code for the purposes of generating stack traces etc.mutedErrors
: if set to True
, eval errors or unhandled rejections are ignored ("muted"). Default False
.noScriptRval
: if False
, return the last expression value of the script as the result value to the caller. Default False
.selfHosting
: experimentalstrict
: forcibly evaluate in strict mode ("use strict"
). Default False
.module
: indicate the file is an ECMAScript module (always strict mode code and disallow HTML comments). Default False
.fromPythonFrame
: generate the equivalent of filename, lineno, and column based on the location of the Python call to eval. This makes it possible to evaluate Python multiline string literals and generate stack traces in JS pointing to the error in the Python source file.undefined
in JavaScript; if you want to return a function, you must evaluate an expression: Return the exports of a CommonJS module identified by moduleIdentifier
, using standard CommonJS semantics
require
.js
- JavaScript module; source code decorates exports
object.py
- Python module; source code decorates exports
dict.json
- JSON module; exports are the result of parsing the JSON text in the fileA Python Dict which is equivalent to the globalThis object in JavaScript.
Factory function which returns a new require function
Load and evaluate a program (main) module. Program modules must be written in JavaScript. Program modules are not necessary unless the main entry point of your program is written in JavaScript.
Care should be taken to ensure that only one program module is run per JS context.
Examines the string code
and returns False if the string might become a valid JS statement with the addition of more lines. This is used internally by pmjs and can be very helpful for building JavaScript REPLs; the idea is to accumulate lines in a buffer until isCompilableUnit is true, then evaluate the entire buffer.
Returns a Python function which invokes function
with the JS new operator.
This is the JS typeof
operator, wrapped in a function so that it can be used easily from Python.
All of the JS Standard Classes (Array, Function, Object, Date...) and objects (globalThis, FinalizationRegistry...) are available as exports of the pythonmonkey module. These exports are generated by enumerating the global variable in the current SpiderMonkey context. The current list is:
undefined, Boolean, JSON, Date, Math, Number, String, RegExp, Error, InternalError, AggregateError, EvalError, RangeError, ReferenceError, SyntaxError, TypeError, URIError, ArrayBuffer, Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, Uint32Array, Float32Array, Float64Array, Uint8ClampedArray, BigInt64Array, BigUint64Array, BigInt, Proxy, WeakMap, Map, Set, DataView, Symbol, Intl, Reflect, WeakSet, Promise, WebAssembly, WeakRef, Iterator, AsyncIterator, NaN, Infinity, isNaN, isFinite, parseFloat, parseInt, escape, unescape, decodeURI, encodeURI, decodeURIComponent, encodeURIComponent, Function, Object, debuggerGlobal, FinalizationRegistry, Array, globalThis
See definitions in python/pythonmonkey/global.d.ts. Including:
console
atob
btoa
setTimeout
clearTimeout
The CommonJS subsystem is activated by invoking the require
or createRequire
exports of the (Python) pythonmonkey module.
require
exports
module
__filename
__dirname
python.print
- the Python print functionpython.getenv
- the Python getenv functionpython.stdout
- an object with read
and write
methods, which read and write to stdoutpython.stderr
- an object with read
and write
methods, which read and write to stderrpython.exec
- the Python exec functionpython.eval
- the Python eval functionpython.exit
- exit via sys.exit(); the exit code is the function argument or python.exit.code
.python.paths
- the Python sys.paths list, visible in JS as an ArrayWhen sending variables from Python into JavaScript, PythonMonkey will intelligently coerce or wrap your variables based on their type. PythonMonkey will share backing stores (use the same memory) for ctypes, typed arrays, and strings; moving these types across the language barrier is extremely fast because there is no copying involved.
Note: There are plans in Python 3.12 (PEP 623) to change the internal string representation so that every character in the string uses four bytes of memory. This will break fast string transfers for PythonMonkey, as it relies on the memory layout being the same in Python and JavaScript. As of this writing (July 2023), "classic" Python strings still work in the 3.12 beta releases.
Where shared backing store is not possible, PythonMonkey will automatically emit wrappers that use the "real" data structure as its value authority. Only immutable intrinsics are copied. This means that if you update an object in JavaScript, the corresponding Dict in Python will be updated, etc.
JavaScript Array and Object methods are implemented on Python List and Dictionaries, and vice-versa.
Python Type | JavaScript Type |
---|---|
String | string |
Integer | number |
Bool | boolean |
Function | function |
Dict | object |
List | Array |
datetime | Date object |
awaitable | Promise |
Error | Error object |
Buffer | ArrayBuffer |
JavaScript Type | Python Type |
---|---|
string | pythonmonkey.JSStringProxy (String) |
number | Float |
bigint | pythonmonkey.bigint (Integer) |
boolean | Bool |
| function | pythonmonkey.JSFunctionProxy || pythonmonkey.JSMethodProxy (Function || Method) | object - most | pythonmonkey.JSObjectProxy (Dict) | object - Date | datetime | object - Array | pythonmonkey.JSArrayProxy (List) | object - Promise | awaitable | object - ArrayBuffer | Buffer | object - type arrays | Buffer | object - Error | Error
You can force a number in JavaScript to be coerced as an integer by casting it to BigInt:
The pythonmonkey.bigint
object works like an int in Python, but it will be coerced as a BigInt in JavaScript:
You can use a JavaScript IIFE to create a scope in which you can inject Python symbols:
You need an event-loop running to use setTimeout
and Promise
<=>awaitable
coercion.
A basic JavaScript shell, pmjs
, ships with PythonMonkey. This shell can act as a REPL or run JavaScript programs; it is conceptually similar to the node
shell which ships with Node.js.
Pmjs starts PythonMonkey's CommonJS subsystem, which allow it to use CommonJS modules, with semantics that are similar to Node.js - e.g. searching module.paths, understanding package.json, index.js, and so on. See the ctx-module for a full list of supported features.
In addition to CommonJS modules written in JavaScript, PythonMonkey supports CommonJS modules written in Python. Simply decorate a Dict named exports
inside a file with a .py
extension, and it can be loaded by require()
– in either JavaScript or Python.
The program module, or main module, is a special module in CommonJS. In a program module:
globalThis
arguments
variable in an Array which holds your program's argument vector (command-line arguments)If you are having trouble with the CommonJS require function, set environment variable ‘DEBUG='ctx-module*’` and you can see the filenames it tries to load.
PythonMonkey has a built-in gdb-like JavaScript command-line debugger called pmdb, which would be automatically triggered on debugger;
statements and uncaught exceptions.
To enable pmdb, simply call from pythonmonkey.lib import pmdb; pmdb.enable()
before doing anything on PythonMonkey.
Run help
command in pmdb to see available commands.
.help
menu in the REPL--help
command-line option--inspect
option enables pmdb, a gdb-like JavaScript command-line debugger-r
option can be used to load a module before your program or the REPL runs-e
option can be used evaluate code – e.g. define global variables – before your program or the REPL runs$1
, $2
, etc.