Dignified Python Standards
Enforce modern Python standards including LBYL exception handling, contemporary type syntax, pathlib usage, and rigorous testing practices. Designed for early-stage projects that prioritize clean design over backward compatibility.
Instructions
When writing or reviewing Python code, apply these standards:
1. Exception Handling (LBYL - Look Before You Leap)
**Fail fast with clear errors.** Do not catch exceptions to handle them gracefully.Let errors propagate with descriptive messages.Avoid `try/except` blocks unless re-raising with additional context.Validate preconditions explicitly before operations.```python
Good
if not path.exists():
raise FileNotFoundError(f"Required file not found: {path}")
Avoid
try:
path.read_text()
except FileNotFoundError:
return None # Silent failure obscures root cause
```
2. Modern Type Syntax
Use PEP 604 union syntax: `str | None` instead of `Optional[str]`Use PEP 585 generics: `list[int]` instead of `List[int]`Code must pass `just typecheck` (or equivalent type checker)Fix all type errors before completing work3. Path Handling
Always use `pathlib.Path` for filesystem operationsNever use `os.path` or raw string manipulationLeverage `Path` methods: `.exists()`, `.read_text()`, `.write_text()`, `.iterdir()`, etc.```python
from pathlib import Path
config_path = Path("config") / "settings.yaml"
if config_path.exists():
content = config_path.read_text()
```
4. Testing Standards
**Add or update tests** when modifying features**Never run full test suite** unless explicitly instructedRun targeted tests: `uv run pytest tests/path/to/test.py -k "pattern"`Update snapshot tests when intentional: `uv run pytest --snapshot-update path/to/test.py`Verify changes before considering work complete5. Documentation Guidelines
**Docstrings:**
Focus on high-level concepts, properties, and invariantsAvoid documenting implementation details or default valuesKeep docstrings concise and relevant**Comments:**
Describe the current state, not historical contextNever reference refactoring history or deleted codeAvoid phrases like "previously used X" or "removed Y"**Written docs:**
Use complete English sentencesMinimize excessive parenthetical asidesProvide generic explanations first, then concrete examplesLeverage Material for MkDocs features (tooltips, admonitions)6. Code Simplicity
Avoid over-engineeringMake only requested or clearly necessary changesKeep solutions simple and focusedDon't add features, refactoring, or improvements beyond requirementsNo unnecessary error handling for impossible scenariosTrust internal code and framework guaranteesValidate only at system boundaries (user input, external APIs)7. Development Commands
```bash
just sync # Install dependencies
just ruff # Lint and format
just typecheck # Type check
uv run pytest # Run tests (filter with -k "pattern")
```
8. Git Workflow
**Do not create commits** unless explicitly requestedWhen asked to commit, follow standard git workflowAlways run relevant tests before committingExamples
**Bad:**
```python
import os
from typing import Optional, List
def load_config(path: str) -> Optional[dict]:
try:
with open(os.path.join(path, "config.yaml")) as f:
return yaml.safe_load(f)
except: # Too broad, silent failure
return None
```
**Good:**
```python
from pathlib import Path
def load_config(config_dir: Path) -> dict:
config_path = config_dir / "config.yaml"
if not config_path.exists():
raise FileNotFoundError(f"Config not found: {config_path}")
return yaml.safe_load(config_path.read_text())
```
Constraints
Breaking changes encouraged in early developmentPrioritize better design over backward compatibilityNo stable API guarantees until explicitly documentedAll code must pass type checking before completion