Fast Python bindings for the oxc JavaScript/TypeScript parser.
oxc-python provides Python bindings for oxc's blazing-fast JavaScript and TypeScript parser. oxc is written in Rust and is one of the fastest JS/TS parsers available, outperforming alternatives by 3-5x while maintaining full compatibility with JavaScript and TypeScript standards.
Use cases:
- Building development tools that analyze JavaScript/TypeScript code
- Creating AST-based linters or code analyzers
- Extracting information from JS/TS codebases (imports, exports, functions, etc.)
- Building code transformation or refactoring tools
- Any Python application that needs to understand JavaScript/TypeScript syntax
pip install oxc-pythonNote: Package not yet published to PyPI. For now, install from source (see Development section).
import oxc_python
# Parse JavaScript code
result = oxc_python.parse("const x = 42;")
print(result.program.body[0].type) # VariableDeclaration
# Access the source text of any node
for node, depth in oxc_python.walk(result.program):
if node.type == "VariableDeclaration":
print(node.get_text("const x = 42;")) # const x = 42;- ✅ JavaScript (ES2024+) - Full support for modern JavaScript
- ✅ TypeScript - Types, interfaces, enums, decorators
- ✅ JSX/TSX - React syntax support
- ✅ Error Recovery - Get partial AST even with syntax errors
- ✅ Fast - Rust-powered performance
- ✅ Type Stubs - Full type hints for IDE support
import oxc_python
# Basic parsing
result = oxc_python.parse("const x = 1;")
# Returns: ParseResult with 'program' and 'errors' fields
# Parse TypeScript
result = oxc_python.parse(
"const x: number = 1;",
source_type="module", # or "script"
)
# Parse JSX/TSX
result = oxc_python.parse(
"const Component = () => <div>Hello</div>;",
)
# Handle parse errors gracefully
result = oxc_python.parse("const x = ;") # Syntax error
if result.errors:
for error in result.errors:
print(f"Error: {error}")
# Still get partial AST in result.program
# Traverse the AST
for node, depth in oxc_python.walk(result.program):
indent = " " * depth
print(f"{indent}{node.type}")
# Extract source text for any node
source = "const x = 1;\nconst y = 2;"
result = oxc_python.parse(source)
for node, _ in oxc_python.walk(result.program):
if node.type == "VariableDeclaration":
text = node.get_text(source)
line_start, line_end = node.get_line_range(source)
print(f"Lines {line_start}-{line_end}: {text}")import oxc_python
source = """
import React from 'react';
import { useState } from 'react';
import * as Utils from './utils';
"""
result = oxc_python.parse(source)
for node, _ in oxc_python.walk(result.program):
if node.type == "ImportDeclaration":
module = node.source.value
print(f"Imports from: {module}")import oxc_python
source = """
function foo() {}
async function bar() {}
function* baz() {}
"""
result = oxc_python.parse(source)
for node, _ in oxc_python.walk(result.program):
if node.type == "FunctionDeclaration":
name = node.id.name if node.id else "<anonymous>"
async_flag = "async " if node.async_ else ""
generator_flag = "* " if node.generator else ""
print(f"{async_flag}{generator_flag}function {name}")import oxc_python
source = """
type User = { name: string; age: number };
interface Config { debug: boolean; }
enum Status { Active, Inactive }
"""
result = oxc_python.parse(source)
for node, _ in oxc_python.walk(result.program):
if node.type == "TSTypeAliasDeclaration":
print(f"Type alias: {node.id.name}")
elif node.type == "TSInterfaceDeclaration":
print(f"Interface: {node.id.name}")
elif node.type == "TSEnumDeclaration":
print(f"Enum: {node.id.name}")This project uses a devcontainer for consistent development environments.
-
Prerequisites:
-
Open in devcontainer:
git clone https://github.com/tylersatre/oxc-python.git cd oxc-python code .
- When prompted, click "Reopen in Container"
- Or: Press
F1→ "Dev Containers: Reopen in Container"
-
The devcontainer will automatically:
- Install all dependencies with
uv sync - Set up Python virtual environment
- Configure VS Code with Python, Rust, and Ruff extensions
- Install all dependencies with
-
Build and test:
# Build the Rust extension maturin develop # Run tests pytest # Run specific test pytest tests/test_phase_08_parse_function.py -v
Requirements:
Steps:
git clone https://github.com/tylersatre/oxc-python.git
cd oxc-python
# Install dependencies
uv sync # or: pip install -e ".[dev]"
# Build the extension
maturin develop
# Run tests
pytest# Build for development
maturin develop
# Build for release (optimized)
maturin develop --release
# Build wheel
maturin build --release
# Format code
ruff format .
# Lint code
ruff check .
# Run tests
pytest
# Run tests with coverage
pytest --cov=oxc_python --cov-report=htmlCurrent: v0.1.0 (Pre-release)
This is an early-stage project focused on providing parser bindings only. The API is stable enough for experimentation but may change before v1.0.
- ✅ Full JavaScript/TypeScript/JSX parsing
- ✅ AST traversal with
walk() - ✅ Source text extraction with
get_text()andget_line_range() - ✅ Error recovery
- ✅ Type stubs for IDE support
- ❌ Linting (oxc linter bindings)
- ❌ Code transformation/mutation
- ❌ Formatting (oxc formatter bindings)
- ❌ Scope analysis
- ❌ AST modification APIs
These features may be added in future versions based on community interest.
Contributions are welcome! This project is in active development for v0.1.0.
How to contribute:
- Fork the repository
- Create a feature branch
- Make your changes in the devcontainer
- Add tests for new features
- Run
pytestandruff check . - Submit a pull request
Areas where we'd love help:
- Documentation improvements
- Example scripts
- Bug reports and fixes
- Performance benchmarks
- Feature suggestions
See CLAUDE.md for architectural guidance.
oxc-python/
├── src/ # Rust source code (PyO3 bindings)
│ ├── lib.rs # Main module
│ ├── parser.rs # Parser bindings
│ ├── traversal.rs # walk() implementation
│ └── nodes/ # AST node conversions
├── python/oxc_python/ # Python package
│ ├── __init__.py # Python API
│ ├── *.pyi # Type stubs
│ └── py.typed # PEP 561 marker
├── tests/ # Python test suite
└── .devcontainer/ # Dev environment config
oxc is designed for speed. While we haven't published formal benchmarks yet, oxc's Rust parser is typically 3-5x faster than popular JavaScript parsers like Babel or TypeScript's compiler.
The Python bindings add minimal overhead - most time is spent in Rust code.
MIT License - see LICENSE file for details.
This project provides Python bindings for oxc, which is also MIT licensed.
Built on top of the excellent oxc project by Boshen and contributors. Thank you for creating such a high-quality, fast JavaScript toolchain in Rust!
- Repository: https://github.com/tylersatre/oxc-python
- Issues: https://github.com/tylersatre/oxc-python/issues
- oxc Project: https://github.com/oxc-project/oxc
- PyO3: https://pyo3.rs (Rust ↔ Python bindings)
- Maturin: https://maturin.rs (Build tool)