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:

def start_services(self) -> None:
 """
 Initialises background threads and MCP servers.
 [C: App.run, _cb_load_project]
 """
 ...

4.0 KiB Raw Blame History