npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@willbooster/tree-sitter-python

v21.0.3

Published

Python grammar for tree-sitter

Readme

@willbooster/tree-sitter-python

npm version license Test Test rust semantic-release wbfy crates.io

Python grammar for tree-sitter, forked from 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 and scanner fixes, including Python 3.15 unpacking comprehensions. It ships a compact parser generated by the parser generator of WillBooster/tree-sitter. Its ABI (0x5742000d) rejects upstream Tree-sitter runtimes and WillBooster runtimes prior to 22.0.0. Use this parser with willbooster-tree-sitter or @willbooster/web-tree-sitter 23.0.0 or later within 23.x, the runtime line it is tested and fuzzed with.

Support Scope

This fork maintains only full parsing: valid input yields a correct tree, and invalid input yields ERROR or MISSING nodes without crashing, hanging, or taking more than linear time. Incremental parsing and queries (highlights, locals, injections, tags) are not supported. Node types, field names, and the trees that error recovery produces may change; such changes are released as new major versions.

Usage

The npm package ships tree-sitter-python.wasm for @willbooster/web-tree-sitter, which runs in Node.js, Bun, browsers, and Cloudflare Workers. Package peer dependencies require @willbooster/web-tree-sitter ^23.0.0.

In Node.js and Bun, load the grammar from its path:

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:

import pythonUrl from '@willbooster/tree-sitter-python/tree-sitter-python.wasm?url';
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtimeUrl from '@willbooster/web-tree-sitter/web-tree-sitter.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:

import python from '@willbooster/tree-sitter-python/tree-sitter-python.wasm';
import { Language, Parser } from '@willbooster/web-tree-sitter';
import runtime from '@willbooster/web-tree-sitter/web-tree-sitter.wasm';

await Parser.init({ wasmModule: runtime });
const parser = new Parser();
parser.setLanguage(await Language.load(python));

The package also ships the node types in src/node-types.json.

Qualified generic bases use member_type inside generic_type. Generic bases in annotations also recognize the contextual identifier spellings match, print, exec and lazy, while ordinary value subscripts retain their expression trees. Plain qualified generic arguments also expose member_type inside their type operand. Structured unpacked annotations and unpacked generic arguments use a type child inside splat_type. Expression-valued starred parameter annotations, such as *args: *factory(), keep a direct expression child instead. Ordinary value unpacks keep their expression tree.

In Rust, depend on the crate and on willbooster-tree-sitter 23.0.0 or later within 23.x:

cargo add [email protected] --rename tree-sitter
cargo add willbooster-tree-sitter-python --rename tree-sitter-python
let mut parser = tree_sitter::Parser::new();
parser.set_language(&tree_sitter_python::LANGUAGE.into())?;

Development

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);
  • 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, 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