Factory & Builder Patterns

Factories centralize object creation behind a function or class method so callers stay decoupled from concrete types. Builders assemble complex objects step-by-step when constructors would need too many parameters or optional combinations.

Recipe

Quick-reference recipe card - copy-paste ready.

from dataclasses import dataclass
 
@dataclass
class HttpClient:
    base_url: str
    timeout: float = 30.0
    retries: int = 3
 
def http_client_from_env(env: dict) -> HttpClient:
    return HttpClient(
        base_url=env["API_URL"],
        timeout=float(env.get("HTTP_TIMEOUT", 30)),
    )

When to reach for this:

• Factory when creation logic branches on config, env, or runtime type
• Builder when objects have many optional fields or validation between steps
• classmethod constructors (from_dict, from_url) as lightweight factories
• Hiding import cycles - factory module imports concrete classes, callers do not
• Test doubles - factories accept injectable backends

Working Example

A factory picks storage backends; a builder constructs a validated report config.

from dataclasses import dataclass, field
from typing import Protocol
 
class Storage(Protocol):
    def save(self, key: str, data: bytes) -> None: ...
 
@dataclass
class MemoryStorage:
    _data: dict[str, bytes] = field(default_factory=dict)
 
    def save(self, key: str, data: bytes) -> None:
        self._data[key] = data
 
@dataclass
class FileStorage:
    root: str
 
    def save(self, key: str, data: bytes) -> None:
        print(f"write {key} to {self.root}")
 
def storage_factory(kind: str, **kwargs) -> Storage:
    if kind == "memory":
        return MemoryStorage()
    if kind == "file":
        return FileStorage(root=kwargs["root"])
    raise ValueError(f"unknown storage: {kind}")
 
@dataclass
class ReportConfig:
    title: str
    columns: list[str]
    page_size: int = 50
 
class ReportConfigBuilder:
    def __init__(self, title: str) -> None:
        self._title = title
        self._columns: list[str] = []
        self._page_size = 50
 
    def add_column(self, name: str) -> "ReportConfigBuilder":
        self._columns.append(name)
        return self
 
    def page_size(self, size: int) -> "ReportConfigBuilder":
        if size < 1:
            raise ValueError("page_size must be positive")
        self._page_size = size
        return self
 
    def build(self) -> ReportConfig:
        if not self._columns:
            raise ValueError("at least one column required")
        return ReportConfig(self._title, list(self._columns), self._page_size)
 
store = storage_factory("memory")
store.save("report.pdf", b"%PDF")
 
cfg = (
    ReportConfigBuilder("Sales")
    .add_column("sku")
    .add_column("revenue")
    .page_size(100)
    .build()
)
print(cfg)

What this demonstrates:

• Factory encapsulates branching construction
• Protocol types keep callers storage-agnostic
• Builder methods return self for fluent chaining
• build() validates invariants before returning the product

Deep Dive

How It Works

• Factory: one function maps inputs to a concrete instance
• Builder: accumulates state, validates at build(), avoids telescoping constructors
• @dataclass + field(default_factory=...) often replaces builders for simple cases
• Classmethods (from_env, parse) are idiomatic Python factories
• Dependency injection passes factories instead of instances for late binding

Factory vs Builder

Python Notes

@dataclass
class Settings:
    debug: bool = False
 
    @classmethod
    def from_env(cls, env: dict) -> "Settings":
        return cls(debug=env.get("DEBUG") == "1")

Gotchas

• God factory - one function with 20 elif branches. Fix: registry dict or subclass factories per domain.
• Builder without validation - invalid partial state escapes. Fix: validate only in build(), keep builder mutable internally.
• Over-engineering simple dataclasses - three optional fields do not need a builder. Fix: use defaults and dataclass.
• Factory hiding side effects - creating a client should not connect to network. Fix: separate create from connect.
• Mutable builder reuse - reusing the same builder after build() causes cross-talk. Fix: document single-use or clone on build().

Alternatives

FAQs

Related

• Dependency Injection in Python - wiring factories
• The Strategy & Dispatch Patterns - factory + strategy
• Null Object & Sentinels - default product instances
• Pythonic Patterns Basics - section overview

External Related Links

• Real Python - In-depth tutorials, courses, and practical guides.
• 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).
• Fluent Python (2nd Edition) - Intermediate to advanced Python idioms (Luciano Ramalho).
• Python Crash Course (Penguin Random House) - Same title via publisher.

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+.