Module Design Guide

Universal rules for designing Python modules and packages. Not framework-specific — applies to any Python project.

Directory structure, layered architecture, size limits, public API facade

Data models, validation, serialization, configuration, migration from v1

Async/await, gather, semaphores, dual API, streaming, graceful shutdown

Exception hierarchy, error codes, recovery patterns, structured logging

pytest setup, unit/integration/performance tests, mocking, factories

Protocols, constructor injection, factories, containers, testability

Circuit breaker, retry with backoff, timeout, bulkhead, rate limiting

Naming, type annotations, formatting, docstrings, tooling

Async optimization, memory, caching, database, profiling

8-phase refactoring process, commit strategy, rollback plan

Cheat sheets, templates, size limits, anti-pattern mapping