Pythonic Patterns Best Practices

Rules for readable, maintainable Python structure - from EAFP to dependency wiring.

How to Use This List

• Apply during design reviews before adding new abstraction layers.
• Prefer one clear pattern per boundary - do not mix dispatch styles in the same module.
• Enforce with ruff, mypy/pyright, and architecture tests where possible.

A - Idioms & Readability

• Prefer EAFP when success is common. Linear happy paths beat nested guards; catch specific exceptions.
• Use with for acquire/release pairs. Files, locks, and transactions need guaranteed teardown.
• Reach for dict dispatch before elif chains grow past five branches. Register plugins explicitly.
• Name factory functions thing_from_env / build_thing. Callers recognize composition-root helpers.
• Readability counts over cleverness. If a junior cannot trace it in five minutes, simplify.

B - Structure & Coupling

• Inject dependencies through constructors. No hidden get_db() singletons in service methods.
• Depend on protocols, wire concretes at the root. Application code stays testable and swappable.
• Use null objects for optional no-op collaborators. Not for required production dependencies.
• Publish domain events through a bus interface. Handlers stay small; failures logged per handler.
• Split god objects by responsibility before adding the tenth method. Extract protocols first.

C - Defaults & Safety

• Never use mutable default arguments. None sentinel plus fresh container inside the function.
• Use explicit sentinels when None is valid data. Document is checks for UNSET objects.
• Validate builders in build(), not in setters. Keep partial builder state internal.
• Avoid import-time I/O and network. Startup hooks and lifespan handlers own side effects.
• Catch specific exceptions; never bare except. Log context; re-raise unless suppression is contractual.

D - Abstraction Discipline

• Rule of three before extracting interfaces. Wait for three real duplications, not imagined futures.
• Prefer functions and dataclasses over deep inheritance. Composition and dispatch cover most Python cases.
• Replace boolean flag sprawl with enums or strategies. Modes are types, not four True/False params.
• Keep public APIs explicit - minimal **kwargs. TypedDict or Pydantic at HTTP/CLI boundaries.
• Document valid registry keys and event names. StrEnum or Literal for static checking.

E - Review & Evolution

• Scan for anti-patterns in high-churn modules quarterly. Mutable defaults and swallowed errors first.
• One integration test per dispatcher/registry. Unknown keys and types fail with clear messages.
• Refactor extract-by-protocol in small PRs. Facade delegates until callers migrate.
• Match pattern to problem size. Scripts stay simple; services get injection and events.
• Link ADRs when choosing bus vs direct calls. Future readers know the trade-off accepted.

FAQs

Related

• Pythonic Patterns Basics - hands-on examples
• Common Anti-Patterns - mistakes to avoid
• EAFP vs LBYL - exception style
• Dependency Injection in Python - wiring detail

External Related Links

• The Hitchhiker's Guide to Python - Best-practices handbook for installation, configuration, style, and tooling.
• Official Python Documentation - The definitive source (Tutorial, Library Reference, Language Reference, HOWTOs).
• Real Python - In-depth tutorials, courses, and practical guides.
• Fluent Python (2nd Edition) - Intermediate to advanced Python idioms (Luciano Ramalho).
• Python Crash Course (3rd Edition) - Beginner-friendly projects (Eric Matthes).

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.