Article 5: SOLID Principles and Design Patterns

Introduction

SOLID principles are the foundation of maintainable object-oriented design. Through refactoring many codebases, I've seen how violating these principles leads to fragile, rigid code—and how following them creates systems that are a joy to work with.

This article covers the five SOLID principles with Python examples, plus advanced design patterns that build on the foundation from the previous article.

The SOLID Principles

S - Single Responsibility Principle

A class should have only one reason to change.

The Problem

# Bad: Class has multiple responsibilities
class UserService:
    def __init__(self, db_connection):
        self.db = db_connection

    def create_user(self, email: str, password: str) -> User:
        # Validation logic
        if not self._is_valid_email(email):
            raise ValueError("Invalid email")
        if len(password) < 8:
            raise ValueError("Password too short")

        # Password hashing
        password_hash = bcrypt.hash(password)

        # Database logic
        user = User(email=email, password_hash=password_hash)
        self.db.add(user)
        self.db.commit()

        # Email notification
        self._send_welcome_email(user)

        return user

    def _is_valid_email(self, email: str) -> bool:
        return "@" in email and "." in email

    def _send_welcome_email(self, user: User) -> None:
        # SMTP logic here
        smtp = smtplib.SMTP("localhost")
        smtp.send_message(...)

This class has four responsibilities: validation, password hashing, database operations, and email sending.

The Solution

# Good: Each class has a single responsibility

class EmailValidator:
    """Validates email format."""
    
    def is_valid(self, email: str) -> bool:
        pattern = r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"
        return bool(re.match(pattern, email))


class PasswordHasher:
    """Handles password hashing."""
    
    def hash(self, password: str) -> str:
        return bcrypt.hash(password)
    
    def verify(self, password: str, hash: str) -> bool:
        return bcrypt.verify(password, hash)


class UserRepository:
    """Manages User persistence."""
    
    def __init__(self, session) -> None:
        self._session = session

    def save(self, user: User) -> User:
        self._session.add(user)
        self._session.commit()
        return user

    def find_by_email(self, email: str) -> Optional[User]:
        return self._session.query(User).filter_by(email=email).first()


class EmailNotifier:
    """Sends email notifications."""
    
    def __init__(self, smtp_config: SMTPConfig) -> None:
        self._config = smtp_config

    def send_welcome_email(self, user: User) -> None:
        # Email sending logic
        pass


class UserService:
    """Orchestrates user operations."""
    
    def __init__(
        self,
        validator: EmailValidator,
        hasher: PasswordHasher,
        repository: UserRepository,
        notifier: EmailNotifier,
    ) -> None:
        self._validator = validator
        self._hasher = hasher
        self._repository = repository
        self._notifier = notifier

    def create_user(self, email: str, password: str) -> User:
        if not self._validator.is_valid(email):
            raise ValueError("Invalid email")

        password_hash = self._hasher.hash(password)
        user = User(email=email, password_hash=password_hash)
        
        self._repository.save(user)
        self._notifier.send_welcome_email(user)
        
        return user

Benefits

• Easier testing: Each class can be tested in isolation

• Easier changes: Changing email logic doesn't affect database logic

• Better reuse: EmailValidator can be used elsewhere

• Clearer code: Each class has a clear purpose

O - Open/Closed Principle

Software entities should be open for extension but closed for modification.

The Problem

# Bad: Must modify class to add new discount types
class DiscountCalculator:
    def calculate(self, order: Order, discount_type: str) -> Decimal:
        if discount_type == "percentage":
            return order.total * Decimal("0.10")
        elif discount_type == "fixed":
            return Decimal("10.00")
        elif discount_type == "bulk":
            if order.quantity > 10:
                return order.total * Decimal("0.15")
            return Decimal("0")
        # Every new discount type requires modifying this class!
        else:
            raise ValueError(f"Unknown discount type: {discount_type}")

The Solution

# Good: Open for extension, closed for modification
from abc import ABC, abstractmethod


class DiscountStrategy(ABC):
    """Base class for discount strategies."""
    
    @abstractmethod
    def calculate(self, order: Order) -> Decimal:
        """Calculate discount amount for an order."""
        pass


