Ed_
602cea6c13
Replaces Google Python Style Guide with project-specific conventions: 1-space indentation, strict type hints on all signatures/vars, minimal blank lines, 120-char soft limit, AI-agent conventions. Also marks type hinting task complete in plan.md. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
65 lines
3.4 KiB
Markdown
65 lines
3.4 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.
|
|
|
|
## 10. Main Guard
|
|
- All executable files should have `if __name__ == "__main__":` calling `main()`.
|
|
|
|
**BE CONSISTENT.** When editing existing code, match the style already present in the file.
|