tree-sitter-languages

Warnings

• breaking Versions of `tree-sitter` equal to or greater than `0.22` (especially `0.25.1` and higher) introduce breaking changes that are incompatible with `tree-sitter-languages`. Attempting to use newer `tree-sitter` versions will result in runtime errors.
  Fix: Pin `tree-sitter` to an earlier, compatible version, such as `0.21.3`, when installing: `pip install tree-sitter-languages tree-sitter==0.21.3`.
• deprecated The `tree-sitter-languages` library is largely unmaintained. The original maintainers recommend migrating to `tree-sitter-language-pack` for continued support, new features, and broader compatibility with modern `tree-sitter` versions.
  Fix: Evaluate migrating your projects to `tree-sitter-language-pack` or another actively maintained Tree-sitter binding. Consult their documentation for equivalent usage patterns.
• gotcha Source installs of `tree-sitter-languages` are not supported. The library is distributed exclusively as pre-compiled binary wheels. Attempts to install from source will fail.
  Fix: Ensure your Python environment can correctly utilize pre-compiled binary wheels (e.g., compatible OS/architecture). Do not attempt to install directly from source.
• gotcha The API provided by `tree-sitter-languages` is extremely minimal, offering only `get_language` and `get_parser`. For any advanced operations, such as traversing the syntax tree, querying nodes, or modifying parsers, you must directly interact with the underlying `py-tree-sitter` library's API.
  Fix: After obtaining a `language` or `parser` object, refer to the `py-tree-sitter` documentation for its API to perform detailed parsing, analysis, and manipulation tasks.

Install

• pip install tree-sitter-languages PyPI

Imports

• get_language

  from tree_sitter_languages import get_language

• get_parser

  from tree_sitter_languages import get_parser

Quickstart

Demonstrates how to load a language and obtain a parser, then use it to parse a simple Python code snippet. It highlights the crucial dependency on `tree-sitter` and the potential need for version pinning.

from tree_sitter_languages import get_language, get_parser
import tree_sitter # The underlying tree-sitter library

# IMPORTANT: This library has known compatibility issues with newer versions of `tree-sitter`.
# For versions of `tree-sitter-languages` up to 1.10.2, you might need to pin `tree-sitter`
# to an earlier version for functionality, e.g., `pip install tree-sitter==0.21.3`.

try:
    # Get a language object for Python
    python_language = get_language('python')
    print(f"Loaded language: {python_language}")

    # Get a parser instance for Python
    python_parser = get_parser('python')
    print(f"Created parser: {python_parser}")

    # Example usage: parse some Python code
    code_bytes = b"""
    def hello_world():
        print('Hello, Tree-sitter!')
    """
    tree = python_parser.parse(code_bytes)
    
    print("\nParsed code:")
    print(code_bytes.decode())
    print("\nRoot node of the syntax tree (S-expression form):")
    print(tree.root_node.sexp())

except ImportError as e:
    print(f"Error: {e}. Ensure 'tree-sitter-languages' and 'tree-sitter' are installed.")
except Exception as e:
    print(f"An error occurred during parsing: {e}. Check tree-sitter version compatibility.")