class PercentageDiscount(DiscountStrategy):
    def __init__(self, percentage: Decimal) -> None:
        self._percentage = percentage

    def calculate(self, order: Order) -> Decimal:
        return order.total * self._percentage


class FixedDiscount(DiscountStrategy):
    def __init__(self, amount: Decimal) -> None:
        self._amount = amount

    def calculate(self, order: Order) -> Decimal:
        return min(self._amount, order.total)


class BulkDiscount(DiscountStrategy):
    def __init__(self, threshold: int, percentage: Decimal) -> None:
        self._threshold = threshold
        self._percentage = percentage

    def calculate(self, order: Order) -> Decimal:
        if order.quantity > self._threshold:
            return order.total * self._percentage
        return Decimal("0")


# New discount types don't require modifying existing code
class SeasonalDiscount(DiscountStrategy):
    def __init__(self, season: str, percentage: Decimal) -> None:
        self._season = season
        self._percentage = percentage

    def calculate(self, order: Order) -> Decimal:
        if self._is_current_season():
            return order.total * self._percentage
        return Decimal("0")

    def _is_current_season(self) -> bool:
        # Season checking logic
        pass


class DiscountCalculator:
    """Applies discount strategies to orders."""
    
    def calculate(self, order: Order, strategy: DiscountStrategy) -> Decimal:
        return strategy.calculate(order)


# Usage
calculator = DiscountCalculator()
discount = calculator.calculate(order, BulkDiscount(10, Decimal("0.15")))

L - Liskov Substitution Principle

Subtypes must be substitutable for their base types.

The Problem

# Bad: Subclass violates parent contract
class Bird:
    def fly(self) -> str:
        return "Flying high!"


class Penguin(Bird):
    def fly(self) -> str:
        # Penguins can't fly! This breaks the contract.
        raise NotImplementedError("Penguins can't fly")


def make_bird_fly(bird: Bird) -> str:
    return bird.fly()  # Crashes with Penguin!


# This code expects all Birds to fly
sparrow = Bird()
penguin = Penguin()

make_bird_fly(sparrow)  # Works
make_bird_fly(penguin)  # Raises exception!

The Solution

# Good: Proper abstraction that respects LSP
from abc import ABC, abstractmethod


class Bird(ABC):
    """Base class for all birds."""
    
    @abstractmethod
    def move(self) -> str:
        """Move in the bird's natural way."""
        pass


class FlyingBird(Bird):
    """Birds that can fly."""
    
    def move(self) -> str:
        return self.fly()
    
    def fly(self) -> str:
        return "Flying through the sky!"


class SwimmingBird(Bird):
    """Birds that primarily swim."""
    
    def move(self) -> str:
        return self.swim()
    
    def swim(self) -> str:
        return "Swimming through the water!"


class Sparrow(FlyingBird):
    pass


class Penguin(SwimmingBird):
    def swim(self) -> str:
        return "Swimming gracefully!"


def make_bird_move(bird: Bird) -> str:
    return bird.move()  # Works for all birds!


# Now any Bird can be used
sparrow = Sparrow()
penguin = Penguin()

make_bird_move(sparrow)  # "Flying through the sky!"
make_bird_move(penguin)  # "Swimming gracefully!"

Another Example: Rectangle/Square

# Classic LSP violation
class Rectangle:
    def __init__(self, width: int, height: int) -> None:
        self._width = width
        self._height = height

    @property
    def width(self) -> int:
        return self._width

    @width.setter
    def width(self, value: int) -> None:
        self._width = value

    @property
    def height(self) -> int:
        return self._height

    @height.setter
    def height(self, value: int) -> None:
        self._height = value

    def area(self) -> int:
        return self._width * self._height


class Square(Rectangle):
    def __init__(self, side: int) -> None:
        super().__init__(side, side)

    @Rectangle.width.setter
    def width(self, value: int) -> None:
        # Must keep width == height, violating Rectangle behavior
        self._width = value
        self._height = value

    @Rectangle.height.setter
    def height(self, value: int) -> None:
        self._width = value
        self._height = value


# This function expects Rectangle behavior
def double_width(rect: Rectangle) -> None:
    rect.width = rect.width * 2
    # For a 5x10 rectangle, we expect area = 100
    # For a 5x5 square, we get area = 100 but height also changed!


