Python code organization conventions for this codebase. Apply when structuring modules, organizing imports, designing file layouts, or moving functions/classes within or between files. Use PROACTIVELY when users request to check code organization, move code, or clean up and reorganize a module.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Python code organization conventions for this codebase. Apply when structuring modules, organizing imports, designing file layouts, or moving functions/classes within or between files. Use PROACTIVELY when users request to check code organization, move code, or clean up and reorganize a module.
user-invocable
false
Code Organization Conventions
Apply these organization patterns when writing Python code in this repository.
Quick Reference
Aspect
Pattern
File layout
Imports → Public interface → Private helpers
Module size
Split at ~800 lines or multiple responsibilities
Import order
stdlib → third-party → local
Import style
Absolute imports, no wildcards
Private members
Single _ prefix
Cohesion
Group by feature/responsibility
Coupling
Depend on abstractions, not concretions
Dependencies
No circular imports
Responsibility
One purpose per function/class
Section comments
# region / # endregion (optional)
Module Structure
Pattern: ALL public functions and classes MUST be defined before ANY private
(_-prefixed) functions and classes. This boundary is strict — private helpers
must never appear above public definitions, even if a private function is only
called by the public function directly below it. Within each section (public or
private), group related items together and order them by logical flow.
Verification: Scan the module top-to-bottom. If any _-prefixed function or
class definition appears before a non-_-prefixed function or class definition,
that is a violation and must be reordered.
# src/package/module/file.py# Imports (organized by section)
...
# region Public interface (ALL public definitions first)classPublicClass:
"""Public API class."""
...
defpublic_function() -> ReturnType:
"""Public API function."""
...
# endregion# region Private helpers (ALL private definitions after)def_private_helper() -> ReturnType:
"""Internal implementation detail."""
...
# endregion
# INCORRECT - private function defined before public functiondef_validate_inputs(data: Data) -> None:
"""Validate inputs."""
...
defprocess_data(data: Data) -> Result:
"""Process data."""
_validate_inputs(data)
...
# CORRECT - public function first, private helper afterdefprocess_data(data: Data) -> Result:
"""Process data."""
_validate_inputs(data)
...
def_validate_inputs(data: Data) -> None:
"""Validate inputs."""
...
Class vs. Module-Level Private Helpers
Rule: A private helper function that does NOT access self or cls MUST be a
module-level function, never a @staticmethod or instance method. This applies even
when the function is only called by methods of a single class.
This follows from two conventions:
Avoid static methods (class-design skill) — use module-level functions instead
Public-before-private ordering — module-level private helpers go after the class
Pattern: Use # region / # endregion to delimit code sections within a file.
Section comments are optional -- not every file needs them. But when you do divide a
file into sections, use this format exclusively. VSCode recognizes these keywords and
renders them in the minimap, making them functionally useful, not just decorative.
# CORRECT - standardized region comments# region Public APIclassUserService:
"""Service for user operations."""
...
defcreate_user(data: UserCreate) -> User:
"""Create a new user."""
...
# endregion# region Private Helpersdef_validate_user_data(data: UserCreate) -> None:
"""Validate user creation data."""
...
# endregion# INCORRECT - ad-hoc section dividers# ----- Classes -----# ###### Section Helpers# === Public API ===# ==================== Utils ====================
Rule
Detail
Format
# region <Description> / # endregion
Required?
No -- only use when sectioning adds clarity
Nesting
Allowed but discouraged; keep it flat
Banned alternatives
# -----, # ======, # ######, or other decorative dividers
