manual_slop/conductor/code_styleguides/python.md

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.