# Better: Use composition or separate abstractions
from abc import ABC, abstractmethod


class Shape(ABC):
    @abstractmethod
    def area(self) -> int:
        pass


@dataclass
class Rectangle(Shape):
    width: int
    height: int

    def area(self) -> int:
        return self.width * self.height


@dataclass
class Square(Shape):
    side: int

    def area(self) -> int:
        return self.side * self.side

I - Interface Segregation Principle

Clients should not be forced to depend on interfaces they don't use.

The Problem

# Bad: Fat interface that forces unnecessary implementations
from abc import ABC, abstractmethod


class Worker(ABC):
    @abstractmethod
    def work(self) -> None:
        pass

    @abstractmethod
    def eat(self) -> None:
        pass

    @abstractmethod
    def sleep(self) -> None:
        pass

    @abstractmethod
    def take_break(self) -> None:
        pass


class Human(Worker):
    def work(self) -> None:
        print("Working on tasks")

    def eat(self) -> None:
        print("Eating lunch")

    def sleep(self) -> None:
        print("Sleeping at home")

    def take_break(self) -> None:
        print("Taking a coffee break")


class Robot(Worker):
    def work(self) -> None:
        print("Processing tasks")

    def eat(self) -> None:
        pass  # Robots don't eat - forced to implement!

    def sleep(self) -> None:
        pass  # Robots don't sleep - forced to implement!

    def take_break(self) -> None:
        pass  # Robots don't take breaks - forced to implement!

The Solution

# Good: Segregated interfaces
from abc import ABC, abstractmethod
from typing import Protocol


class Workable(Protocol):
    """Interface for entities that can work."""
    
    def work(self) -> None:
        ...


class Eatable(Protocol):
    """Interface for entities that eat."""
    
    def eat(self) -> None:
        ...


class Sleepable(Protocol):
    """Interface for entities that sleep."""
    
    def sleep(self) -> None:
        ...


class Breakable(Protocol):
    """Interface for entities that take breaks."""
    
    def take_break(self) -> None:
        ...


class Human:
    """Implements all interfaces relevant to humans."""
    
    def work(self) -> None:
        print("Working on tasks")

    def eat(self) -> None:
        print("Eating lunch")

    def sleep(self) -> None:
        print("Sleeping at home")

    def take_break(self) -> None:
        print("Taking a coffee break")


class Robot:
    """Only implements interfaces relevant to robots."""
    
    def work(self) -> None:
        print("Processing tasks")


# Functions only depend on what they need
def assign_work(worker: Workable) -> None:
    worker.work()


def schedule_lunch(eater: Eatable) -> None:
    eater.eat()


# Both work for assign_work
human = Human()
robot = Robot()

assign_work(human)  # Works
assign_work(robot)  # Works

# Only Human works for schedule_lunch
schedule_lunch(human)  # Works
# schedule_lunch(robot)  # Type error - Robot doesn't implement Eatable

D - Dependency Inversion Principle

High-level modules should not depend on low-level modules. Both should depend on abstractions.

The Problem

# Bad: High-level module depends on low-level implementation
class MySQLDatabase:
    def connect(self) -> None:
        print("Connecting to MySQL")

    def execute(self, query: str) -> list:
        print(f"Executing MySQL query: {query}")
        return []


class UserService:
    def __init__(self) -> None:
        # Direct dependency on concrete implementation
        self.db = MySQLDatabase()

    def get_users(self) -> list[User]:
        return self.db.execute("SELECT * FROM users")


# Can't switch to PostgreSQL without modifying UserService
# Can't test UserService without a real database

The Solution

# Good: Depend on abstractions
from abc import ABC, abstractmethod
from typing import Protocol


class Database(Protocol):
    """Abstract interface for database operations."""
    
    def connect(self) -> None:
        ...

    def execute(self, query: str) -> list:
        ...


class MySQLDatabase:
    def connect(self) -> None:
        print("Connecting to MySQL")

    def execute(self, query: str) -> list:
        print(f"Executing MySQL query: {query}")
        return []


class PostgreSQLDatabase:
    def connect(self) -> None:
        print("Connecting to PostgreSQL")

    def execute(self, query: str) -> list:
        print(f"Executing PostgreSQL query: {query}")
        return []


