Skip to content

Editor Integration (t-linter)

t-linter is a linter, formatter, and LSP server for Python template strings (PEP 750 t-strings). It uses the same Rust backends (tstring-json, tstring-toml, tstring-yaml) as this project for check and format operations.

Installation

pip install t-linter

Or with uv:

uv add t-linter

CLI usage

Check templates for errors

Validate t-string templates in your Python files:

t-linter check file.py
t-linter check src/

Output format options:

t-linter check file.py --format human    # default, human-readable
t-linter check file.py --format json     # machine-readable JSON
t-linter check file.py --format github   # GitHub Actions annotations

Use --error-on-issues to fail CI when problems are found:

t-linter check src/ --error-on-issues

Format templates

Canonical formatting for JSON, YAML, and TOML template literals:

t-linter format file.py
t-linter format src/

Dry-run to see what would change without modifying files:

t-linter format --check file.py

Read from stdin:

cat file.py | t-linter format --stdin-filename file.py -

LSP server

Start the built-in LSP server for real-time editor diagnostics and formatting:

t-linter lsp

The LSP provides:

  • Diagnostics — syntax and semantic errors reported inline as you type
  • Formatting — format-on-save or format-on-demand via your editor's formatting command

VSCode integration

  1. Install the binary:

    pip install t-linter

  2. Install the t-linter extension from the VSCode marketplace.

  3. Recommended: set "python.languageServer": "None" in VSCode settings to avoid conflicts with other Python language servers.

  4. Optionally configure t-linter.serverPath in settings if the binary is not on your PATH.

Other editors

Any editor that supports the Language Server Protocol can use t-linter lsp. Configure your editor to start t-linter lsp as the language server for Python files.

Configuration

Configure t-linter via pyproject.toml:

[tool.t-linter]
extend-exclude = ["generated", "vendor"]
ignore-file = ".t-linterignore"

Language detection

t-linter identifies structured-data templates from PEP 593 Annotated metadata on string.templatelib.Template:

from string.templatelib import Template
from typing import Annotated

payload: Annotated[Template, "json"] = t'{"name": {name}}'
config: Annotated[Template, "toml"] = t"name = {name}"
manifest: Annotated[Template, "yaml"] = t"name: {name}"

The wrapper packages export aliases for the same convention:

from json_tstring import JsonTemplate, render_data as render_json
from toml_tstring import TomlTemplate, render_data as render_toml
from yaml_tstring import YamlTemplate, render_data as render_yaml

payload: JsonTemplate = t'{"name": {name}}'
config: TomlTemplate = t"name = {name}"
manifest: YamlTemplate = t"name: {name}"

json_data = render_json(payload)
toml_data = render_toml(config)
yaml_data = render_yaml(manifest)

For this project, t-linter recognizes the metadata tags json, toml, yaml, and yml. The aliases above use the canonical json, toml, and yaml tags.

How it works with tstring-structured-data

t-linter and tstring-structured-data share the same Rust parsing and formatting backends:

  • tstring-structured-data is the runtime library — render_data() and render_text() parse and render templates at runtime
  • t-linter is the developer tooling — check validates templates and format canonicalizes them at development time

For JSON, YAML, and TOML templates, t-linter uses:

  • Tree-sitter for fast syntax highlighting (low-latency, no full parse)
  • Rust backends (tstring-json, tstring-yaml, tstring-toml) for strict check and format operations