---
description: Python style for CelerisLab — path header, docstrings, English comments
alwaysApply: true
---

# Python style (CelerisLab)

## File header

- Every `src/CelerisLab/**/*.py` file starts with a single-line path comment so agents can orient without reading the body:
  - Format: `# CelerisLab/<path_under_package>` (e.g. `# CelerisLab/simulation.py`).
- Match the real path under `CelerisLab/` after edits or moves.

## Language

- All comments and docstrings in Python source are **English**. User-facing prose in `configs/CONFIG.md` may stay Chinese if that file is explicitly maintained for Chinese readers.

## Docstrings and structure

- Module docstring: one-line summary plus at least one structured block where useful (`Usage::`, `Responsibilities:`, `Design:`).
- Public classes and public functions/methods should have a docstring that states purpose; use Google-style sections (`Args:`, `Returns:`, `Raises:`) when parameters or return value are non-obvious.
- Section dividers in long files: `# -- Section name ---------------------------------------` (consistent with existing files like `simulation.py`).

## Types

- Prefer type hints on public APIs (`Simulation`, `ObjectManager`, `LBMField`, config loaders). Completeness can improve incrementally; do not block features on perfect annotation coverage.

## Imports

- Avoid obvious dead imports when touching a file, but **do not** run broad “import cleanup only” refactors as a standalone task unless asked.

## Placeholders

- Stub methods: `pass` plus a short docstring; mark intent with `(placeholder)` or `(future)` where appropriate.