jungho-git/python

Python

• Shared examples and formatting reference: references/EXAMPLE.md.
• Keep new guidance, snippets, and edits aligned with that file.

---

Scope

Use this rule when:

• editing .py files
• changing function signatures, data models, or module boundaries
• writing Python scripts, services, CLIs, or data-processing helpers

Python changes should keep typed boundaries explicit and resource handling safe.

---

Runtime

• Use CPython through uv: uv run --no-project --python "%PYTHON_HOME%/python.exe" python.
• Do not call legacy Python interpreter aliases. Use direct python only when checking compatibility or when an external tool requires it.
• Install or verify the runtime with uv python install cpython3.14.

---

Core Rules

• Type all public function signatures.
• Prefer pathlib.Path over os.path.
• Use f-strings for interpolation.
• Never use mutable default arguments.
• Prefer dataclass or TypedDict over unstructured dicts for structured data.
• Never use bare except:; catch specific exceptions.
• Use with statements for resources.
• Group imports: stdlib, third-party, local.
• Never use for i in range(len(items)); use direct iteration, enumerate(), or zip().

---

None And Data Contracts

• Do not return None where a typed value is expected unless the signature says so.
• Use Optional[T] or T | None and check before use.
• Validate external data at the boundary.
• Keep internal flow direct after normalization.

---

Function Shape

• Keep related logic cohesive.
• Extract only for real duplication, unavoidable complexity, a typed boundary, or testable contract.
• Do not add helpers only for style.
• Prefer early return or early raise to keep main logic flat.

---

Formatting

• Follow PEP 8 and Google Python Style where compatible with local style.
• Use Black/Ruff when available and in scope.
• Keep line length near 88 characters.
• Use PascalCase for classes, snake_case for functions and variables, and UPPER_SNAKE_CASE for constants.
• When generating new code, keep newly authored constant and variable names at 30 chars or fewer by default; alias external contract names locally when needed.
• Never vertically align assignments, dict entries, or imports.
• Do not write single-line colon-body forms such as if x: return.

---

Validation Focus

• mutable default arguments
• missing public type hints
• bare exceptions
• resource leaks
• boundary validation and None handling