pscript Python to JavaScript Compiler

0.8.1 · active · verified Fri Apr 17

pscript is a Python-to-JavaScript compiler that allows developers to write Python code that runs directly in a JavaScript environment, such as a web browser or Node.js. It supports converting Python functions and basic data structures into their JavaScript equivalents, enabling seamless integration of Python logic into web applications. The current version is 0.8.1, with releases occurring periodically, often tied to Python version support updates.

Common errors

```
NameError: name 'document' is not defined
```
cause Attempting to use browser-specific JavaScript objects (like `document` or `window`) directly in the Python source code that is intended for transpilation, but trying to execute/evaluate that Python code without a JavaScript runtime.

fix The generated JavaScript code, not the Python source, is what interacts with browser APIs. Ensure the generated JavaScript is run in a browser or Node.js environment where `document` or `window` objects exist. The Python function definition itself should ideally remain abstract from the execution environment.
```
TypeError: Cannot convert Python object of type <class 'MyCustomClass'> to JavaScript
```
cause pscript tries to transpile a Python object type that it doesn't recognize or know how to convert into a JavaScript equivalent (e.g., custom classes, complex library objects).

fix Only pass or operate on basic Python types (integers, floats, strings, booleans, lists, dictionaries, tuples) and simple functions. If custom objects are needed, convert them to supported primitive types (e.g., dictionaries) before passing them to `@pyscript`-decorated functions.

Warnings

gotcha Only a subset of Python's standard library and built-in functions are supported for transpilation. Functions from modules like `os`, `sys`, or complex data structures are generally not translated.
Fix: Focus on using basic Python types (strings, numbers, lists, dicts) and core operations. Avoid relying on Python-specific library functions that don't have direct JavaScript equivalents.
gotcha pscript generates JavaScript; it does not provide a JavaScript runtime in Python. Code relying on browser APIs (e.g., `document`, `window`) will only work when the generated JS is executed within a browser environment.
Fix: Test the generated JavaScript in its target environment (e.g., a web browser's console or Node.js). Do not expect browser-specific APIs to be available when inspecting the generated Python object.
gotcha Python's scoping rules, especially with closures and `nonlocal` variables, can behave subtly differently when transpiled to JavaScript. This can lead to unexpected variable capture.
Fix: Simplify function structures and explicitly pass variables where possible. Test edge cases involving closures and mutable state carefully in the JavaScript output.

Install

pip install pscript Install pscript

Imports

pyscript
```
from pscript import pyscript
```
The primary decorator for transpiling Python functions to JavaScript.
Script
```
from pscript import Script
```
Used for compiling arbitrary JavaScript code snippets and managing shared variables.

Quickstart

This quickstart demonstrates how to define a Python function decorated with `@pyscript` to automatically generate its JavaScript equivalent. The generated JavaScript source code can then be embedded and executed in a JavaScript runtime environment.

from pscript import pyscript

@pyscript
def hello_js(name):
    # This Python code will be transpiled to JavaScript
    print(f'Hello, {name} from JavaScript!')
    return f'Greetings, {name}'

# The generated JavaScript source code
js_code = hello_js.source
print(js_code)

# Example of using the generated function in a browser context (conceptual)
# You would typically inject js_code into an HTML <script> tag
# For example, in browser console:
# hello_js('World'); // Should print 'Hello, World from JavaScript!' to console

view raw JSON →