arch-python-modern

name	arch-python-modern
description	Modern Python 3.10+ development standards including type hints, async patterns, pathlib, dataclasses, and recommended tooling (uv, Ruff, pytest). Use for Python code review, new feature implementation, refactoring legacy code, or making architecture decisions about Python projects.
allowed-tools	Read, Grep, Glob
kb-sources	["wiki/software-engineering/arch-python-modern"]
updated	"2026-06-03T00:00:00.000Z"

Modern Python Standards

Development practices for Python 3.10+ focusing on type safety, modern idioms, and efficient tooling.

Recommended Stack

Category	Tool
Package Management	uv (preferred) or Poetry
Linting/Formatting	Ruff
Type Checking	mypy (strict mode)
Testing	pytest with coverage
Web APIs	FastAPI
Data Processing	Polars or Pandas

Key Patterns

Type Hints

• Public functions use type hints — enables static analysis and IDE tooling
• X | None for nullable (3.10+), list[X] over List[X] (3.9+)
• TypeVar for generics, Protocol for structural typing

Async

• Use asyncio with TaskGroup for structured concurrency (3.11+)
• Blocking calls in async context stall the event loop — use asyncio.gather() for concurrent I/O

Path Handling

• pathlib.Path over os.path; use .read_text(), .write_text()
• Sanitize user-controlled filenames: replace("/", "_").replace("\\", "_") before Path(name).name. See reference.md → User-Controlled Filename Sanitization.
• Resolve vault/repo roots from a config file, not Path(__file__).parents[N] — relocation silently breaks __file__-relative walks. See reference.md → Config-Resolved Roots.

Error Handling

• Specific exceptions over bare except: — bare form catches SystemExit and KeyboardInterrupt
• Context managers for resources; logging with structlog
• logging.error("msg", exc_info=e) — preserves traceback; not f-string interpolation

Pydantic Settings Validation

@property (lazy) → @field_validator (per-field) → @model_validator (cross-field, after parse). Use @model_validator for cross-field security controls. See reference.md → Pydantic Validators.

Pydantic Dual-Purpose Models

Storage + API response in one model: use a thin response model, not serialization_alias — alias changes affect GCS/DB output. See reference.md → Pydantic Dual-Purpose Models.

Pydantic Value Objects

Compare with str() on both sides: str(a) != str(b) — prevents silent type-mismatch failures.

StrEnum for Status Fields

Use StrEnum for status fields. ORM defaults: default=WidgetStatus.ACTIVE, not default="active" (bare strings go out of sync).

Computed Fields

Use @computed_field @property — included in .model_dump() and JSON schema. Avoid __init__ assignment (bypasses Pydantic validation lifecycle).

Module Dispatch

• Per-module MODE constant + uniform render() / write() / main() triple lets one orchestrator dispatch heterogeneous modules with no per-module branching.
• Registry-driven orchestrator: dict mapping selector → (callable, mode, defaults) — adding a module is a one-line change. See reference.md → Module Dispatch Patterns.

Experiment Script Isolation

[project.optional-dependencies] groups keep AI/ML deps out of the production image. Install via uv pip install -e ".[experiments]"; pair with mypy exclude + pytest norecursedirs. See reference.md → Experiment Script Isolation.

Anti-Patterns

Anti-Pattern	Pattern
os.path.join()	Path() / "file"
% formatting	f-strings
pip install	uv add
flake8	Ruff
List[str]	list[str]
Optional[X]	X | None
populate_by_name=True on request models	Keep False — widens API input surface by accepting both alias and field name
Mutable default args	field(default_factory=list)
time.time() for elapsed	time.perf_counter()
Custom http_client= without lifecycle	Let library manage client
default="active" (bare string)	default=WidgetStatus.ACTIVE (StrEnum)
except Exception as err: logging.exception("msg")	except Exception: logging.exception("msg") — err unused (ruff F841); exception captured from call stack
Path(__file__).parents[N] for repo root	Resolve root from config file — __file__-relative walks break on relocation

See reference.md for: type hints, dataclasses, async patterns, path handling, error handling, docstrings, resource leaks, tooling config, git tracking in ignored dirs, LRU cache with model_copy(), config-resolved roots, module dispatch patterns.

See examples.md for: project structure, type-safe config, async HTTP client, repository pattern, modern testing, FastAPI endpoints, structured logging, Django+OpenCV pipeline.