PyScript Compiler

PyScript is a Python-like programming language that compiles to JavaScript and can run in browsers or Node.js environments.

About PyScript

PyScript aims to provide developers with a familiar Python-style syntax while enjoying the power of the JavaScript ecosystem. It is not a complete implementation of Python, but a syntax-level transpilation tool.

Core Design Philosophy

1. Python-style syntax - Uses indentation, def, class, if and other Python syntax elements
2. JS-specific features retained - Such as trailing commas in object literals, async/await, etc.
3. Keyword escaping - JS keywords used as variable names are automatically escaped (e.g., function → def)

Why Choose PyScript

• Familiar Syntax: Python-style syntax reduces learning curve
• Powerful Ecosystem: Direct access to all JavaScript libraries and frameworks
• Seamless Integration: Compiled code runs directly in browsers or Node.js
• Flexibility: Combines Python's concise syntax with JavaScript's power

Features

Supported Syntax Features

Feature	PyScript Syntax	Generated JavaScript
Variable Declaration	a = 1	let a = 1
Multi-variable Assignment	a, b = 1, 2	let [a, b] = [1, 2]
Async Function	async def fn():	async function fn() {}
Await Expression	await fetch()	await fetch()
Class Definition	class Foo:	class Foo {}
Class Inheritance	class Bar(Foo):	class Bar extends Foo {}
Lambda Expression	lambda x: x*x	(x) => (x * x)
Conditional Expression	x if a else b	(a) ? x : b
Print Output	print(x)	console.log(x)

Installation

pnpm install

Usage

Compile a Single File

npx ts-node src/index.ts <input.py> <output.js>

Example

Input file examples/test.py:

async def fetch_data(url):
    return {"url": url, "status": "ok"}

async def main():
    data = await fetch_data("http://example.com")
    print(data["status"])

a, b, c = 1, 2, 3

Generated JavaScript:

async function fetch_data(url) {
    return {"url": url, "status": "ok"};
}

async function main() {
    let data = await fetch_data("http://example.com");
    console.log(data["status"]);
}

let [a, b, c] = [1, 2, 3];

Project Structure

.
├── src/                 # Source code directory
│   ├── token.ts        # Token type definitions
│   ├── lexer.ts        # Lexer (tokenizer)
│   ├── parser.ts       # Parser (AST builder)
│   ├── generator.ts    # Code generator
│   ├── ast.ts          # AST type definitions
│   └── index.ts        # Main entry file
├── examples/           # Example files
│   ├── test.py         # Comprehensive test case
│   ├── class-test.py   # Class definition test
│   └── ...
├── package.json        # Project configuration
├── tsconfig.json       # TypeScript configuration
├── SPEC.md             # Language specification
└── MAPPING.md          # Syntax mapping documentation

Supported Literal Types

PyScript	JavaScript
42	42
3.14	3.14
"hello"	"hello"
True	true
False	false
None	null
[1, 2, 3]	[1, 2, 3]
{key: "value"}	{key: "value"}

Keyword Escaping Rules

When JavaScript keywords are used as variable names, the compiler automatically escapes them:

PyScript Variable	JavaScript Variable
function	def
var	var_
let	let_
const	const_

Compilation Error Handling

The compiler has error recovery mechanisms:

• Skips error statements and continues parsing subsequent code
• Outputs successfully compiled parts even when compilation fails
• Error messages are displayed in the console

Development

# Install dependencies
pnpm install

# Development mode
pnpm run dev

# Compile TypeScript
pnpm run build

# Run tests
pnpm test

License

MIT License