Python API Reference

Python API Reference v1.15.7

Functions

detect_language_from_extension()

Detect language name from a file extension (without leading dot).

Returns None for unrecognized extensions. The match is case-insensitive.

Signature:

def detect_language_from_extension(ext: str) -> str | None

Example:

result = detect_language_from_extension("value")

Parameters:

Name	Type	Required	Description
ext	str	Yes	The ext

Returns: str | None

---

detect_language_from_path()

Detect language name from a file path.

Extracts the file extension and looks it up. Returns None if the path has no extension or the extension is not recognized.

Signature:

def detect_language_from_path(path: str) -> str | None

Example:

result = detect_language_from_path("value")

Parameters:

Name	Type	Required	Description
path	str	Yes	Path to the file

Returns: str | None

---

detect_language_from_content()

Detect language name from file content using the shebang line (#!).

Inspects only the first line of content. If it begins with #!, the interpreter name is extracted and mapped to a language name.

Handles common patterns:

• #!/usr/bin/env python3 → "python"
• #!/bin/bash → "bash"
• #!/usr/bin/env node → "javascript"

The -S flag accepted by some env implementations is skipped automatically. Version suffixes (e.g. python3.11, ruby3.2) are stripped before matching.

A leading UTF-8 BOM (U+FEFF) is skipped before the #! check, so a BOM-prefixed script is still detected by its shebang.

Returns None when content does not start with #! (after stripping a leading BOM), the shebang is malformed, or the interpreter is not recognised.

Signature:

def detect_language_from_content(content: str) -> str | None

Example:

result = detect_language_from_content("value")

Parameters:

Name	Type	Required	Description
content	str	Yes	The content to process

Returns: str | None

---

get_highlights_query()

Get the highlights query for a language, if bundled.

Returns the contents of highlights.scm as a static string, or None if no highlights query is bundled for this language.

Signature:

def get_highlights_query(language: str) -> str | None

Example:

result = get_highlights_query("value")

Parameters:

Name	Type	Required	Description
language	str	Yes	The language

Returns: str | None

---

get_injections_query()

Get the injections query for a language, if bundled.

Returns the contents of injections.scm as a static string, or None if no injections query is bundled for this language.

Signature:

def get_injections_query(language: str) -> str | None

Example:

result = get_injections_query("value")

Parameters:

Name	Type	Required	Description
language	str	Yes	The language

Returns: str | None

---

get_locals_query()

Get the locals query for a language, if bundled.

Returns the contents of locals.scm as a static string, or None if no locals query is bundled for this language.

Signature:

def get_locals_query(language: str) -> str | None

Example:

result = get_locals_query("value")

Parameters:

Name	Type	Required	Description
language	str	Yes	The language

Returns: str | None

---

get_tags_query()

Get the tags query for a language, if bundled.

Returns the contents of tags.scm as a static string, or None if no tags query is bundled for this language.

Signature:

def get_tags_query(language: str) -> str | None

Example:

result = get_tags_query("value")

Parameters:

Name	Type	Required	Description
language	str	Yes	The language

Returns: str | None

---

get_indents_query()

Get the indents query for a language, if bundled.

Returns the contents of indents.scm (used for auto-indentation) as a static string, or None if no indents query is bundled for this language.

Signature:

def get_indents_query(language: str) -> str | None

Example:

result = get_indents_query("value")

Parameters:

Name	Type	Required	Description
language	str	Yes	The language

Returns: str | None

---

get_folds_query()

Get the folds query for a language, if bundled.

Returns the contents of folds.scm (used for code folding) as a static string, or None if no folds query is bundled for this language.

Signature:

def get_folds_query(language: str) -> str | None

Example:

result = get_folds_query("value")

Parameters:

Name	Type	Required	Description
language	str	Yes	The language

Returns: str | None

---

get_language()

Get a tree-sitter Language by name using the global registry.

Resolves language aliases (e.g., "shell" maps to "bash"). When the download feature is enabled (default), automatically downloads the parser from GitHub releases if not found locally.

Errors:

Returns Error.LanguageNotFound if the language is not recognized, or Error.Download if auto-download fails.

Signature:

def get_language(name: str) -> Language

Example:

result = get_language("value")

Parameters:

Name	Type	Required	Description
name	str	Yes	The name

Returns: Language

Errors: Raises Error.

---

get_parser()

Get a Parser pre-configured for the given language.

This is a convenience function that calls get_language and configures a new parser in one step.

Errors:

Returns Error.LanguageNotFound if the language is not recognized, or Error.ParserSetup if the language cannot be applied to the parser.

Signature:

def get_parser(name: str) -> Parser

Example:

result = get_parser("value")

Parameters:

Name	Type	Required	Description
name	str	Yes	The name

Returns: Parser

Errors: Raises Error.

---

detect_language()

Detect language name from a file path or extension.

This compatibility alias matches the pre-Alef Python binding API.

Signature:

def detect_language(path: str) -> str | None

Example:

result = detect_language("value")

Parameters:

Name	Type	Required	Description
path	str	Yes	Path to the file

Returns: str | None

---

available_languages()

List all available language names (sorted, deduplicated, includes aliases).

Returns names of both statically compiled and dynamically loadable languages, plus any configured aliases.

Signature:

def available_languages() -> list[str]

Example:

result = available_languages()

Returns: list[str]

---

has_language()

Check if a language is available by name or alias.

Returns True if the language can be loaded (statically compiled, dynamically available, or a known alias for one of these).

Signature:

def has_language(name: str) -> bool

Example:

result = has_language("value")

Parameters:

Name	Type	Required	Description
name	str	Yes	The name

Returns: bool

---

language_count()

Return the number of available languages.

Includes statically compiled languages, dynamically loadable languages, and aliases.

Signature:

def language_count() -> int

Example:

result = language_count()

Returns: int

---

process()

Process source code and extract file intelligence using the global registry.

Parses the source with tree-sitter and extracts metrics, structure, imports, exports, comments, docstrings, symbols, diagnostics, and/or chunks based on the flags set in ProcessConfig.

Errors:

Returns Error.InvalidRange if the config carries a zero-valued limit or the source exceeds ProcessConfig.max_source_bytes, Error.ParseTimeout if the parse exceeds ProcessConfig.parse_timeout_ms, Error.LanguageNotFound if the language is unknown, or Error.ParseFailed if parsing yields no tree.

Signature:

def process(source: str, config: ProcessConfig) -> ProcessResult

Example:

result = process("value", ProcessConfig())

Parameters:

Name	Type	Required	Description
source	str	Yes	The source
config	ProcessConfig	Yes	The configuration options

Returns: ProcessResult

Errors: Raises Error.

---

init()

Initialize the language pack with the given configuration.

Applies any custom cache directory, then downloads all languages and groups specified in the config. This is the recommended entry point when you want to pre-warm the cache before use.

Errors:

Returns an error if configuration cannot be applied or if downloads fail.

Signature:

def init(config: PackConfig) -> None

Example:

init(PackConfig())

Parameters:

Name	Type	Required	Description
config	PackConfig	Yes	The configuration options

Returns: No return value.

Errors: Raises Error.

---

configure()

Apply download configuration without downloading anything.

Use this to set a custom cache directory before the first call to get_language or any download function. Changing the cache dir after languages have been registered has no effect on already-loaded languages.

PackConfig.cache_dir is a BASE directory, not the final libs path: this crate appends tree-sitter-language-pack/v{version}/libs to it, the same suffix applied to the platform default cache directory. In the example below, files actually land under /tmp/my-parsers/tree-sitter-language-pack/v{version}/libs/, never directly in /tmp/my-parsers/. Call cache_dir to read back the resolved, fully-suffixed path.

Errors:

Returns an error if the lock cannot be acquired.

Signature:

def configure(config: PackConfig) -> None

Example:

configure(PackConfig())

Parameters:

Name	Type	Required	Description
config	PackConfig	Yes	The configuration options

Returns: No return value.

Errors: Raises Error.

---

download()

Download specific languages to the local cache.

Returns the number of distinct languages available after the call. Already compiled or cached languages are included in the count.

Aliases are resolved before counting, so ["shell", "bash"] names one language and returns 1.

Errors:

Returns an error if any language is not available in the manifest or if the download fails.

Signature:

def download(names: list[str]) -> int

Example:

result = download([])

Parameters:

Name	Type	Required	Description
names	list\[str\]	Yes	The names

Returns: int

Errors: Raises Error.

---

prefetch()

Prefetch grammars: download any not already loadable from disk, then load every requested language into the process registry so a subsequent hot loop only parses.

Unlike download(), this does not trust in-memory availability — it downloads whenever a grammar is not actually loadable from disk (fixing the case where a known-but-not-downloaded grammar is reported present), then resolves and caches every requested language. Call it once, up front, before a parallel workload.

Errors:

Returns Error.Download if a required grammar cannot be fetched, or Error.LanguageNotFound if a requested name is unknown.

Signature:

def prefetch(languages: list[str]) -> None

Example:

prefetch([])

Parameters:

Name	Type	Required	Description
languages	list\[str\]	Yes	The languages

Returns: No return value.

Errors: Raises Error.

---

download_all()

Download all available languages from the remote manifest.

Downloads the platform bundle and extracts every library it contains. Languages that appear in the manifest but are absent from the bundle (e.g. grammars that failed to compile at release time) are silently skipped — they are not treated as an error.

Returns the total number of languages now available (statically compiled plus downloaded and cached).

Errors:

Returns an error if the manifest cannot be fetched or the bundle download fails.

Signature:

def download_all() -> int

Example:

result = download_all()

Returns: int

Errors: Raises Error.

---

download_group()

Download every language in a named group.

Groups are defined by the remote manifest, not by this library, and let you ensure a curated set of related grammars in one call instead of listing each name to download(). Already-cached languages are skipped.

Call manifest_groups to discover the group names the manifest actually defines. The published manifest currently defines a single group, "all"; earlier revisions of this documentation advertised "web", "data", and "systems", which the manifest has never contained, so every call following that example failed. Do not hardcode a group name without checking.

Returns the total number of languages now available (statically compiled plus downloaded and cached).

Errors:

Returns Error.Download if the manifest cannot be fetched, if the group is unknown — the message lists the groups the manifest defines — or if any constituent language fails to download.

Signature:

def download_group(name: str) -> int

Example:

result = download_group("value")

Parameters:

Name	Type	Required	Description
name	str	Yes	The name

Returns: int

Errors: Raises Error.

---

manifest_languages()

Return all language names available in the remote manifest (371).

Fetches (and caches) the remote manifest to discover the full list of downloadable languages. Use downloaded_languages to list what is already cached locally.

Errors:

Returns an error if the manifest cannot be fetched.

Signature:

def manifest_languages() -> list[str]

Example:

result = manifest_languages()

Returns: list[str]

Errors: Raises Error.

---

manifest_groups()

Return the names of every language group the remote manifest defines, sorted.

Group names are manifest data, not a compile-time constant of this library, so this is the only reliable way to learn what download_group and PackConfig.groups accept. The published manifest currently defines just "all".

Errors:

Returns Error.Download if the manifest cannot be fetched.

Signature:

def manifest_groups() -> list[str]

Example:

result = manifest_groups()

Returns: list[str]

Errors: Raises Error.

---

downloaded_languages()

Return languages that are already downloaded and cached locally.

Does not perform any network requests. Returns an empty list if the cache directory does not exist or cannot be read.

Signature:

def downloaded_languages() -> list[str]

Example:

result = downloaded_languages()

Returns: list[str]

---

clean_cache()

Delete all cached parser shared libraries.

Resets the cache registration so the next call to get_language or a download function will re-register the (now empty) cache directory.

Errors:

Returns an error if the cache directory cannot be removed.

Signature:

def clean_cache() -> None

Example:

clean_cache()

Returns: No return value.

Errors: Raises Error.

---

cache_dir()

Return the effective cache directory path.

This is {base}/tree-sitter-language-pack/v{version}/libs/, where {base} is either the custom BASE directory set via configure / init (PackConfig.cache_dir) or the platform default cache directory — both are suffixed identically, so a custom cache_dir is never used as the final libs path. The default resolves to ~/.cache/tree-sitter-language-pack/v{version}/libs/ on a typical Unix system.

Errors:

Returns an error if no cache directory can be resolved: version is somehow invalid, or (with no custom cache_dir configured) the platform reports none and TREE_SITTER_LANGUAGE_PACK_CACHE_DIR is unset. This crate no longer falls back to the temporary directory for the latter case — see #101 H2.

Signature:

def cache_dir() -> str

Example:

result = cache_dir()

Returns: str

Errors: Raises Error.

---

Types

ByteRange

A byte range — start (inclusive) to end (exclusive).

Field	Type	Default	Description
start	int	—	Inclusive start byte offset.
end	int	—	Exclusive end byte offset.

---

ChunkContext

Metadata for a single chunk of source code.

Field	Type	Default	Description
language	str	—	Language name used to parse this chunk.
chunk_index	int	—	Zero-indexed position of this chunk within the file’s chunk list.
total_chunks	int	—	Total number of chunks the file was split into.
node_types	list\[str\]	[]	Tree-sitter node kinds that appear at the top level of this chunk.
context_path	list\[str\]	[]	Hierarchical path of enclosing structural items (e.g., ["MyClass", "my_method"]).
symbols_defined	list\[str\]	[]	Names of symbols defined within this chunk.
comments	list\[CommentInfo\]	[]	Comments contained within this chunk.
docstrings	list\[DocstringInfo\]	[]	Docstrings contained within this chunk. Populated only for Python — the same language for which ProcessResult.docstrings is populated, and by the same classifier. Always empty for every other language.
has_error_nodes	bool	—	Whether this chunk contains any tree-sitter error nodes.

---

CodeChunk

A chunk of source code with rich metadata.

Field	Type	Default	Description
content	str	—	The raw source text of this chunk.
start_byte	int	—	Inclusive start byte offset of this chunk in the original source.
end_byte	int	—	Exclusive end byte offset of this chunk in the original source.
start_line	int	—	Zero-indexed start line of this chunk.
end_line	int	—	Zero-indexed row of the last byte actually included in this chunk (inclusive — the same row a Span.end_line would report for a node ending on that byte). Computed the same way regardless of whether the source has a trailing newline: it is always the row of end_byte - 1, never a phantom row past the file’s real content.
metadata	ChunkContext	—	Contextual metadata about this chunk.

---

CommentInfo

A comment extracted from source code.

Field	Type	Default	Description
text	str	—	The raw text content of the comment.
kind	CommentKind	CommentKind.LINE	The kind of comment (line, block, or doc).
span	Span	—	Source span covering the comment.
associated_node	str | None	None	Name of the syntax node this comment is directly associated with.

---

DataAttribute

An XML-style attribute attached to an Element node.

Populated only for DataNodeKind.Element; always empty for KeyValue and Sequence nodes.

Field	Type	Default	Description
name	str	—	Attribute name (e.g. "class", "href").
value	str	—	Attribute value as a raw string (quotes stripped).
span	Span	—	Source span covering the entire name="value" attribute token.

---

DataNode

A node in the hierarchical data tree produced by data-format extraction.

When ProcessConfig.data_extraction is True, ProcessResult.data is populated with a root DataNode whose children mirror the structure of the parsed file.

The kind field determines which other fields are meaningful:

kind	key	value	attributes	children
KeyValue	key / mapping key / index	leaf value	empty	nested map
Element	XML tag name	text content	XML attrs	child elements
Sequence	positional index ("0")	leaf value	empty	sub-items

Field	Type	Default	Description
kind	DataNodeKind	DataNodeKind.KEY_VALUE	Whether this node is a key/value pair, XML element, or sequence item.
key	str | None	None	Key, attribute name, tag name, or positional index ("0", "1", …). None at the document root.
value	str | None	None	Leaf scalar value, if any. None for containers (objects, arrays, XML elements with child elements).
attributes	list\[DataAttribute\]	[]	Attributes on element-shape nodes (XML STag attributes). Empty for all other kinds.
children	list\[DataNode\]	[]	Children for nested containers and XML element bodies.
span	Span	—	Source span covering this node in the original source file.

---

Diagnostic

A diagnostic (syntax error, missing node, etc.) from parsing.

Field	Type	Default	Description
message	str	—	Human-readable description of the diagnostic.
severity	DiagnosticSeverity	DiagnosticSeverity.ERROR	Severity of the diagnostic.
span	Span	—	Source span where the diagnostic was detected.

---

DocSection

A section within a docstring (e.g., Args, Returns, Raises).

Field	Type	Default	Description
kind	str	—	Section kind (e.g., "args", "returns", "raises").
name	str | None	None	Parameter or return value name, if applicable.
description	str	—	Description text for this section.

---

DocstringInfo

A docstring extracted from source code.

Field	Type	Default	Description
text	str	—	The raw text of the docstring.
format	DocstringFormat	DocstringFormat.PYTHON_TRIPLE_QUOTE	The docstring format (Python, JSDoc, Rustdoc, etc.).
span	Span	—	Source span covering the docstring.
associated_item	str | None	None	Name of the item this docstring documents.
parsed_sections	list\[DocSection\]	[]	Parsed sections of the docstring (Args, Returns, Raises, etc.). Reserved: not yet populated. Always empty, for every DocstringFormat. Parsing a docstring body into sections requires implementing each convention’s own layout (Google/NumPy/reST style for Python, @param/@returns for JSDoc/Javadoc, and so on), which no extractor here does yet. The field is kept rather than removed so a consumer’s deserializer does not need updating once it is.

---

DownloadManager

Manages downloading and caching of pre-built parser shared libraries.

Methods

new()

Create a new download manager for the given version.

Errors:

Returns Error.Download if version is empty, contains a path separator or .., or contains a character outside [A-Za-z0-9.+-] — see validate_version — or if no cache directory can be resolved (see Self.default_cache_dir).

Signature:

@staticmethod
def new(version: str) -> DownloadManager

Example:

result = DownloadManager.new("value")

Parameters:

Name	Type	Required	Description
version	str	Yes	The version

Returns: DownloadManager

Errors: Raises Error.

installed_languages()

List languages that are already downloaded and cached.

Derived from the on-disk cache filenames, one canonical name per file, plus every alias that resolves to it (via aliases_for) — so this list agrees with the user-facing LanguageRegistry.available_languages about which names are “available”; both report "shell" once bash is cached, for example. A previous version reported canonical names only, which could never agree with available_languages(). See #107.

Returns an empty list if the cache directory does not exist. If it exists but cannot be read (e.g. a permission error), also returns an empty list — changing this to a Result would be a breaking change across every language binding — but logs a tracing.warn! so the failure is not silently indistinguishable from “nothing installed”.

Signature:

def installed_languages(self) -> list[str]

Example:

result = instance.installed_languages()

Returns: list[str]

download_all_best_effort()

Download the platform bundle and extract every library file it contains.

Unlike Self.ensure_languages, this does not check the manifest language list against archive contents — it simply extracts all .so/.dylib/.dll files from the bundle. Languages in the manifest that are missing from the archive are silently ignored rather than returning an error.

Returns the number of library files extracted (including those already cached).

Signature:

def download_all_best_effort(self) -> int

Example:

result = instance.download_all_best_effort()

Returns: int

Errors: Raises Error.

clean_cache()

Remove all cached parser libraries.

Acquires the cross-process lock so clean_cache cannot race a concurrent downloader (avoids Windows sharing-violation errors against an in-flight bundle write). The .download.lock file itself is not removed — it is permanent infrastructure; deleting it could allow a concurrent process that already opened the file to continue holding a stale lock handle while a new process opens a fresh inode, breaking the mutual-exclusion guarantee.

Signature:

def clean_cache(self) -> None

Example:

instance.clean_cache()

Returns: No return value.

Errors: Raises Error.

---

ExportInfo

An export statement extracted from source code.

Field	Type	Default	Description
name	str	—	The exported name.
kind	ExportKind	ExportKind.NAMED	The kind of export (named, default, or re-export).
span	Span	—	Source span covering the export statement.

---

FileMetrics

Aggregate metrics for a source file.

Field	Type	Default	Description
total_lines	int	—	Total number of lines (including blank and comment lines).
code_lines	int	—	Number of lines containing non-blank, non-comment source code.
comment_lines	int	—	Number of lines that are entirely comments.
blank_lines	int	—	Number of blank (whitespace-only) lines.
total_bytes	int	—	Total byte length of the source file.
node_count	int	—	Total number of nodes in the syntax tree.
error_count	int	—	Number of error nodes in the syntax tree (parse errors).
max_depth	int	—	Maximum nesting depth reached in the syntax tree.

---

ImportInfo

An import statement extracted from source code.

Field	Type	Default	Description
source	str	—	The module or path being imported from.
items	list\[str\]	[]	Specific names imported from the source module. For import a, b / from m import a, b, every entry’s base name (never the alias). For a JavaScript/TypeScript named-imports clause (import { a, b as c } from 'm'), every specifier’s original name. Populated for Python and JavaScript/TypeScript only. Always empty for every other language this library recognises import statements for — Rust, Go, Java, Kotlin, and Elixir (import/alias/require/use) — and for a JS/TS namespace import (import * as ns) or default import (import x from 'm'), neither of which names individual items.
alias	str | None	None	Alias assigned to the import (e.g., import numpy as np). Populated for Python’s single-name form (import numpy as np, from m import a as b) and JavaScript/TypeScript’s namespace form (import * as ns from 'm') or a named-imports clause naming exactly one specifier (import { a as b } from 'm'). None for Rust, Go, Java, Kotlin, and Elixir (which has its own as: alias option on alias directives, not yet extracted here) — and for a Python statement that aliases several names at once (import os, sys as s), where there is no single alias to report for the statement as a whole, so only items is populated for it.
is_wildcard	bool	—	Whether this is a wildcard import (e.g., import * or use foo.*). Detected from the syntax tree — a dedicated wildcard node (wildcard_import in Python, use_wildcard in Rust) or a bare * token outside of string-literal content — not by searching the import’s source text for a * character, so a glob in an import path string (import a from './glob*.js') is not mistaken for one.
span	Span	—	Source span covering the import statement.

---

Language

---

LanguageRegistry

Thread-safe registry of tree-sitter language parsers.

Manages both statically compiled and dynamically loaded language grammars. Use LanguageRegistry.new() for the default registry, or access the global instance via the module-level convenience functions (get_language, available_languages, etc.).

Methods

new()

Create a new registry populated with all statically compiled languages.

When the dynamic-loading feature is enabled, the registry also knows about dynamically loadable grammars and will load them on demand.

Signature:

@staticmethod
def new() -> LanguageRegistry

Example:

result = LanguageRegistry.new()

Returns: LanguageRegistry

get_language()

Get a tree-sitter Language by name.

Resolves aliases (e.g., "shell" -> "bash", "makefile" -> "make"), then looks up the language in the static table. When the dynamic-loading feature is enabled, falls back to loading a shared library on demand.

Errors:

Returns Error.LanguageNotFound if the name (after alias resolution) does not match any known grammar.

Signature:

def get_language(self, name: str) -> Language

Example:

result = instance.get_language("value")

Parameters:

Name	Type	Required	Description
name	str	Yes	The name

Returns: Language

Errors: Raises Error.

available_languages()

List all available language names, sorted and deduplicated.

Includes statically compiled languages, dynamically loadable languages (if the dynamic-loading feature is enabled), and all configured aliases.

Signature:

def available_languages(self) -> list[str]

Example:

result = instance.available_languages()

Returns: list[str]

has_parser()

Check whether this language can be parsed right now, without downloading.

Resolves aliases, then answers from exactly the lookup get_language performs: the statically compiled table, the already-loaded dynamic grammars, and the parser shared libraries present in the primary and extra (download-cache) library directories. It never performs network I/O.

A previous implementation consulted only the statically compiled table. That table is empty in every build that does not set TSLP_LANGUAGES, so the function answered False for languages this registry parses perfectly well.

Contrast has_language, which is also True for a grammar that is merely known to the manifest and would have to be downloaded first. The pair distinguishes “we can parse it offline, now” from “we recognise the name”.

The first True answer for a dynamic grammar loads its shared library: loading is the only way to know the grammar is usable, since a truncated or wrong-architecture library exists on disk but cannot parse. Loads are cached process-wide, so repeat calls are cheap.

use tree_sitter_language_pack::{detect_language_from_extension, LanguageRegistry};

let registry = LanguageRegistry::new();
// Extension detection uses the static ext table for all 371 grammars.
let lang = detect_language_from_extension("feature"); // always returns Some("gherkin")
// Parser availability depends on what is compiled in or cached on disk.
let can_parse = lang.map(|name| registry.has_parser(name)).unwrap_or(false);

Signature:

def has_parser(self, name: str) -> bool

Example:

result = instance.has_parser("value")

Parameters:

Name	Type	Required	Description
name	str	Yes	The name

Returns: bool

has_language()

Check whether a language is available by name or alias.

Returns True if the language can be loaded, either from the static table or from a dynamic library on disk.

Every branch is one more way to answer True, so they are ordered cheapest-first and the filesystem is only consulted once every in-memory source has said no. Probing the loaded-grammar map and the manifest ahead of the stat calls is what keeps this off the syscall path for the languages a process actually uses.

Signature:

def has_language(self, name: str) -> bool

Example:

result = instance.has_language("value")

Parameters:

Name	Type	Required	Description
name	str	Yes	The name

Returns: bool

language_count()

Return the total number of available languages (including aliases).

Counts the same set available_languages lists, without materialising or sorting it.

Signature:

def language_count(self) -> int

Example:

result = instance.language_count()

Returns: int

process()

Parse source code and extract file intelligence based on config in a single pass.

Errors:

Returns Error.InvalidRange if the config is invalid (see ProcessConfig.validate) or if the source exceeds the configured max_source_bytes; Error.LanguageNotFound if the language is unknown; or Error.ParseFailed if parsing produces no tree.

Signature:

def process(self, source: str, config: ProcessConfig) -> ProcessResult

Example:

result = instance.process("value", ProcessConfig())

Parameters:

Name	Type	Required	Description
source	str	Yes	The source
config	ProcessConfig	Yes	The configuration options

Returns: ProcessResult

Errors: Raises Error.

---

Node

A single syntax node within a Tree.

Nodes hold a strong reference to their parent tree so they remain valid regardless of how the tree is moved or stored at the FFI boundary.

Methods

kind()

Return the node’s kind name (e.g. "function_definition").

Signature:

def kind(self) -> str

Example:

result = instance.kind()

Returns: str

kind_id()

Return the node’s numeric kind ID.

Tree-sitter assigns a stable u16 ID to every node kind in a grammar (e.g. "function_definition" → 42). Comparing kind_id() is cheaper than comparing the string kind() in tight AST loops.

Signature:

def kind_id(self) -> int

Example:

result = instance.kind_id()

Returns: int

start_byte()

Return the inclusive start byte offset of this node.

Signature:

def start_byte(self) -> int

Example:

result = instance.start_byte()

Returns: int

end_byte()

Return the exclusive end byte offset of this node.

Signature:

def end_byte(self) -> int

Example:

result = instance.end_byte()

Returns: int

byte_range()

Return the node’s byte range as a ByteRange.

Callers should slice their own source bytes — this is a zero-copy text accessor.

Signature:

def byte_range(self) -> ByteRange

Example:

result = instance.byte_range()

Returns: ByteRange

start_position()

Return the start Point (row, column).

Signature:

def start_position(self) -> Point

Example:

result = instance.start_position()

Returns: Point

end_position()

Return the end Point (row, column).

Signature:

def end_position(self) -> Point

Example:

result = instance.end_position()

Returns: Point

is_named()

True when this node is named (not punctuation/whitespace).

Signature:

def is_named(self) -> bool

Example:

result = instance.is_named()

Returns: bool

is_error()

True when this is an error node.

Signature:

def is_error(self) -> bool

Example:

result = instance.is_error()

Returns: bool

is_missing()

True when this is a missing-token node.

Signature:

def is_missing(self) -> bool

Example:

result = instance.is_missing()

Returns: bool

is_extra()

True when this is an “extra” node (e.g. a comment).

Signature:

def is_extra(self) -> bool

Example:

result = instance.is_extra()

Returns: bool

has_error()

True when this node or any descendant is an error.

Signature:

def has_error(self) -> bool

Example:

result = instance.has_error()

Returns: bool

parent()

Return this node’s parent, if any.

Signature:

def parent(self) -> Node | None

Example:

result = instance.parent()

Returns: Node | None

child()

Return the i-th child of this node, if any.

Signature:

def child(self, index: int) -> Node | None

Example:

result = instance.child(42)

Parameters:

Name	Type	Required	Description
index	int	Yes	The index

Returns: Node | None

child_count()

Total number of children (including unnamed).

Signature:

def child_count(self) -> int

Example:

result = instance.child_count()

Returns: int

named_child()

Return the i-th named child of this node, if any.

Signature:

def named_child(self, index: int) -> Node | None

Example:

result = instance.named_child(42)

Parameters:

Name	Type	Required	Description
index	int	Yes	The index

Returns: Node | None

named_child_count()

Number of named children of this node.

Signature:

def named_child_count(self) -> int

Example:

result = instance.named_child_count()

Returns: int

child_by_field_name()

Look up a child by its grammar-defined field name.

Signature:

def child_by_field_name(self, name: str) -> Node | None

Example:

result = instance.child_by_field_name("value")

Parameters:

Name	Type	Required	Description
name	str	Yes	The name

Returns: Node | None

to_sexp()

Return the S-expression form of this node’s subtree.

Signature:

def to_sexp(self) -> str

Example:

result = instance.to_sexp()

Returns: str

walk()

Return a TreeCursor positioned at this node.

Signature:

def walk(self) -> TreeCursor

Example:

result = instance.walk()

Returns: TreeCursor

---

PackConfig

Configuration for the tree-sitter language pack.

Controls cache directory and which languages to pre-download. Can be loaded from a TOML file, constructed programmatically, or passed as a dict/object from language bindings.

Field	Type	Default	Description
cache_dir	str | None	None	Override the BASE directory the parser cache lives under. This is a base, not the final library path: the crate appends tree-sitter-language-pack/v{version}/libs to it, exactly as it does to the platform default. So cache_dir = "/tmp/my-parsers" resolves to /tmp/my-parsers/tree-sitter-language-pack/v{version}/libs/. The suffix is not cosmetic. It keeps the whole cache tree — manifest, bundles and lock file included — inside a directory this library owns and versions. Earlier releases used this path verbatim, which put those files in the configured directory’s PARENT and let a cache built by one crate version be reused by another. Default base: the platform cache dir, e.g. ~/.cache on Linux.
languages	list\[str\] | None	[]	Languages to pre-download on init. Each entry is a language name (e.g. "python", "rust").
groups	list\[str\] | None	[]	Language groups to pre-download. Group names come from the remote manifest, so the valid set is not fixed by this library; the published manifest currently defines only "all". Call manifest_groups to enumerate them. An unknown name makes init fail.

---

Parser

A tree-sitter parser configured for one language at a time.

Methods

new()

Construct a new parser with no language set and no parse limits.

Call Parser.set_language before parsing. Limits are opt-in via set_max_source_bytes and set_parse_timeout_ms; both default to unbounded so that existing callers are unaffected.

Signature:

@staticmethod
def new() -> Parser

Example:

result = Parser.new()

Returns: Parser

set_max_source_bytes()

Refuse to parse sources longer than max_bytes.

None (the default) means no limit. Over-limit input makes parse and parse_bytes return None after emitting a WARN; input is never silently truncated.

See RECOMMENDED_MAX_SOURCE_BYTES.

Signature:

def set_max_source_bytes(self, max_bytes: int) -> None

Example:

instance.set_max_source_bytes(max_bytes=42)

Parameters:

Name	Type	Required	Description
max_bytes	int | None	No	The max bytes

Returns: No return value.

set_parse_timeout_ms()

Cancel a parse that exceeds timeout_ms milliseconds of wall clock.

None (the default) means no budget. Cancellation runs through tree-sitter’s parse progress callback, so it is granular to that callback’s interval rather than exact.

See RECOMMENDED_PARSE_TIMEOUT_MS.

Signature:

def set_parse_timeout_ms(self, timeout_ms: int) -> None

Example:

instance.set_parse_timeout_ms(timeout_ms=42)

Parameters:

Name	Type	Required	Description
timeout_ms	int | None	No	The timeout ms

Returns: No return value.

set_language()

Configure the parser to use the language identified by name (e.g. "python").

Resolves the language through the global registry — auto-downloading if necessary, when the download feature is enabled.

Errors:

Returns Error.LanguageNotFound if the language is not recognized, or Error.ParserSetup if the language ABI is incompatible.

Signature:

def set_language(self, name: str) -> None

Example:

instance.set_language("value")

Parameters:

Name	Type	Required	Description
name	str	Yes	The name

Returns: No return value.

Errors: Raises Error.

parse()

Parse a UTF-8 source string.

Returns None if no language is set, if the parse was cancelled by the configured timeout, or if the source exceeds the configured size limit. Each non-parse outcome is logged, so an empty result is never silent.

Concurrency

Parsing runs fully in parallel across threads for almost every language — no lock is taken. The exception is the small set of grammars whose external scanner keeps mutable process-global state (currently just properties): parses of that language are serialized against each other through an internal per-language lock, so that concurrent threads can’t corrupt shared scanner state. Every other language is unaffected by that lock and never waits on it.

Signature:

def parse(self, source: str) -> Tree | None

Example:

result = instance.parse("value")

Parameters:

Name	Type	Required	Description
source	str	Yes	The source

Returns: Tree | None

parse_bytes()

Parse a raw byte slice.

Same outcomes as parse, including the concurrency behaviour documented there.

Signature:

def parse_bytes(self, source: bytes) -> Tree | None

Example:

result = instance.parse_bytes(b"data")

Parameters:

Name	Type	Required	Description
source	bytes	Yes	The source

Returns: Tree | None

reset()

Reset internal state. The next call to parse will not be incremental.

Signature:

def reset(self) -> None

Example:

instance.reset()

Returns: No return value.

---

Point

A source position — row + column, zero-indexed.

Field	Type	Default	Description
row	int	—	Zero-indexed row number.
column	int	—	Zero-indexed column, counted in bytes from the start of the row. This is tree_sitter.Point.column verbatim, and tree-sitter defines it as a byte offset — not characters, and not UTF-16 code units. Measured on a row of the form x = '<c>' where <c> is a single 4-byte character (an emoji), the string node reports columns 4..10, identical to its byte range; the character columns would be 4..7 and the UTF-16 columns 4..8. Anything that builds LSP positions (UTF-16) or editor caret columns (characters) from this field is silently wrong on every row containing a non-ASCII byte, and must re-measure the row against the source text instead. Earlier releases documented this field as UTF-16 code units; that was never what the value contained.

---

ProcessConfig

Configuration for the process() function.

Controls which analysis features are enabled and whether chunking is performed.

Field	Type	Default	Description
language	str	""	Language name (required).
structure	bool	True	Extract structural items (functions, classes, etc.). Default: true.
imports	bool	True	Extract import statements. Default: true.
exports	bool	True	Extract export statements. Default: true.
comments	bool	False	Extract comments. Default: false.
docstrings	bool	False	Extract docstrings. Default: false.
symbols	bool	False	Extract symbol definitions. Default: false.
diagnostics	bool	False	Include parse diagnostics. Default: false.
chunk_max_size	int | None	None	Maximum chunk size in bytes. None disables chunking. Some(0) is rejected by ProcessConfig.validate with Error.InvalidRange. A zero-sized chunk limit previously produced an empty chunk list and silently discarded the whole source; use None to mean “do not chunk”.
data_extraction	bool	False	Extract hierarchical key/value data tree from data-format files. Default: false. When True, ProcessResult.data is populated with a DataNode tree for supported languages: JSON, YAML, TOML, .properties, HCL/HOCON, INI, editorconfig, KDL, CUE, CSV, PSV, PO, nginx config, Caddy config, XML, and DTD. For languages outside this set the field is left as None.
max_source_bytes	int | None	None	Reject source longer than this many bytes instead of parsing it. Default: None (unbounded). Tree-sitter allocates and walks proportionally to input size, so an unbounded parse of attacker-supplied input is a denial-of-service vector. The default stays unbounded for backward compatibility; services handling untrusted input should opt in, e.g. with RECOMMENDED_MAX_SOURCE_BYTES. Exceeding the limit fails the call with Error.InvalidRange — the source is never silently truncated.
parse_timeout_ms	int | None	None	Wall-clock budget for the parse step, in milliseconds. Default: None (no timeout). Enforced through tree-sitter’s parse progress callback, which the parser invokes periodically; cancellation is therefore granular to that callback interval rather than exact. A parse that exceeds the budget fails with Error.ParseTimeout.

---

ProcessResult

Complete analysis result from processing a source file.

Contains metrics, structural analysis, imports/exports, comments, docstrings, symbols, diagnostics, and optionally chunked code segments. Fields are populated based on the ProcessConfig flags.

Field	Type	Default	Description
language	str	—	The language name used to parse the source file.
metrics	FileMetrics	—	File-level metrics (line counts, byte size, error count).
structure	list\[StructureItem\]	[]	Top-level structural items (functions, classes, etc.).
imports	list\[ImportInfo\]	[]	Import statements extracted from the source.
exports	list\[ExportInfo\]	[]	Export statements extracted from the source.
comments	list\[CommentInfo\]	[]	Comments extracted from the source.
docstrings	list\[DocstringInfo\]	[]	Docstrings extracted from the source.
symbols	list\[SymbolInfo\]	[]	Symbol definitions (variables, types, functions) extracted from the source.
diagnostics	list\[Diagnostic\]	[]	Parse diagnostics (syntax errors, missing nodes) from tree-sitter.
chunks	list\[CodeChunk\]	[]	Syntax-aware code chunks produced when chunking is enabled.
data	DataNode | None	None	Hierarchical data tree extracted when config.data_extraction is True. Populated for supported data-format languages (JSON, YAML, TOML, properties, HCL, INI, XML, CSV, and more). None when data_extraction is False (the default) or when the language is not a recognised data format. See DataNode for the shape of the returned tree.

---

Span

Byte and line/column range in source code.

Represents both byte offsets (for slicing) and human-readable line/column positions (for display and diagnostics).

Field	Type	Default	Description
start_byte	int	—	Inclusive start byte offset in the source.
end_byte	int	—	Exclusive end byte offset in the source.
start_line	int	—	Zero-indexed line number of the span’s start.
start_column	int	—	Zero-indexed column of the span’s start, counted in bytes from the start of the line — not characters, not UTF-16 code units.
end_line	int	—	Zero-indexed line number of the span’s end.
end_column	int	—	Zero-indexed column of the span’s end, counted in bytes from the start of the line — not characters, not UTF-16 code units.

---

StructureItem

A structural item (function, class, struct, etc.) in source code.

Field	Type	Default	Description
kind	StructureKind	StructureKind.FUNCTION	The kind of structural item.
name	str | None	None	The declared name of the item, if present.
visibility	str | None	None	Visibility modifier (e.g., "pub", "public", "private").
span	Span	—	Source span covering the entire item declaration.
children	list\[StructureItem\]	[]	Nested structural items (e.g., methods within a class).
decorators	list\[str\]	[]	Decorator or attribute names applied to the item. Reserved: not yet populated. Always empty, for every language. Recognising a decorator requires per-language grammar knowledge (a Python decorated_definition wrapper, Java/C# annotations, Rust attributes each have a different shape), which no extractor here implements yet. The field is kept rather than removed so a consumer’s deserializer does not need updating once it is.
doc_comment	str | None	None	Documentation comment attached to the item, if any. The text of the comment (or run of comments) immediately preceding the item, with no blank line in between, when that comment is classified as a doc comment. Multiple adjacent single-line doc comments (Rust ///) are joined with \n in source order. Populated for Rust (//////!), Java (/** */), and JavaScript/ TypeScript (/** */). None for every other language, and for a preceding comment that is not in doc-comment form (a plain # comment in Python, Ruby, or Elixir) — Python’s docstring convention is captured separately, as DocstringInfo, not through this field.
signature	str | None	None	Full signature text of the item (e.g., function parameters and return type). The item’s own source text from its start up to the start of its body (see StructureItem.body_span), trimmed of trailing whitespace — for example fn add(a: i32, b: i32) -> i32 for a Rust function whose body is { a + b }. None only when that text is empty, which does not happen for any item StructureKind currently reports. Populated for every language and kind this library extracts structure for, since it is derived from body_span’s boundary rather than per-language syntax.
body_span	Span | None	None	Source span covering only the body of the item, if distinct from the declaration.

---

SymbolInfo

A symbol (variable, function, type, etc.) extracted from source code.

Field	Type	Default	Description
name	str	—	The name of the symbol.
kind	SymbolKind	SymbolKind.VARIABLE	The kind of symbol (variable, function, class, etc.).
span	Span	—	Source span covering the symbol definition.
type_annotation	str | None	None	Explicit type annotation, if present in the source.
doc	str | None	None	Documentation comment immediately preceding this symbol, resolved by the same walk StructureItem.doc_comment uses (see doc_comment_at) — never hard-coded None. Populated for Rust (//////!), Java (/** */), and JavaScript/ TypeScript (/** */) — the languages whose comment classification recognizes a doc-kind comment. None for every other language (e.g. Python, Go, Ruby, which have no doc-kind comment classification), and also None when a symbol in a supported language simply has no doc comment immediately above it.

---

Tree

A parsed syntax tree. Cheap to clone (refcount bump).

Methods

root_node()

Return the root Node of this tree.

Signature:

def root_node(self) -> Node

Example:

result = instance.root_node()

Returns: Node

walk()

Return a TreeCursor positioned at the root.

Signature:

def walk(self) -> TreeCursor

Example:

result = instance.walk()

Returns: TreeCursor

---

TreeCursor

A cursor for traversing a Tree.

Methods

node()

Return the Node at the cursor’s current position.

Signature:

def node(self) -> Node

Example:

result = instance.node()

Returns: Node

goto_first_child()

Move the cursor to the first child of the current node. Returns True if a child existed.

Signature:

def goto_first_child(self) -> bool

Example:

result = instance.goto_first_child()

Returns: bool

goto_parent()

Move the cursor to the parent of the current node. Returns True if a parent existed.

Signature:

def goto_parent(self) -> bool

Example:

result = instance.goto_parent()

Returns: bool

goto_next_sibling()

Move the cursor to the next sibling of the current node. Returns True if a sibling existed.

Signature:

def goto_next_sibling(self) -> bool

Example:

result = instance.goto_next_sibling()

Returns: bool

field_name()

Return the field name for the current node, if any.

Signature:

def field_name(self) -> str | None

Example:

result = instance.field_name()

Returns: str | None

---

Enums

DataNodeKind

The kind of a data node extracted from a data-format file.

Classifies each node in the hierarchical DataNode tree returned when data_extraction is enabled on ProcessConfig.

Wire format (public JSON contract)

Unit variants serialize as a bare string ("KeyValue"). DO NOT add #[serde(tag = "...")] or rename variants — every language binding has a hand-written deserializer matching this exact shape, and any change breaks all bindings’ process() tests simultaneously. Covered by tests/wire_format.rs.

Value	Description
KEY_VALUE	A key/value pair or mapping (json/toml/properties/yaml/hcl/cue/kdl pair, or a wrapper “object”/“mapping” container).
ELEMENT	An XML element with a tag name in key and attributes in attributes.
SEQUENCE	A positional sequence item (JSON array element, YAML block sequence item, CSV/PSV row or cell).

---

StructureKind

The kind of structural item found in source code.

Categorizes top-level and nested declarations such as functions, classes, structs, enums, traits, and more. Use Other for language-specific constructs that do not fit a standard category.

Wire format (public JSON contract)

Unit variants serialize as a bare string ("Function"); the Other variant serializes as a single-keyed object ({"Other": "macro"}). DO NOT add #[serde(tag = "...")] or rename variants — every language binding has a hand-written deserializer matching this exact shape, and any change breaks all bindings’ process() tests simultaneously. Covered by tests/wire_format.rs.

Value	Description
FUNCTION	A free-standing or associated function.
METHOD	A method defined inside a class, struct, trait, or impl block.
CLASS	A class definition.
STRUCT	A struct definition.
INTERFACE	An interface or protocol definition.
ENUM	An enum definition.
MODULE	A module or package declaration.
TRAIT	A trait definition.
IMPL	An impl block (Rust) or similar implementation block.
NAMESPACE	A namespace declaration.
OTHER	A language-specific construct that does not fit any standard category. — Fields: 0: str

---

CommentKind

The kind of a comment found in source code.

Distinguishes between single-line comments, block (multi-line) comments, and documentation comments.

Value	Description
LINE	A single-line comment (e.g., // ... or # ...).
BLOCK	A block or multi-line comment using slash-star delimiters.
DOC	A documentation comment such as /// ... or slash-double-star block.

---

DocstringFormat

The format of a docstring extracted from source code.

Identifies the docstring convention used, which varies by language (e.g., Python triple-quoted strings, JSDoc, Rustdoc /// comments).

Wire format (public JSON contract)

Unit variants serialize as a bare string ("JSDoc"); the Other variant serializes as a single-keyed object ({"Other": "rst"}). DO NOT add #[serde(tag = "...")]. Covered by tests/wire_format.rs.

Value	Description
PYTHON_TRIPLE_QUOTE	Python triple-quoted string docstring ("""...""").
JS_DOC	JavaScript/TypeScript JSDoc block comment (opens with two stars, closes with star-slash).
RUSTDOC	Rust /// or //! doc comment.
GO_DOC	Go doc comment (a comment block immediately preceding a declaration).
JAVA_DOC	Java Javadoc block comment (opens with two stars, closes with star-slash).
OTHER	A language-specific docstring format not covered by the standard variants. — Fields: 0: str

---

ExportKind

The kind of an export statement found in source code.

Covers named exports, default exports, and re-exports from other modules.

Value	Description
NAMED	A named export (e.g., export { foo }).
DEFAULT	A default export (e.g., export default foo).
RE_EXPORT	A re-export from another module (e.g., export { foo } from 'bar').

---

SymbolKind

The kind of a symbol definition found in source code.

Categorizes symbol definitions such as variables, constants, functions, classes, types, interfaces, enums, and modules.

Wire format (public JSON contract)

Unit variants serialize as a bare string ("Function"); the Other variant serializes as a single-keyed object ({"Other": "macro"}). DO NOT add #[serde(tag = "...")]. Covered by tests/wire_format.rs.

Value	Description
VARIABLE	A variable binding.
CONSTANT	A constant (immutable binding).
FUNCTION	A function definition.
CLASS	A class definition.
TYPE	A type alias or typedef.
INTERFACE	An interface definition.
ENUM	An enum definition.
MODULE	A module declaration.
OTHER	A symbol kind not covered by the standard variants. — Fields: 0: str

---

DiagnosticSeverity

Severity level of a diagnostic produced during parsing.

Used to classify parse errors, warnings, and informational messages found in the syntax tree.

Value	Description
ERROR	A parse error (e.g., an ERROR or MISSING node in the tree).
WARNING	A warning-level diagnostic.
INFO	An informational diagnostic.

---

Errors

Error

Errors that can occur when using the tree-sitter language pack.

Covers language lookup failures, parse errors, query errors, and I/O issues. Feature-gated variants are included when config, download, or related features are enabled.

Matching on Error

The set of variants is not stable: new failure modes are added in minor releases, and Io, Json, and Toml exist only under certain feature combinations, so the variant set a downstream crate sees depends on which features it enables. Downstream matches must therefore carry a _ arm; #[non_exhaustive] makes the compiler enforce that instead of letting a feature change silently break a build.

C ABI error codes

Each variant alef can see carries an explicit alef(error_code = N) allocation that becomes a member of the generated AlefFfiErrorCode C enum. These numbers are a public ABI contract: an allocated number is never reused after its variant is removed, and a variant’s number never changes, because C callers compare against the value, not the name. New variants take the next free number. 0-4 are reserved by alef, so allocation starts at 100. An unannotated variant is emitted as the unknown code rather than as itself, which silently flattens the taxonomy — annotate every new variant.

Base class: Error(Exception)

Exception	Description
LanguageNotFoundError(Error)	The requested language name (or alias) was not found in the registry.
DynamicLoadError(Error)	A dynamic shared library could not be loaded at runtime.
NullLanguagePointerError(Error)	The tree-sitter language function returned a null pointer for the given language name.
ParserSetupError(Error)	The language could not be applied to the parser (e.g., ABI version mismatch).
LockPoisonedError(Error)	An internal RwLock or Mutex was poisoned by a previous panic.
ConfigError(Error)	A configuration file or value was invalid or could not be applied.
ParseFailedError(Error)	The tree-sitter parser returned no tree for the given source input.
ParseTimeoutError(Error)	The parse was cancelled because it exceeded its configured wall-clock budget. Raised only when a budget is configured — see ProcessConfig.parse_timeout_ms, which defaults to None.
QueryError(Error)	A tree-sitter query could not be compiled or executed.
InvalidRangeError(Error)	A byte range was invalid (e.g., end before start, or out of bounds).
DownloadError(Error)	A parser download from GitHub releases failed.
ChecksumMismatchError(Error)	The downloaded file’s SHA-256 digest did not match the manifest’s expected value.
CacheLockError(Error)	The cross-process download cache lock file could not be acquired or created.

---