Tree-sitter Backend¶

The Tree-sitter backend (headerkit.backends.treesitter) is a zero-dependency parser backend for C and C++ headers and sources using tree-sitter-c and tree-sitter-cpp.

Features¶

Zero Host Tooling Required: Does not require LLVM, Xcode Command Line Tools, or libclang.so/.dylib/.dll installed on the host.
Precompiled Wheels: Uses prebuilt wheels from PyPI (tree-sitter, tree-sitter-c, and tree-sitter-cpp).
Hook Integration: Registered at Priority.FALLBACK for parse_unit, serving as an automatic fallback when libclang is missing.

Installation¶

Install the optional extra:

pip install "headerkit[treesitter]"

Usage¶

CLIPython API

headerkit mylib.h --backend tree-sitter -w ctypes -o ctypes:bindings.py

from headerkit.backends.treesitter import TreeSitterBackend

backend = TreeSitterBackend()
header = backend.parse(code, "mylib.h")

API Reference¶

TreeSitterBackend ¶

TreeSitterBackend()

Parser backend using tree-sitter-c and tree-sitter-cpp.

parse ¶

parse(code, filename, include_dirs=None, extra_args=None, *, use_default_includes=True, recursive_includes=True, max_depth=10, project_prefixes=None, allowlist=None, denylist=None)

Parse C/C++ code with tree-sitter and return the IR representation.

This backend parses exactly the code string it is given. It does not read the filesystem and does not follow #include directives, so include_dirs, recursive_includes, max_depth, project_prefixes, allowlist and denylist have nothing to act on.

Parameters:

Name	Type	Description	Default
`allowlist`	`list[str] \| None`	Not honored by this backend. An allowlist selects which included files keep their declarations; since no declaration here can originate from an `#include`, there is nothing to select. An entry naming a file other than the one being parsed raises :class:`UserWarning` rather than being discarded silently, because such a caller is expecting symbols this backend will never produce. Entries that all resolve to the parsed file itself are already satisfied and warn nothing. Use the libclang backend when allowlist filtering is required.	`None`
`denylist`	`list[str] \| None`	Not honored by this backend, for the same reason and with the same warning. An entry naming another file describes a declaration this backend was never going to emit, so honoring it and ignoring it are indistinguishable -- which is exactly the silence the warning breaks. Entries resolving to the parsed file itself warn nothing, because this backend does not deny the parsed file either.	`None`