# 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.