class InMemoryDatabase:
    """For testing purposes."""
    
    def __init__(self) -> None:
        self._data: dict[str, list] = {}

    def connect(self) -> None:
        pass

    def execute(self, query: str) -> list:
        return self._data.get("users", [])


class UserService:
    def __init__(self, database: Database) -> None:
        # Depends on abstraction, not concrete implementation
        self._db = database

    def get_users(self) -> list:
        return self._db.execute("SELECT * FROM users")


# Production
mysql_db = MySQLDatabase()
user_service = UserService(mysql_db)

# Testing
test_db = InMemoryDatabase()
test_service = UserService(test_db)

# Easily switch implementations
postgres_db = PostgreSQLDatabase()
postgres_service = UserService(postgres_db)

Dependency Injection Patterns

# Constructor Injection (most common)
class OrderService:
    def __init__(
        self,
        repository: OrderRepository,
        notifier: Notifier,
    ) -> None:
        self._repository = repository
        self._notifier = notifier


# Method Injection (for optional dependencies)
class ReportGenerator:
    def generate(
        self,
        data: list[dict],
        formatter: ReportFormatter,
    ) -> str:
        return formatter.format(data)


# Simple Dependency Container
class Container:
    """Simple dependency injection container."""
    
    def __init__(self) -> None:
        self._services: dict[type, object] = {}

    def register(self, interface: type, implementation: object) -> None:
        self._services[interface] = implementation

    def resolve(self, interface: type) -> object:
        if interface not in self._services:
            raise KeyError(f"No implementation registered for {interface}")
        return self._services[interface]


# Usage
container = Container()
container.register(Database, MySQLDatabase())
container.register(UserRepository, SQLUserRepository(container.resolve(Database)))

user_repo = container.resolve(UserRepository)

Advanced Design Patterns

Building on the patterns from Article 4, here are more patterns that work with SOLID principles.

Observer Pattern

Allows objects to notify others of state changes:

from abc import ABC, abstractmethod
from typing import Protocol


class Observer(Protocol):
    """Observer interface."""
    
    def update(self, event: str, data: dict) -> None:
        ...


class Subject:
    """Subject that observers can subscribe to."""
    
    def __init__(self) -> None:
        self._observers: list[Observer] = []

    def attach(self, observer: Observer) -> None:
        self._observers.append(observer)

    def detach(self, observer: Observer) -> None:
        self._observers.remove(observer)

    def notify(self, event: str, data: dict) -> None:
        for observer in self._observers:
            observer.update(event, data)


class Order(Subject):
    def __init__(self, order_id: int) -> None:
        super().__init__()
        self.order_id = order_id
        self._status = "pending"

    @property
    def status(self) -> str:
        return self._status

    def complete(self) -> None:
        self._status = "completed"
        self.notify("order_completed", {"order_id": self.order_id})

    def cancel(self) -> None:
        self._status = "cancelled"
        self.notify("order_cancelled", {"order_id": self.order_id})


class EmailNotifier:
    def update(self, event: str, data: dict) -> None:
        if event == "order_completed":
            print(f"Sending completion email for order {data['order_id']}")


class InventoryManager:
    def update(self, event: str, data: dict) -> None:
        if event == "order_completed":
            print(f"Updating inventory for order {data['order_id']}")
        elif event == "order_cancelled":
            print(f"Restoring inventory for order {data['order_id']}")


class AnalyticsTracker:
    def update(self, event: str, data: dict) -> None:
        print(f"Tracking event: {event} with data: {data}")


# Usage
order = Order(123)
order.attach(EmailNotifier())
order.attach(InventoryManager())
order.attach(AnalyticsTracker())

order.complete()
# Output:
# Sending completion email for order 123
# Updating inventory for order 123
# Tracking event: order_completed with data: {'order_id': 123}

Decorator Pattern

Add behavior to objects dynamically:

from abc import ABC, abstractmethod
from decimal import Decimal


class Coffee(ABC):
    """Base coffee interface."""
    
    @abstractmethod
    def cost(self) -> Decimal:
        pass

    @abstractmethod
    def description(self) -> str:
        pass


class Espresso(Coffee):
    def cost(self) -> Decimal:
        return Decimal("2.00")

    def description(self) -> str:
        return "Espresso"


