# tree-sitter/py-tree-sitter architecture

> Architecture diagram of the GitHub repository tree-sitter/py-tree-sitter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tree-sitter/py-tree-sitter
- Repository: https://github.com/tree-sitter/py-tree-sitter

## Overview

##### Project Type and Purpose
- This is a **Python library** providing **bindings** to the Tree-sitter parsing engine (a C library).
- It is **not** a full-stack web app—it’s an extensible parser library that lets Python code invoke a high-performance C parser.

##### Main Components
a. **Python API Layer**
– Files under `tree_sitter/` (`__init__.py`, `.pyi`) define classes: `Language`, `Parser`, `Node`, `Tree`, `TreeCursor`, `Query`, etc.
– These are what **users import** and call in their Python scripts or applications.
b. **C Extension / Binding Layer**
– Under `tree_sitter/binding/*.c` and `types.h` sits the CPython extension code.
– Exposes the Tree-sitter C API to Python by wrapping functions in Python-callable methods.
c. **Tree-sitter Core**
– In `tree_sitter/core/` (and linked from submodules) lives the actual parser implementation and runtime.
– Compiled as a static or shared library that the binding layer links against.
d. **Language Plug-ins**
– External language libraries (e.g. `tree-sitter-python` wheel) provide `language()` functions.
– Loaded at runtime into the `Language` class.
e. **Support Infrastructure**
– **Examples** (`examples/usage.py`, `examples/walk_tree.py`) show how to use the API.
– **Tests** (`tests/`) validate functionality of each class.
– **Docs** (`docs/`) generated by Sphinx, illustrating API reference and guides.
– **Packaging/config** (`pyproject.toml`, `setup.py`, GitHub workflows) for CI, publishing, linting.

##### Relationships and Data Flow
- **User Code** → calls **Python API Layer** methods (e.g. `Parser.parse()`).
- **Python API Layer** → calls into **C Extension Layer** (via CPython C-API functions).
- **C Extension Layer** → invokes **Tree-sitter Core** functions to parse source text.
- **Tree-sitter Core** → returns opaque parse trees to the C Extension.
- **C Extension Layer** → wraps core structures into Python objects (`Tree`, `Node`, etc.) and returns them.
- **Python Code** then inspects or mutates these objects, or applies `Query` patterns.

##### Architectural Patterns and Principles
– **Layered Architecture**: clear separation between user-facing Python classes and low-level C bindings.
– **Plugin/Extension Model**: languages are separate wheels and loaded dynamically.
– **Test-Driven**: each core component has corresponding unit tests.
– **Documentation-First**: Sphinx docs mirror the package structure for discoverability.

##### Essential Elements
– **Component labels**: e.g., “TreeCursor (Python)”, “lookahead_iterator.c”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    UA["User Application / Example Script"]:::external

    %% Main Package Boundary
    subgraph "py-tree-sitter package"
        direction TB

        %% Python API Layer
        subgraph "Python API Layer"
            direction TB
            API_init["tree_sitter/__init__.py"]:::pythonapi
            API_stub["tree_sitter/__init__.pyi"]:::pythonapi
        end

        %% C Extension / Binding Layer
        subgraph "CPython Extension Module"
            direction TB
            lang_c["language.c"]:::cext
            lookahead_it_c["lookahead_iterator.c"]:::cext
            lookahead_names_it_c["lookahead_names_iterator.c"]:::cext
            module_c["module.c"]:::cext
            node_c["node.c"]:::cext
            parser_c["parser.c"]:::cext
            query_c["query.c"]:::cext
            query_predicates_c["query_predicates.c"]:::cext
            range_c["range.c"]:::cext
            tree_c["tree.c"]:::cext
            tree_cursor_c["tree_cursor.c"]:::cext
            types_h["types.h"]:::cext
        end

        %% Tree-sitter Core
        core["Tree-sitter Core Library"]:::core

        %% Language Plugins
        plugins["External Language Plugins"]:::plugins
    end

    %% Support Infrastructure
    subgraph "Support Infrastructure"
        direction TB
        examples_usage["examples/usage.py"]:::support
        examples_walk["examples/walk_tree.py"]:::support
        tests_dir["tests/"]:::support
        docs_dir["docs/"]:::support
        ci_dir[".github/workflows/"]:::support
        packaging["setup.py, pyproject.toml, MANIFEST.in"]:::support
        typing_marker["tree_sitter/py.typed"]:::support
    end

    %% Relationships
    UA -->|"import & call"| API_init
    API_init -->|"calls binding via CPython API"| module_c
    API_init -->|"type hints"| API_stub
    module_c -->|"invokes parser functions"| core
    core -->|"returns parse trees"| module_c
    API_init -->|"loads at runtime"| plugins
    UA -->|"runs examples/tests/docs"| examples_usage
    UA -->|"runs examples/tests/docs"| examples_walk
    UA -->|"runs tests"| tests_dir
    UA -->|"build & publish"| ci_dir
    UA -->|"install & package"| packaging
    UA -->|"type info"| typing_marker

    %% Click Events
    click API_init "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/__init__.py"
    click API_stub "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/__init__.pyi"
    click lang_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/language.c"
    click lookahead_it_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/lookahead_iterator.c"
    click lookahead_names_it_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/lookahead_names_iterator.c"
    click module_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/module.c"
    click node_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/node.c"
    click parser_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/parser.c"
    click query_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/query.c"
    click query_predicates_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/query_predicates.c"
    click range_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/range.c"
    click tree_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/tree.c"
    click tree_cursor_c "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/tree_cursor.c"
    click types_h "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/binding/types.h"
    click core "https://github.com/tree-sitter/py-tree-sitter/tree/master/tree_sitter/core/"
    click examples_usage "https://github.com/tree-sitter/py-tree-sitter/blob/master/examples/usage.py"
    click examples_walk "https://github.com/tree-sitter/py-tree-sitter/blob/master/examples/walk_tree.py"
    click tests_dir "https://github.com/tree-sitter/py-tree-sitter/tree/master/tests/"
    click docs_dir "https://github.com/tree-sitter/py-tree-sitter/tree/master/docs/"
    click ci_dir "https://github.com/tree-sitter/py-tree-sitter/blob/master/.github/workflows/ci.yml"
    click packaging "https://github.com/tree-sitter/py-tree-sitter/blob/master/setup.py"
    click typing_marker "https://github.com/tree-sitter/py-tree-sitter/blob/master/tree_sitter/py.typed"

    %% Styles
    classDef pythonapi fill:#ccf,stroke:#000,color:#000
    classDef cext fill:#fca,stroke:#000,color:#000
    classDef core fill:#cfc,stroke:#000,color:#000
    classDef plugins fill:#c9c,stroke:#000,color:#000
    classDef support fill:#eee,stroke:#666,color:#000
    classDef external fill:#ddd,stroke:#000,color:#000
```
