Skip to content

Commit 22419d9

Browse files
koxudaxikoxudaxi
authored
Merge pull request #27 from koxudaxi/docs/add-t-linter-integration
docs: add t-linter integration guide
2 parents 4862105 + b227502 commit 22419d9

6 files changed

Lines changed: 268 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,36 @@ text = render_text(template)
105105
JSON and TOML work the same way — `json_tstring.render_data()`,
106106
`toml_tstring.render_text()`, etc.
107107

108+
## Editor integration (t-linter)
109+
110+
[t-linter](https://github.com/koxudaxi/t-linter) is a linter, formatter, and
111+
LSP server for t-strings. It uses the same Rust backends as this project for
112+
`check` and `format`.
113+
114+
```bash
115+
pip install t-linter
116+
```
117+
118+
Check templates for errors:
119+
120+
```bash
121+
t-linter check src/
122+
```
123+
124+
Format JSON / TOML / YAML template literals:
125+
126+
```bash
127+
t-linter format src/
128+
```
129+
130+
Start the LSP server for real-time editor diagnostics:
131+
132+
```bash
133+
t-linter lsp
134+
```
135+
136+
A [VSCode extension](https://marketplace.visualstudio.com/items?itemName=koxudaxi.t-linter) is also available.
137+
108138
## Rust backend API
109139

110140
The Rust crates also expose parser-first `check` and `format` entry points for
@@ -195,3 +225,4 @@ when a version tag is pushed.
195225
- [PEP 750 – Template Strings](https://peps.python.org/pep-0750/)
196226
- [`string.templatelib` — Template String Support](https://docs.python.org/3/library/string.templatelib.html)
197227
- [What's New In Python 3.14](https://docs.python.org/3/whatsnew/3.14.html)
228+
- [t-linter](https://github.com/koxudaxi/t-linter) — Linter, formatter, and LSP for t-strings

‎docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,4 +73,5 @@ Pick the format you need:
7373

7474
- [Installation](getting-started/installation.md)
7575
- [Quick Start](getting-started/quick-start.md)
76+
- [Editor Integration (t-linter)](usage/editor-integration.md)
7677
- [Architecture](architecture.md)

‎docs/llms-full.txt‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@ Pick the format you need:
7575

7676
- [Installation](getting-started/installation.md)
7777
- [Quick Start](getting-started/quick-start.md)
78+
- [Editor Integration (t-linter)](usage/editor-integration.md)
7879
- [Architecture](architecture.md)
7980

8081
---
@@ -604,6 +605,125 @@ Each profile's conformance claims are backed by per-profile manifests and test s
604605

605606
---
606607

608+
# Editor Integration (t-linter)
609+
610+
Source: https://tstring-structured-data.koxudaxi.dev/usage/editor-integration/
611+
612+
[t-linter](https://github.com/koxudaxi/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.
613+
614+
## Installation
615+
616+
```bash
617+
pip install t-linter
618+
```
619+
620+
Or with uv:
621+
622+
```bash
623+
uv add t-linter
624+
```
625+
626+
## CLI usage
627+
628+
### Check templates for errors
629+
630+
Validate t-string templates in your Python files:
631+
632+
```bash
633+
t-linter check file.py
634+
t-linter check src/
635+
```
636+
637+
Output format options:
638+
639+
```bash
640+
t-linter check file.py --format human # default, human-readable
641+
t-linter check file.py --format json # machine-readable JSON
642+
t-linter check file.py --format github # GitHub Actions annotations
643+
```
644+
645+
Use `--error-on-issues` to fail CI when problems are found:
646+
647+
```bash
648+
t-linter check src/ --error-on-issues
649+
```
650+
651+
### Format templates
652+
653+
Canonical formatting for JSON, YAML, and TOML template literals:
654+
655+
```bash
656+
t-linter format file.py
657+
t-linter format src/
658+
```
659+
660+
Dry-run to see what would change without modifying files:
661+
662+
```bash
663+
t-linter format --check file.py
664+
```
665+
666+
Read from stdin:
667+
668+
```bash
669+
cat file.py | t-linter format --stdin-filename file.py -
670+
```
671+
672+
## LSP server
673+
674+
Start the built-in LSP server for real-time editor diagnostics and formatting:
675+
676+
```bash
677+
t-linter lsp
678+
```
679+
680+
The LSP provides:
681+
682+
- **Diagnostics** — syntax and semantic errors reported inline as you type
683+
- **Formatting** — format-on-save or format-on-demand via your editor's formatting command
684+
685+
## VSCode integration
686+
687+
1. Install the binary:
688+
689+
```bash
690+
pip install t-linter
691+
```
692+
693+
2. Install the [t-linter extension](https://marketplace.visualstudio.com/items?itemName=koxudaxi.t-linter) from the VSCode marketplace.
694+
695+
3. Recommended: set `"python.languageServer": "None"` in VSCode settings to avoid conflicts with other Python language servers.
696+
697+
4. Optionally configure `t-linter.serverPath` in settings if the binary is not on your `PATH`.
698+
699+
## Other editors
700+
701+
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.
702+
703+
## Configuration
704+
705+
Configure t-linter via `pyproject.toml`:
706+
707+
```toml
708+
[tool.t-linter]
709+
extend-exclude = ["generated", "vendor"]
710+
ignore-file = ".t-linterignore"
711+
```
712+
713+
## How it works with tstring-structured-data
714+
715+
t-linter and tstring-structured-data share the same Rust parsing and formatting backends:
716+
717+
- **tstring-structured-data** is the **runtime library** — `render_data()` and `render_text()` parse and render templates at runtime
718+
- **t-linter** is the **developer tooling** — `check` validates templates and `format` canonicalizes them at development time
719+
720+
For JSON, YAML, and TOML templates, t-linter uses:
721+
722+
- **Tree-sitter** for fast syntax highlighting (low-latency, no full parse)
723+
- **Rust backends** (`tstring-json`, `tstring-yaml`, `tstring-toml`) for strict `check` and `format` operations
724+
725+
---
726+
607727
# Architecture
608728

609729
Source: https://tstring-structured-data.koxudaxi.dev/architecture/

‎docs/llms.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
- [YAML](https://tstring-structured-data.koxudaxi.dev/usage/yaml/): The `yaml-tstring` package provides `render_data`, `render_text`, and `render_result` for YAML templates.
1616
- [Error Handling](https://tstring-structured-data.koxudaxi.dev/usage/error-handling/): T-string backends catch errors that f-strings silently ignore and block injection by construction.
1717
- [Profiles](https://tstring-structured-data.koxudaxi.dev/usage/profiles/): Each backend accepts an optional `profile` keyword argument to select the target spec version.
18+
- [Editor Integration (t-linter)](https://tstring-structured-data.koxudaxi.dev/usage/editor-integration/): [t-linter](https://github.com/koxudaxi/t-linter) is a linter, formatter, and LSP server for Python template strings (PEP 750 t-strings). It uses th...
1819

1920
- [Architecture](https://tstring-structured-data.koxudaxi.dev/architecture/)
2021
## Reference

‎docs/usage/editor-integration.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Editor Integration (t-linter)
2+
3+
[t-linter](https://github.com/koxudaxi/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.
4+
5+
## Installation
6+
7+
```bash
8+
pip install t-linter
9+
```
10+
11+
Or with uv:
12+
13+
```bash
14+
uv add t-linter
15+
```
16+
17+
## CLI usage
18+
19+
### Check templates for errors
20+
21+
Validate t-string templates in your Python files:
22+
23+
```bash
24+
t-linter check file.py
25+
t-linter check src/
26+
```
27+
28+
Output format options:
29+
30+
```bash
31+
t-linter check file.py --format human # default, human-readable
32+
t-linter check file.py --format json # machine-readable JSON
33+
t-linter check file.py --format github # GitHub Actions annotations
34+
```
35+
36+
Use `--error-on-issues` to fail CI when problems are found:
37+
38+
```bash
39+
t-linter check src/ --error-on-issues
40+
```
41+
42+
### Format templates
43+
44+
Canonical formatting for JSON, YAML, and TOML template literals:
45+
46+
```bash
47+
t-linter format file.py
48+
t-linter format src/
49+
```
50+
51+
Dry-run to see what would change without modifying files:
52+
53+
```bash
54+
t-linter format --check file.py
55+
```
56+
57+
Read from stdin:
58+
59+
```bash
60+
cat file.py | t-linter format --stdin-filename file.py -
61+
```
62+
63+
## LSP server
64+
65+
Start the built-in LSP server for real-time editor diagnostics and formatting:
66+
67+
```bash
68+
t-linter lsp
69+
```
70+
71+
The LSP provides:
72+
73+
- **Diagnostics** — syntax and semantic errors reported inline as you type
74+
- **Formatting** — format-on-save or format-on-demand via your editor's formatting command
75+
76+
## VSCode integration
77+
78+
1. Install the binary:
79+
80+
```bash
81+
pip install t-linter
82+
```
83+
84+
2. Install the [t-linter extension](https://marketplace.visualstudio.com/items?itemName=koxudaxi.t-linter) from the VSCode marketplace.
85+
86+
3. Recommended: set `"python.languageServer": "None"` in VSCode settings to avoid conflicts with other Python language servers.
87+
88+
4. Optionally configure `t-linter.serverPath` in settings if the binary is not on your `PATH`.
89+
90+
## Other editors
91+
92+
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.
93+
94+
## Configuration
95+
96+
Configure t-linter via `pyproject.toml`:
97+
98+
```toml
99+
[tool.t-linter]
100+
extend-exclude = ["generated", "vendor"]
101+
ignore-file = ".t-linterignore"
102+
```
103+
104+
## How it works with tstring-structured-data
105+
106+
t-linter and tstring-structured-data share the same Rust parsing and formatting backends:
107+
108+
- **tstring-structured-data** is the **runtime library** — `render_data()` and `render_text()` parse and render templates at runtime
109+
- **t-linter** is the **developer tooling** — `check` validates templates and `format` canonicalizes them at development time
110+
111+
For JSON, YAML, and TOML templates, t-linter uses:
112+
113+
- **Tree-sitter** for fast syntax highlighting (low-latency, no full parse)
114+
- **Rust backends** (`tstring-json`, `tstring-yaml`, `tstring-toml`) for strict `check` and `format` operations

‎zensical.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ nav = [
1717
{ "YAML" = "usage/yaml.md" },
1818
{ "Error Handling" = "usage/error-handling.md" },
1919
{ "Profiles" = "usage/profiles.md" },
20+
{ "Editor Integration (t-linter)" = "usage/editor-integration.md" },
2021
]},
2122
{ "Architecture" = "architecture.md" },
2223
{ "Reference" = [

0 commit comments

Comments
 (0)