Tree-sitter provides Python bindings to the core Tree-sitter parsing library, enabling fast, incremental parsing and the generation of concrete syntax trees for various programming languages. It's actively maintained, with frequent updates (minor and patch releases typically every few weeks or months) to keep pace with the underlying C library. The current version is `0.25.2`.
pip install tree-sitterVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to load a language grammar (Python in this case), create a parser, parse a code string into a syntax tree, and then use Tree-sitter's query system to find specific patterns within the tree, such as function names. It highlights the typical workflow of initializing a `Language` object from a pre-compiled grammar and then using a `Parser` to process source code. Ensure the relevant language package (e.g., `tree-sitter-python`) is installed alongside `tree-sitter`.
For custom language loading, ensure you're passing a proper `PyCapsule` or using a language binding that provides it. Remove `keep_text` from `parser.parse()` calls. For queries, pre-set the desired range using `query.set_byte_range()` or `query.set_point_range()` before calling `captures()` or `matches()`.
Upgrade your Python environment to 3.10 or later. Migrate away from `Language(ptr: int)` by using official language binding packages (e.g., `tree-sitter-python`) which provide a `language()` function. Update code using `Node.child_containing_descendant` to equivalent newer methods or tree traversal logic.
Ensure that the `tree-sitter` package and any `tree-sitter-<language>` packages you use are compatible by checking their release notes or by installing versions known to work together. If encountering issues, try aligning their versions, typically by upgrading/downgrading one or both packages.
Monitor memory usage closely in production. For large inputs, consider processing files in chunks or optimizing your queries to reduce the scope. Report any persistent, unexplainable memory growth as a bug to the project maintainers, providing a minimal reproducible example.
For unsupported languages, follow the official Tree-sitter documentation for compiling custom grammars. Then, use `from tree_sitter import Language; MY_LANGUAGE = Language(f'path/to/my_language.so', 'my_language_name')` to load it, ensuring the ABI version matches. Avoid `tree-sitter-languages` in new projects.
Verify the integrity of your `tree-sitter` installation by reinstalling it (`pip install --force-reinstall tree-sitter`). Ensure there are no conflicting packages or unusual environment configurations that might interfere with the package's functionality. If the issue persists, consider trying a different minor version of `tree-sitter` or consulting the project's issue tracker for known environment-specific problems.
Initialize the `Parser` with the `language` argument (e.g., `parser = Parser(language=MY_LANGUAGE)`) or assign the language directly to the `language` property (e.g., `parser.language = MY_LANGUAGE`).
pip install tree-sitter
Install the "Build Tools for Visual Studio 2022" (or 2019) from Microsoft's website, ensuring to select the 'Desktop development with C++' workload during installation.
Ensure `tree_sitter.Language.build_library()` successfully compiles the grammar, verify the `output_path` matches where you later try to load it, and confirm the `source_paths` are correct.
parser.language = language