1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
|
[]: Copyright (c) 2017-2026 Juancarlo Añez (apalala@gmail.com)
[]: SPDX-License-Identifier: BSD-4-Clause
[]: by Gemini 2026-02-15
# TatSu Development Style Guide
This document defines the coding standards for the TatSu project, specifically for task automation and core Python development. These rules ensure consistency, type safety, and a professional terminal experience.
## 1. String Quoting
* **Primary Standard:** Use `'single quotes'` for all strings, including UI messages, shell commands, and identifiers.
* **Secondary Standard:** Use `"double quotes"` only when necessary to avoid escaping internal single quotes (e.g., `'It's a test'` becomes `"It's a test"`) or within complex f-string expressions.
## 2. Path Management (`pathlib`)
* **Strict Usage:** Never use `os.path`. Use `pathlib.Path` for all filesystem interactions.
* **Traversal:** Use `Path.rglob()` for recursive searches and cleanups.
* **Type Safety:** Maintain paths as `Path` objects as long as possible before converting to `str` for shell execution.
## 3. Type Annotations & Static Analysis
* **Explicit Typing:** Annotate all top-level constants and function parameters.
* **Modern Aliases:** Use the `type` keyword (Python 3.12+) for complex type definitions.
* **Return Types:** * Functions with side effects should be explicitly annotated with `-> None`.
* **Linter Overrides:** When a linter (like Ruff) conflicts with functional intent, use pragmatic workarounds (e.g., the `math.pi` rounding hack) and silence the specific warning with an inline `# pyright:ignore` or `# noqa`.
## 4. Task Orchestration (Invoke & UV)
* **Execution Wrappers:** All system calls must be wrapped in a helper (like `uv()`) that manages quiet modes, python versions, and dependency groups.
* **State Management:** Critical tasks (`matrix`, `all`) must ensure environment synchronization using `uv_sync()`.
* **Dependencies:** Use the `pre` argument in `@task` to build a robust, ordered execution graph.
## 5. Terminal User Interface (UX)
* **Visual Hierarchy:** Use box-drawing characters for boundaries.
* **Constants:**
* `THIN_LINE = '─'`
* `THICK_LINE = '━'`
* **Adaptive Width:** UI elements must dynamically adapt to the terminal width using `shutil.get_terminal_size()`.
* **Visual Cues:** Use emojis (`✅`, `✨`, `🐍`) to mark success and major categories.
## 6. Documentation & Comments
* **Rationale over Description:** Comments should explain *why* a certain path was taken (the "Engineering Rationale") rather than *what* the code is doing.
* **Provenance:** Maintain headers with proper copyright and attribution for significant logic changes.
|
