faif/python-patterns

python-patterns

A collection of design patterns and idioms in Python.

Remember that each pattern has its own trade-offs. And you need to pay attention more to why you're choosing a certain pattern than to how to implement it.

Creational Patterns

Patterns that deal with object creation — abstracting and controlling how instances are made.

graph LR
    Client -->|requests object| AbstractFactory
    AbstractFactory -->|delegates to| ConcreteFactory
    ConcreteFactory -->|produces| Product

    Builder -->|step-by-step| Director
    Director -->|returns| BuiltObject

    FactoryMethod -->|subclass decides| ConcreteProduct
    Pool -->|reuses| PooledInstance

Structural Patterns

Patterns that define how classes and objects are composed to form larger, flexible structures.

graph TD
    Client --> Facade
    Facade --> SubsystemA
    Facade --> SubsystemB
    Facade --> SubsystemC

    Client2 --> Adapter
    Adapter --> LegacyService

    Client3 --> Proxy
    Proxy -->|controls access to| RealSubject

    Component --> Composite
    Composite --> Leaf1
    Composite --> Leaf2

Behavioral Patterns

Patterns concerned with communication and responsibility between objects.

graph LR
    Sender -->|sends event| Observer1
    Sender -->|sends event| Observer2

    Request --> Handler1
    Handler1 -->|passes if unhandled| Handler2
    Handler2 -->|passes if unhandled| Handler3

    Context -->|delegates to| Strategy
    Strategy -->|executes| Algorithm

    Originator -->|saves state to| Memento
    Caretaker -->|holds| Memento

Design for Testability Patterns

Fundamental Patterns

Others

🚫 Anti-Patterns

This section lists some common design patterns that are not recommended in Python and explains why.

🧱 Singleton

Why not:

• Python modules are already singletons — every module is imported only once.
• Explicit singleton classes add unnecessary complexity.
• Better alternatives: use module-level variables or dependency injection.

🌀 God Object

Why not:

• Centralizes too much logic in a single class.
• Makes code harder to test and maintain.
• Better alternative: split functionality into smaller, cohesive classes.

🔁 Inheritance overuse

Why not:

• Deep inheritance trees make code brittle.
• Prefer composition and delegation.
• “Favor composition over inheritance.”

Videos

• Design Patterns in Python by Peter Ullrich
• Sebastian Buczyński - Why you don't need design patterns in Python?
• You Don't Need That!
• Pluggable Libs Through Design Patterns

Contributing

When an implementation is added or modified, please review the following guidelines:

Docstrings

Add module level description in form of a docstring with links to corresponding references or other useful information. Add "Examples in Python ecosystem" section if you know some. It shows how patterns could be applied to real-world problems. facade.py has a good example of detailed description, but sometimes the shorter one as in template.py would suffice.

Python 2 compatibility

To see Python 2 compatible versions of some patterns please check-out the legacy tag.

Update README

When everything else is done - update corresponding part of README.

Travis CI

Please run the following before submitting a patch:

• If you have a bash-compatible shell, use ./lint.sh to run formatting, linting, type checking, and tests.

Development dependencies are pinned in Pipfile.lock. After changing Pipfile, activate a Python 3.10 virtual environment and run make lock to regenerate it.

Contributing via issue triage

You can triage issues and pull requests on CodeTriage.