class CoffeeDecorator(Coffee):
    """Base decorator."""
    
    def __init__(self, coffee: Coffee) -> None:
        self._coffee = coffee

    def cost(self) -> Decimal:
        return self._coffee.cost()

    def description(self) -> str:
        return self._coffee.description()


class Milk(CoffeeDecorator):
    def cost(self) -> Decimal:
        return self._coffee.cost() + Decimal("0.50")

    def description(self) -> str:
        return f"{self._coffee.description()}, Milk"


class Vanilla(CoffeeDecorator):
    def cost(self) -> Decimal:
        return self._coffee.cost() + Decimal("0.75")

    def description(self) -> str:
        return f"{self._coffee.description()}, Vanilla"


class WhippedCream(CoffeeDecorator):
    def cost(self) -> Decimal:
        return self._coffee.cost() + Decimal("0.60")

    def description(self) -> str:
        return f"{self._coffee.description()}, Whipped Cream"


# Usage - compose decorators
coffee = Espresso()
coffee = Milk(coffee)
coffee = Vanilla(coffee)
coffee = WhippedCream(coffee)

print(coffee.description())  # Espresso, Milk, Vanilla, Whipped Cream
print(coffee.cost())         # 3.85

Builder Pattern

Construct complex objects step by step:

from dataclasses import dataclass, field
from typing import Optional


@dataclass
class HTTPRequest:
    url: str
    method: str = "GET"
    headers: dict[str, str] = field(default_factory=dict)
    body: Optional[str] = None
    timeout: int = 30
    retry_count: int = 0


class HTTPRequestBuilder:
    """Builder for constructing HTTP requests."""
    
    def __init__(self, url: str) -> None:
        self._url = url
        self._method = "GET"
        self._headers: dict[str, str] = {}
        self._body: Optional[str] = None
        self._timeout = 30
        self._retry_count = 0

    def method(self, method: str) -> "HTTPRequestBuilder":
        self._method = method
        return self

    def header(self, key: str, value: str) -> "HTTPRequestBuilder":
        self._headers[key] = value
        return self

    def json_body(self, data: dict) -> "HTTPRequestBuilder":
        import json
        self._body = json.dumps(data)
        self._headers["Content-Type"] = "application/json"
        return self

    def timeout(self, seconds: int) -> "HTTPRequestBuilder":
        self._timeout = seconds
        return self

    def retry(self, count: int) -> "HTTPRequestBuilder":
        self._retry_count = count
        return self

    def build(self) -> HTTPRequest:
        return HTTPRequest(
            url=self._url,
            method=self._method,
            headers=self._headers,
            body=self._body,
            timeout=self._timeout,
            retry_count=self._retry_count,
        )


# Usage - fluent interface
request = (
    HTTPRequestBuilder("https://api.example.com/users")
    .method("POST")
    .header("Authorization", "Bearer token123")
    .json_body({"name": "Alice", "email": "[email protected]"})
    .timeout(60)
    .retry(3)
    .build()
)

Adapter Pattern

Make incompatible interfaces work together:

from abc import ABC, abstractmethod
from typing import Protocol


# Target interface our code expects
class PaymentProcessor(Protocol):
    def charge(self, amount: Decimal, currency: str) -> bool:
        ...


# Legacy system with different interface
class LegacyPaymentGateway:
    """Old payment system we can't modify."""
    
    def process_payment(
        self,
        amount_cents: int,
        currency_code: int,
    ) -> dict:
        # Legacy implementation
        return {"success": True, "transaction_id": "123"}


# Adapter makes legacy system work with new interface
class LegacyPaymentAdapter:
    """Adapts LegacyPaymentGateway to PaymentProcessor interface."""
    
    CURRENCY_CODES = {"USD": 840, "EUR": 978, "GBP": 826}

    def __init__(self, legacy_gateway: LegacyPaymentGateway) -> None:
        self._gateway = legacy_gateway

    def charge(self, amount: Decimal, currency: str) -> bool:
        # Convert to legacy format
        amount_cents = int(amount * 100)
        currency_code = self.CURRENCY_CODES.get(currency, 840)

        result = self._gateway.process_payment(amount_cents, currency_code)
        return result.get("success", False)


