diff --git a/conductor/code_styleguides/python.md b/conductor/code_styleguides/python.md index b684577..b82c566 100644 --- a/conductor/code_styleguides/python.md +++ b/conductor/code_styleguides/python.md @@ -1,37 +1,64 @@ -# Google Python Style Guide Summary +# AI-Optimized Python Style Guide -This document summarizes key rules and best practices from the Google 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. Python Language Rules -- **Linting:** Run `pylint` on your code to catch bugs and style issues. -- **Imports:** Use `import x` for packages/modules. Use `from x import y` only when `y` is a submodule. -- **Exceptions:** Use built-in exception classes. Do not use bare `except:` clauses. -- **Global State:** Avoid mutable global state. Module-level constants are okay and should be `ALL_CAPS_WITH_UNDERSCORES`. -- **Comprehensions:** Use for simple cases. Avoid for complex logic where a full loop is more readable. -- **Default Argument Values:** Do not use mutable objects (like `[]` or `{}`) as default values. -- **True/False Evaluations:** Use implicit false (e.g., `if not my_list:`). Use `if foo is None:` to check for `None`. -- **Type Annotations:** Strongly encouraged for all public APIs. +## 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. Python Style Rules -- **Line Length:** Maximum 80 characters. -- **Indentation:** 4 spaces per indentation level. Never use tabs. -- **Blank Lines:** Two blank lines between top-level definitions (classes, functions). One blank line between method definitions. -- **Whitespace:** Avoid extraneous whitespace. Surround binary operators with single spaces. -- **Docstrings:** Use `"""triple double quotes"""`. Every public module, function, class, and method must have a docstring. - - **Format:** Start with a one-line summary. Include `Args:`, `Returns:`, and `Raises:` sections. -- **Strings:** Use f-strings for formatting. Be consistent with single (`'`) or double (`"`) quotes. -- **`TODO` Comments:** Use `TODO(username): Fix this.` format. -- **Imports Formatting:** Imports should be on separate lines and grouped: standard library, third-party, and your own application's imports. +## 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. Naming -- **General:** `snake_case` for modules, functions, methods, and variables. -- **Classes:** `PascalCase`. -- **Constants:** `ALL_CAPS_WITH_UNDERSCORES`. -- **Internal Use:** Use a single leading underscore (`_internal_variable`) for internal module/class members. +## 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. Main -- All executable files should have a `main()` function that contains the main logic, called from a `if __name__ == '__main__':` block. +## 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. -**BE CONSISTENT.** When editing code, match the existing style. +## 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. -*Source: [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)* +## 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. diff --git a/conductor/tracks/python_style_refactor_20260227/plan.md b/conductor/tracks/python_style_refactor_20260227/plan.md index b1a2026..cc59680 100644 --- a/conductor/tracks/python_style_refactor_20260227/plan.md +++ b/conductor/tracks/python_style_refactor_20260227/plan.md @@ -13,12 +13,12 @@ - [x] Task: Conductor - User Manual Verification 'Phase 2: Indentation and Newline Refactor' (Protocol in workflow.md) [checkpoint: Phase2] ## Phase 3: AI-Optimized Metadata and Final Cleanup -- [~] Task: Conductor - Implement Strict Type Hinting across the Entire Codebase. +- [x] Task: Conductor - Implement Strict Type Hinting across the Entire Codebase. [c816f65] - [x] Engine Core (`ai_client.py`, `mcp_client.py`, `aggregate.py`, `shell_runner.py`) - [x] Develop/Integrate Surgical AST Tools in `mcp_client.py` and `tools.json`. - [x] Management Modules (project_manager.py, session_logger.py) [19c28a1] - - [~] UI Modules (`gui_2.py`, `gui_legacy.py`) -- [ ] Task: Conductor - Update `conductor/code_styleguides/python.md` with the new AI-optimized standard. + - [x] UI Modules (`gui_2.py`, `gui_legacy.py`) [c816f65] +- [~] Task: Conductor - Update `conductor/code_styleguides/python.md` with the new AI-optimized standard. - [ ] Task: Conductor - User Manual Verification 'Phase 3: Metadata and Final Documentation' (Protocol in workflow.md) ---