# @willbooster/tree-sitter-python
[](https://www.npmjs.com/package/@willbooster/tree-sitter-python)
[](https://www.npmjs.com/package/@willbooster/tree-sitter-python)
[](https://github.com/WillBooster/tree-sitter-python/actions/workflows/test.yml)
[](https://github.com/WillBooster/tree-sitter-python/actions/workflows/test-rust.yml)
[](https://github.com/semantic-release/semantic-release)
[](https://github.com/WillBooster/shared/tree/main/packages/wbfy)
[](https://crates.io/crates/willbooster-tree-sitter-python)
Python grammar for [tree-sitter](https://github.com/tree-sitter/tree-sitter), forked from
[tree-sitter/tree-sitter-python](https://github.com/tree-sitter/tree-sitter-python). We are grateful
to its authors and contributors. This is not an official release of that project.
This fork builds on upstream v0.25.0 with grammar, scanner, and highlighting fixes, including Python 3.15
unpacking comprehensions. It ships a compact parser generated by the parser generator of
[WillBooster/tree-sitter](https://github.com/WillBooster/tree-sitter). The parser carries that fork's own ABI number, so
it loads only with the WillBooster runtime (`willbooster-tree-sitter` or `@willbooster/web-tree-sitter`) 2.0.0 or later,
not with upstream's tree-sitter.
## Usage
The npm package ships `tree-sitter-python.wasm` for
[@willbooster/web-tree-sitter](https://www.npmjs.com/package/@willbooster/web-tree-sitter), which runs in Node.js, Bun,
browsers, and Cloudflare Workers. The parser requires runtime 2.0.0 or later.
In Node.js and Bun, load the grammar from its path:
```js
import { fileURLToPath } from 'node:url';
import { Language, Parser } from '@willbooster/web-tree-sitter';
await Parser.init();
const parser = new Parser();
const wasmPath = fileURLToPath(import.meta.resolve('@willbooster/tree-sitter-python/tree-sitter-python.wasm'));
parser.setLanguage(await Language.load(wasmPath));
const tree = parser.parse('def main():\n pass\n');
```
In browsers, load the grammar from its URL. With Vite:
```js
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtimeUrl from '@willbooster/web-tree-sitter/web-tree-sitter.wasm?url';
import pythonUrl from '@willbooster/tree-sitter-python/tree-sitter-python.wasm?url';
await Parser.init({ locateFile: () => runtimeUrl });
const parser = new Parser();
parser.setLanguage(await Language.load(pythonUrl));
```
In Cloudflare Workers, which do not allow compiling Wasm at run time, import both `.wasm` files as modules:
```js
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtime from '@willbooster/web-tree-sitter/web-tree-sitter.wasm';
import python from '@willbooster/tree-sitter-python/tree-sitter-python.wasm';
await Parser.init({ wasmModule: runtime });
const parser = new Parser();
parser.setLanguage(await Language.load(python));
```
The package also ships the queries in `queries/` and the node types in `src/node-types.json`.
In Rust, depend on the [crate](https://crates.io/crates/willbooster-tree-sitter-python) and on
[willbooster-tree-sitter](https://crates.io/crates/willbooster-tree-sitter), the runtime this package is tested and
fuzzed with. The parser requires runtime 2.0.0 or later:
```toml
[dependencies]
tree-sitter = { package = "willbooster-tree-sitter", version = "2" }
tree-sitter-python = { package = "willbooster-tree-sitter-python", version = "2" }
```
```rust
let mut parser = tree_sitter::Parser::new();
parser.set_language(&tree_sitter_python::LANGUAGE.into())?;
```
## Development
```sh
mise install
bun install --frozen-lockfile
bun run build/ci
bun run test
script/parse-examples
cargo test
```
The scripts and tests generate, build, test, and parse with `script/tree-sitter`, the tree-sitter CLI of the
WillBooster/tree-sitter runtime version locked in `Cargo.lock`, since the generator and the runtime of upstream's CLI are
not the ones this package ships with. Its first run downloads that CLI from the runtime's GitHub Release, or builds it
with `cargo` (whose build runs the CMake that `mise.toml` pins) when the download fails or the release has no binary that runs here. Run other CLI
commands through it as well (e.g. `script/tree-sitter parse file.py`).
`bun run generate` records a fresh generation profile from the applicable `test/corpus` cases and Git-tracked
Python files in `examples/`, then generates compact parser tables. The parser also embeds metadata from `tree-sitter.json`. After changing a grammar,
`tree-sitter.json`, a corpus case, or a tracked example,
regenerate and commit `src/`. Stage added or removed examples with `git add -A examples` before generation so the profile uses the intended file list.
Profiles in `.tmp/generation-profiles/` are temporary and must not be committed. `bun run build-wasm`, `bun run build/ci`,
and the release build regenerate the parsers before compiling them.
`bun run test` runs:
- the corpus in `test/corpus`, with the native build and with the Wasm build (the first run downloads the WASI SDK);
- an incremental-parsing check (`test/unit/incremental.test.ts`): `script/fuzz-corpus` runs `tree-sitter fuzz`, which
edits each corpus case at random, reparses it, undoes the edits, and reparses again. `TREE_SITTER_SEED`,
`TREE_SITTER_ITERATIONS`, and `TREE_SITTER_EDITS` run other or more edits;
- a check that the real-world Python files in `examples/`, the checked-in ones and those of the cloned repositories,
fail to parse exactly as listed in `script/known-failures.txt`. The first run clones the repositories. The example
repositories are pinned to commits in `script/parse-examples`. After a grammar change or a moved pin alters that list,
`script/parse-examples` rewrites it; review its diff before committing;
- a performance check (`test/unit/performance.test.ts`) that recovering from an error on each line takes linear time
(ten times the lines take about ten times the CPU time, under a ceiling), since consumers parse files while they are
being edited. It loads the Wasm build through @willbooster/web-tree-sitter, which `bun run build/ci` rebuilds after
regenerating the parser;
- a native CLI crash regression for deeply indented strings (`test/unit/deepIndentation.test.ts`);
- a check that `package.json` and `Cargo.lock` test the same runtime version (`test/unit/runtimeVersion.test.ts`);
- checks that the Wasm build parses in Chromium (`test/unit/browser/`) and in Cloudflare Workers with and without
Node.js compatibility (`test/unit/workerd.test.ts`). Run `bun run test/ci-setup` once to install Chromium.
Tests and `script/parse-examples` keep native parser builds under this checkout's `.tmp/` instead of the CLI cache shared by every checkout.
See `test/unit/run.ts`, `test/unit/deepIndentation.test.ts`, `script/fuzz-corpus`, and `script/parse-examples`
for their build locations and cleanup.
CI also runs these tests on Linux arm64 and macOS, where the CLI compiles the parser and the scanner with the platform's
C compiler as the crate does for its users, and fuzzes the parser with libFuzzer and sanitizers
(`.github/workflows/robustness.yml`).
### References
- [Python 2 Grammar](https://docs.python.org/2/reference/grammar.html)
- [Python 3 Grammar](https://docs.python.org/3/reference/grammar.html)