PythonMonkey Documentation

The pmjs shell is a basic JavaScript shell that ships with PythonMonkey. It functions similarly to the node shell, acting as a REPL or a way to run JavaScript programs.

# Conceptually similar to node
pmjs

PythonMonkey provides seamless, high-performance data interchange between Python and JavaScript without serialization or pipes. Both engines run in the same process.

Key Mapping Rules

• Strings: Share immutable backing stores whenever possible to avoid memory-copy overhead for large strings.
• Arrays and Objects:
  • JavaScript Array methods work on Python list objects via a JS API Proxy.
  • JavaScript Object methods work on Python dict objects.
  • Python list and dict are coerced to JS Array and Object respectively.
• TypedArrays: Share mutable backing stores.
• Dates: JavaScript Date objects are represented by Python datetime.datetime objects.
• Functions: JS functions are automatically wrapped to behave like Python functions, and vice-versa.
• Intrinsics: Booleans, numbers, null, and undefined are passed by value.

PythonMonkey's pmjs starts a CommonJS subsystem with Node.js-like semantics (searching module.paths, understanding package.json, etc.).

You can create CommonJS modules in either JavaScript or Python:

JavaScript Modules

Create a .js file and use the exports object to expose functionality.

Python Modules

Create a .py file and decorate a dictionary named exports with your module's members. This allows the module to be loaded via require() in either JavaScript or Python.

// date-lib.js - require("./date-lib")
const d = new Date();
exports.today = `${d.getFullYear()}-${String(d.getMonth()).padStart(2,'0')}-${String(d.getDay()).padStart(2,'0')}`

# date-lib.py - require("./date-lib")
from datetime import date
exports['today'] = date.today()

A Program Module (or main module) is a special module in the CommonJS subsystem with the following behaviors:

• Variables defined in the outermost scope become properties of globalThis.
• Returning from the outermost scope results in a syntax error.
• The arguments variable is an Array containing the program's argument vector (command-line arguments).

$ echo "console.log('hello world')" > my-program.js
$ pmjs my-program.js
hello world
$ 

When writing functions, follow these patterns for parameters and return types:

• Return Values: Prefer returning by value or by reference. Avoid pointers unless the return can be nullptr.
• Input Parameters: Use values or const references for non-optional inputs. Use std::optional for optional by-value inputs.
• Output/IO Parameters: Use non-const references for non-optional output/IO parameters. Use non-const pointers for optional output/IO parameters.
• Parameter Ordering: Place all input-only parameters before any output parameters.
• Attributes: Place function attributes like [[nodiscard]] on their own line.

PythonMonkey allows you to run JavaScript code within a Python environment. The core mechanism is the eval function, which accepts JavaScript code and returns values coerced into Python types.

Basic Usage

Import pythonmonkey and use eval to run a JS string. The result is automatically converted to the appropriate Python type.

import pythonmonkey as pm

# Evaluate a JS arrow function and call it
hello = pm.eval("() => {return 'Hello from Spidermonkey!'}")
print(hello())
# Output: 'Hello from Spidermonkey!'

Quick Example (tl;dr)

from pythonmonkey import eval as js_eval

# Evaluate console.log and call it with a string
js_eval("console.log")('hello, world')

The pmjs REPL allows for interactive Python and JavaScript execution.

Key features:

• .help: Displays a help menu.
• Python Integration: You can run Python code directly using the .python prefix.
• Variable History: The REPL stores evaluated Python expressions in special variables named $1, $2, etc., allowing you to access previous results.

$ pmjs

Welcome to PythonMonkey v1.0.0.
Type ".help" for more information.
> .python import sys
> .python sys.path
$1 = { '0': '/home/wes/git/pythonmonkey2', ... }
> $1[3]
'/usr/lib/python3.10/lib-dynload'

To ensure compliance with the project's requirement for modern C++ and to prevent the use of non-standard extensions, configure your CMakeLists.txt with the following settings. This enforces C++17 and disables compiler-specific extensions.

set(CMAKE_CXX_EXTENSIONS OFF)
set(CMAKE_CXX_STANDARD "17")
set(CMAKE_CXX_STANDARD_REQUIRED ON)

To maintain a consistent codebase, adhere to these formatting rules:

• Indentation: Use 2 spaces; no tabs allowed.
• Braces: Always enclose the body of if, for, do, while, and switch in braces {}.
• Line Length: Aim for a limit of 80 characters.
• Switch Statements: Do not indent case statements. Use [[fallthrough]]; to annotate intentional fall-throughs.
• Multi-line splitting: Match indentation to the nesting level of braces/brackets/parentheses. Place the opening brace on the same line as the statement.

if (
  condition && (
    anotherCondition || possiblyAnotherCondition
  )
) {
  do {
    ++index;
  } while (index < total);
} else {
  return false;
}

To use setTimeout or leverage Promise <=> awaitable coercion, you must have an event-loop running in Python. This is typically done using asyncio.

import asyncio
import pythonmonkey as pm

async def async_fn():
    # Using setTimeout in JS
    await pm.eval("""
        new Promise((resolve) => setTimeout((...args) => {
            console.log(args);
            resolve();
          }, 1000, 42, "abc")
        ）
    """)
    # Using Python awaitable in JS
    await pm.eval("async (x) => await x")(asyncio.sleep(0.5))

asyncio.run(async_fn())