Tombi: TOML Language Server & Toolkit

0.9.18 · active · verified Thu Apr 16

tombi (version 0.9.18) is a comprehensive TOML Language Server and toolkit designed to provide rich editor features like auto-completion, validation, and navigation for TOML files. It focuses particularly on project configuration files such as `pyproject.toml` and `Cargo.toml`. The project is actively maintained with frequent minor releases addressing features, fixes, and dependency updates.

Common errors

```
ModuleNotFoundError: No module named 'tombi.parse'
```
cause Attempting to use `tombi` for direct programmatic TOML parsing via an assumed `parse` function, which does not exist in its public API.

fix Use a dedicated Python TOML parsing library instead. For Python 3.11+, use `import tomllib`. For older Python versions, install `tomli` or `toml` (`pip install tomli`) and use `import tomli`.
```
LSP client failed to connect to 'tombi' server. (or similar editor-specific LSP connection error)
```
cause The `tombi` executable is not found in the system's PATH, or the editor's LSP client is misconfigured regarding the `tombi` server path.

fix Ensure `tombi` is installed in an environment accessible by your editor's LSP client (e.g., `pip install tombi` in the activated virtual environment or globally). Verify your editor's LSP client configuration points to the correct `python -m tombi` command or the `tombi` executable.

Warnings

breaking As of v0.9.18, the default settings for DocumentLink have changed. Only `crates.io` and `pypi.org` links are enabled by default for cargo.toml and pyproject.toml files.
Fix: If you rely on document links for git, path, or workspace dependencies, you must explicitly enable them in your `tombi` configuration (e.g., within your editor's LSP client settings or `tombi.toml`).
gotcha `tombi` is primarily a Language Server Protocol (LSP) server and a command-line toolkit. It is *not* intended to be imported as a Python library for programmatic parsing or manipulation of TOML data within your applications.
Fix: For parsing and manipulating TOML files in your Python code, use standard libraries like `tomllib` (built-in from Python 3.11) or third-party libraries like `toml` or `tomli`.
gotcha Simply installing `tombi` with pip will not activate its features in your editor. `tombi` requires configuration within your editor's Language Server Protocol (LSP) client to provide rich editing capabilities.
Fix: Consult your editor's documentation for integrating LSP servers (e.g., `vscode-toml`, `nvim-lspconfig`, `helix` `languages.toml` settings) and ensure `tombi` is specified as the TOML language server. This typically involves setting the correct command path for `tombi`.

Install

pip install tombi Install latest version

Quickstart

This quickstart demonstrates how to programmatically start `tombi` as an LSP server. Most users will integrate `tombi` directly with their editor's LSP client (e.g., VS Code, NeoVim, Helix), which handles the server startup and communication automatically. Direct programmatic use for TOML *data manipulation* is not `tombi`'s primary function; for that, use dedicated TOML parsing libraries.

import subprocess
import time
import os

# This demonstrates how to start tombi as a language server process.
# In a real editor setup, your IDE would automatically handle this
# and communicate via the Language Server Protocol (LSP).

# Note: tombi is primarily an LSP server/CLI tool, not a library for
# direct programmatic TOML parsing in Python applications.
# For programmatic TOML parsing, use `tomllib` (Python 3.11+) or `toml`/`tomli`.

# Example: Start the tombi LSP server for standard I/O communication
print("Starting tombi LSP server using --stdio...")
try:
    process = subprocess.Popen(
        ['python', '-m', 'tombi', '--stdio'],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True, # For text-mode communication (JSON-RPC over stdio)
        bufsize=1  # Line-buffered output for real-time communication
    )

    print("tombi LSP server started. In a real scenario, an LSP client (editor)")
    print("would now send JSON-RPC messages to stdin and read responses from stdout.")
    
    # Simulate some operational time
    time.sleep(2)
    
    print("Simulating a short run, now terminating the LSP server process.")
    process.terminate() # Attempt graceful termination
    process.wait(timeout=5) # Wait for the process to exit

    print(f"LSP server exited with return code: {process.returncode}")
    
    # Check for any error output from the server
    stderr_output = process.stderr.read()
    if stderr_output:
        print("\n--- stderr output from tombi LSP during startup/shutdown ---")
        print(stderr_output)
        print("-----------------------------------------------------------\n")

except FileNotFoundError:
    print("Error: 'tombi' command not found. Ensure tombi is installed and in PATH.")
    print("Try: pip install tombi")
except Exception as e:
    print(f"An error occurred while trying to run tombi: {e}")

view raw JSON →