{"id":4815,"library":"tree-sitter-toml","title":"TOML Grammar for Tree-sitter in Python","description":"tree-sitter-toml provides a TOML grammar for the Tree-sitter parsing library, with Python bindings and pre-compiled wheels. It enables efficient, incremental parsing of TOML files, generating concrete syntax trees for various programming tools. The library is currently at version 0.7.0 and is actively maintained within the Tree-sitter grammars ecosystem.","status":"active","version":"0.7.0","language":"en","source_language":"en","source_url":"https://github.com/tree-sitter-grammars/tree-sitter-toml","tags":["toml","parsing","tree-sitter","grammar","ast"],"install":[{"cmd":"pip install tree-sitter-toml tree-sitter","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Provides the core Tree-sitter parsing engine and Python bindings, essential for loading and using the TOML grammar.","package":"tree-sitter","optional":false}],"imports":[{"note":"The `language()` function is a module-level function within `tree_sitter_toml` that returns the compiled language object, which must then be wrapped by `tree_sitter.Language`.","wrong":"from tree_sitter_toml import Language; TOML_LANGUAGE = Language()","symbol":"language","correct":"import tree_sitter_toml\nfrom tree_sitter import Language, Parser\n\nTOML_LANGUAGE = Language(tree_sitter_toml.language())"}],"quickstart":{"code":"import tree_sitter_toml\nfrom tree_sitter import Language, Parser\n\n# Load the TOML grammar\nTOML_LANGUAGE = Language(tree_sitter_toml.language())\n\n# Create a parser instance\nparser = Parser()\nparser.set_language(TOML_LANGUAGE)\n\n# Sample TOML source code\ntoml_code = b'''\n[package]\nname = \"my-app\"\nversion = \"0.1.0\"\nauthors = [\"John Doe <john@example.com>\"]\n'''\n\n# Parse the code\ntree = parser.parse(toml_code)\n\n# Get the root node and print its type\nroot_node = tree.root_node\nprint(f\"Root Node Type: {root_node.type}\")\n\n# Example: Find a 'name' key-value pair\ndef find_name(node):\n    for child in node.children:\n        if child.type == 'key_value_pair':\n            if child.child_by_field_name('key') and child.child_by_field_name('key').text == b'name':\n                print(f\"Found name: {child.child_by_field_name('value').text.decode()}\")\n        find_name(child)\n\nfind_name(root_node)","lang":"python","description":"This quickstart demonstrates how to initialize the Tree-sitter parser with the `tree-sitter-toml` grammar and parse a simple TOML string. It then walks the resulting syntax tree to find and print the value associated with the 'name' key."},"warnings":[{"fix":"Ensure `tree-sitter` and `tree-sitter-toml` packages are compatible. If `tree-sitter` is updated to a new major version, check for a corresponding `tree-sitter-toml` update. Reinstalling both might be necessary.","message":"The underlying `tree-sitter` core library (which `py-tree-sitter` binds to) may introduce breaking changes, particularly with its Application Binary Interface (ABI). A major ABI version bump in `tree-sitter` can render `tree-sitter-toml` incompatible until it's updated and recompiled for the new ABI, potentially leading to `Language` loading failures.","severity":"breaking","affected_versions":"All versions, depends on `tree-sitter` core/bindings version"},{"fix":"After updating `tree-sitter-toml`, review and test any custom Tree-sitter queries. Consult the grammar's repository for changes to node types or structure if queries fail unexpectedly.","message":"Changes to the `tree-sitter-toml` grammar definition, even minor ones, can alter the structure of the generated syntax tree. Existing Tree-sitter queries (used for pattern matching or navigation) written against an older grammar structure might become invalid or return incorrect results.","severity":"gotcha","affected_versions":"All versions, especially across `tree-sitter-toml` minor/major updates"},{"fix":"Always encode your TOML source code string to bytes, e.g., `toml_code.encode('utf8')`, before passing it to `parser.parse()`.","message":"The `parser.parse()` method of `tree-sitter` strictly requires the input source code to be a `bytes` object, usually UTF-8 encoded. Passing a standard Python string or an incorrectly encoded byte string will lead to a `TypeError` or parsing errors.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}