# Usage
legacy_gateway = LegacyPaymentGateway()
payment_processor: PaymentProcessor = LegacyPaymentAdapter(legacy_gateway)

# Now legacy system works with new code
success = payment_processor.charge(Decimal("99.99"), "USD")

Practical Exercise

Exercise 1: Apply SOLID Refactoring

# Before: Violates multiple SOLID principles
class ReportService:
    def generate_sales_report(self, start_date, end_date, format_type):
        # Fetch data (should be separate - SRP)
        connection = psycopg2.connect("...")  # Direct dependency - DIP
        cursor = connection.cursor()
        cursor.execute(f"SELECT * FROM sales WHERE date BETWEEN '{start_date}' AND '{end_date}'")
        data = cursor.fetchall()
        
        # Format report (violates OCP - must modify for new formats)
        if format_type == "pdf":
            # PDF generation logic
            pass
        elif format_type == "excel":
            # Excel generation logic
            pass
        elif format_type == "csv":
            # CSV generation logic
            pass
        
        # Send email (SRP violation)
        smtp = smtplib.SMTP("localhost")
        # Email sending logic

# After: SOLID principles applied
from abc import ABC, abstractmethod
from typing import Protocol
from datetime import date


# Abstractions
class SalesRepository(Protocol):
    def get_sales(self, start_date: date, end_date: date) -> list[Sale]:
        ...


class ReportFormatter(Protocol):
    def format(self, data: list[Sale]) -> bytes:
        ...


class NotificationService(Protocol):
    def send(self, recipient: str, subject: str, content: bytes) -> None:
        ...


# Implementations
class PostgresSalesRepository:
    def __init__(self, connection) -> None:
        self._conn = connection

    def get_sales(self, start_date: date, end_date: date) -> list[Sale]:
        # Database query logic
        pass


class PDFFormatter:
    def format(self, data: list[Sale]) -> bytes:
        # PDF generation
        pass


class ExcelFormatter:
    def format(self, data: list[Sale]) -> bytes:
        # Excel generation
        pass


class CSVFormatter:
    def format(self, data: list[Sale]) -> bytes:
        # CSV generation
        pass


class EmailNotificationService:
    def __init__(self, smtp_config) -> None:
        self._config = smtp_config

    def send(self, recipient: str, subject: str, content: bytes) -> None:
        # Email sending logic
        pass


# Clean service following SOLID
class ReportService:
    def __init__(
        self,
        repository: SalesRepository,
        formatter: ReportFormatter,
        notifier: NotificationService,
    ) -> None:
        self._repository = repository
        self._formatter = formatter
        self._notifier = notifier

    def generate_and_send(
        self,
        start_date: date,
        end_date: date,
        recipient: str,
    ) -> None:
        sales = self._repository.get_sales(start_date, end_date)
        report = self._formatter.format(sales)
        self._notifier.send(recipient, "Sales Report", report)

Exercise 2: Implement Observer Pattern

Create a task management system where multiple services react to task status changes:

# Implement these classes
class Task:
    """Observable task that notifies on status changes."""
    pass


class SlackNotifier:
    """Sends Slack notifications on task updates."""
    pass


class TimeTracker:
    """Tracks time spent on tasks."""
    pass


class TaskLogger:
    """Logs all task activities."""
    pass

SOLID Cheat Sheet

Principle	One-liner	Key Question
Single Responsibility	One class, one job	"How many reasons to change?"
Open/Closed	Extend, don't modify	"Can I add without changing?"
Liskov Substitution	Subtypes are swappable	"Can any subclass be used?"
Interface Segregation	Small, focused interfaces	"Do clients use everything?"
Dependency Inversion	Depend on abstractions	"Am I depending on concrete types?"

Key Takeaways

1. SRP makes testing easier - Small, focused classes are simple to test

2. OCP enables extensibility - Add new features without breaking existing code

3. LSP ensures reliability - Subtypes must honor base type contracts

4. ISP keeps interfaces clean - Don't force unnecessary implementations

5. DIP enables flexibility - Abstractions allow swapping implementations

What's Next?

With a solid understanding of design principles, it's time to ensure your code works correctly. In Article 6: Testing Fundamentals, we'll cover unit testing with pytest, test structure, and how to write tests that give you confidence in your code.

---

This article is part of the Software Engineering 101 series.