87 lines
4.0 KiB
Markdown
87 lines
4.0 KiB
Markdown
# AI-Optimized Python Style Guide
|
|
|
|
This document defines the Python style conventions for the Manual Slop codebase.
|
|
These deviate from PEP 8 / Google style to minimize token consumption when code
|
|
is processed by AI agents, while preserving readability for human review.
|
|
|
|
## 1. Indentation and Whitespace
|
|
|
|
- **Indentation:** 1 space per level. No tabs.
|
|
- **Continuation lines:** 1 space relative to the opening construct.
|
|
- **Blank lines:** Zero blank lines between function/method definitions within a class. One blank line between top-level definitions only when separating logically distinct sections.
|
|
- **Trailing whitespace:** None.
|
|
- **Rationale:** 1-space indentation reduces token count by ~40% compared to 4-space on deeply nested GUI code, with no loss of structural clarity for AST-based tools.
|
|
|
|
## 2. Type Annotations
|
|
|
|
- **All functions and methods** must have return type annotations.
|
|
- **All parameters** (except `self`/`cls`) must have type annotations.
|
|
- **Module-level and class-level variables** must have type annotations.
|
|
- **Use modern syntax:** `list[str]`, `dict[str, Any]`, `X | None` over `Optional[X]` where Python 3.10+ is available. Use `from __future__ import annotations` if needed.
|
|
- **Callable:** Use bare `Callable` for callback factories. Use `Callable[[ArgTypes], ReturnType]` when the signature is known and stable.
|
|
- **DearPyGui / ImGui callbacks:** Use `sender: Any, app_data: Any` for framework callbacks where the types are runtime-determined.
|
|
|
|
## 3. Imports
|
|
|
|
- Use `from __future__ import annotations` at the top of every module.
|
|
- Group imports: stdlib, third-party, local — separated by a blank line.
|
|
- Use `from typing import Any, Optional, Callable` etc. for type-only imports.
|
|
- Prefer `from x import Y` for specific symbols over `import x` when only one or two names are used.
|
|
|
|
## 4. Naming
|
|
|
|
- **snake_case** for modules, functions, methods, variables.
|
|
- **PascalCase** for classes.
|
|
- **ALL_CAPS** for module-level constants.
|
|
- **Single leading underscore** (`_name`) for internal/private members.
|
|
|
|
## 5. Docstrings
|
|
|
|
- Required on classes and non-trivial public functions.
|
|
- Use `"""triple double quotes"""`.
|
|
- One-line summary is sufficient for simple methods.
|
|
- Omit docstrings on obvious internal methods (e.g., `_cb_*` callbacks, `_render_*` UI methods) where the name is self-documenting.
|
|
|
|
## 6. String Formatting
|
|
- Prefer f-strings.
|
|
- Use double quotes (`"`) for strings by default.
|
|
- Use single quotes when the string contains double quotes.
|
|
|
|
## 7. Error Handling
|
|
- Never use bare `except:`.
|
|
- Use specific exception types.
|
|
- Prefer `if x is None:` over `if not x:` when testing for None specifically.
|
|
|
|
## 8. AI-Agent Specific Conventions
|
|
|
|
- **No redundant comments.** Do not add comments that restate what the code does. Only comment on *why* when non-obvious.
|
|
- **No empty `__init__.py` files.**
|
|
- **Minimal blank lines.** Token-efficient density is preferred over visual padding.
|
|
- **Short variable names are acceptable** in tight scopes (loop vars, lambdas). Use descriptive names for module-level and class attributes.
|
|
|
|
## 9. Line Length
|
|
|
|
- Soft limit: 120 characters.
|
|
- Hard limit: None — let the formatter handle wrapping if needed.
|
|
- Rationale: 80-char limits cause excessive line continuations that waste tokens.
|
|
|
|
## 11. Structural Dependency Mapping (SDM)
|
|
|
|
To assist AI agents in evaluating refactoring impact across dynamic codebases, all major definitions SHOULD include terse SDM tags at the end of their docstrings.
|
|
|
|
- **Format:** Tags are enclosed in square brackets at the end of the docstring body.
|
|
- **For Functions/Methods:** `[C: CallerA, CallerB]` — List of primary internal callers within the codebase.
|
|
- **For State Variables:**
|
|
- `[M: File:Line, Method]` — List of primary mutation points (where the value is assigned).
|
|
- `[U: File]` — Major codepaths of use (where the value is read but not changed).
|
|
|
|
### Example:
|
|
```python
|
|
def start_services(self) -> None:
|
|
"""
|
|
Initialises background threads and MCP servers.
|
|
[C: App.run, _cb_load_project]
|
|
"""
|
|
...
|
|
```
|