Arch Python Modern

Modern Python Standards

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

Core Defaults

# Always use modern patterns
from pathlib import Path
from typing import Any
from dataclasses import dataclass

def process(items: list[dict[str, Any]]) -> dict[str, int] | None:
    config_path = Path("config.json")
    return {"count": len(items)} if items else None

Recommended Stack

Key Patterns

Type Hints

• All public functions must have type hints
• Use X | None for nullable values (3.10+)
• Prefer list[X] over List[X] (3.9+)
• Use TypeVar for generic functions

Async

• Use asyncio with modern patterns
• Avoid blocking in async contexts
• asyncio.gather() for concurrent operations
• asyncio.TaskGroup for structured concurrency (3.11+)

Path Handling

• Always pathlib.Path over os.path
• Use .read_text(), .write_text()
• Proper path resolution, no hardcoding

Error Handling

• Specific exceptions, never bare except:
• Context managers for resources
• Proper logging with structlog

Pydantic Settings Validation

Validator timing determines when validation executes:

Security controls typically use @model_validator to fail fast:

from pydantic import model_validator

class Settings(BaseSettings):
    environment: str = "development"
    auth_database_url: str | None = None

    @model_validator(mode="after")
    def validate_production_requirements(self) -> "Settings":
        if self.environment == "production" and not self.auth_database_url:
            raise ValueError("AUTH_DATABASE_URL required in production")
        return self

Pydantic Value Object Comparison

When comparing Pydantic models or value objects, use str() on both sides:

# WRONG - type mismatch causes silent failures
session.visitor_id.value != visitor_id

# RIGHT - explicit string conversion
str(session.visitor_id) != str(visitor_id)

Anti-Patterns to Avoid

See reference.md for detailed patterns and examples.md for code samples.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.