Abstract Classes in Python Explained — Why, When, and How to Use Them

# ── PART 1: The problem — a regular base class with no enforcement ──

class Notifier:
    """A base class that INTENDS subclasses to override send().
       But Python has no way to enforce that intent here."""

    def send(self, message: str) -> None:
        # This does nothing, but Python won't complain if a subclass skips it
        pass


class EmailNotifier(Notifier):
    def send(self, message: str) -> None:
        print(f"[EMAIL] Sending: {message}")


class SlackNotifier(Notifier):
    # Oops — developer forgot to implement send()
    # No error raised anywhere during class definition
    pass


# Both can be instantiated without complaint
email = EmailNotifier()
slack = SlackNotifier()   # ← Should fail, but doesn't

email.send("Server is down!")   # Works correctly
slack.send("Server is down!")   # Silently does NOTHING — the bug hides here

from abc import ABC, abstractmethod
from datetime import datetime


class Notifier(ABC):  # Inherit from ABC to activate the enforcement machinery
    """Abstract base class for all notification channels.

    Any concrete subclass MUST implement both send() and channel_name.
    Failing to do so raises TypeError at instantiation — not at call time.
    """

    @abstractmethod
    def send(self, message: str, recipient: str) -> bool:
        """Send a message to a recipient.

        Returns True if delivery succeeded, False otherwise.
        Subclasses must override this — but they can still call super()
        to get the timestamp logging for free.
        """
        # Providing a body in an abstract method is legal.
        # Subclasses can call super().send() to reuse this shared logic.
        print(f"  [BASE LOG] Dispatch attempted at {datetime.now().strftime('%H:%M:%S')}")
        return False  # Subclass should override the return value

    @property
    @abstractmethod
    def channel_name(self) -> str:
        """Every notifier must declare its human-readable channel name."""
        ...


# ── Concrete implementation 1: Email ──
class EmailNotifier(Notifier):

    @property
    def channel_name(self) -> str:
        return "Email"  # Satisfies the abstract property

    def send(self, message: str, recipient: str) -> bool:
        super().send(message, recipient)  # Calls the base body for logging
        print(f"  [{self.channel_name}] To: {recipient} | Message: {message}")
        return True


# ── Concrete implementation 2: SMS ──
class SMSNotifier(Notifier):

    @property
    def channel_name(self) -> str:
        return "SMS"

    def send(self, message: str, recipient: str) -> bool:
        super().send(message, recipient)
        truncated = message[:160]  # SMS has a 160-char limit
        print(f"  [{self.channel_name}] To: {recipient} | Message: {truncated}")
        return True


# ── Broken implementation: SlackNotifier forgets send() ──
class SlackNotifier(Notifier):
    @property
    def channel_name(self) -> str:
        return "Slack"
    # send() is NOT implemented — Python will refuse to instantiate this


# ── Test drive ──
print("=== Creating notifiers ===")
email_notifier = EmailNotifier()
sms_notifier = SMSNotifier()

print("\n=== Sending notifications ===")
email_notifier.send("Deployment complete.", "alice@example.com")
sms_notifier.send("Your OTP is 482910.", "+14155550123")

print("\n=== Attempting to instantiate incomplete SlackNotifier ===")
try:
    slack_notifier = SlackNotifier()  # ← This will blow up immediately
except TypeError as error:
    print(f"Caught expected error: {error}")

# ── You also cannot instantiate the abstract base itself ──
print("\n=== Attempting to instantiate the abstract base ===")
try:
    generic_notifier = Notifier()
except TypeError as error:
    print(f"Caught expected error: {error}")

from abc import ABC, abstractmethod
from dataclasses import dataclass
from typing import Optional


@dataclass
class PaymentResult:
    """A simple value object representing the outcome of a payment operation."""
    success: bool
    transaction_id: Optional[str]
    error_message: Optional[str] = None


class PaymentProcessor(ABC):
    """Abstract contract every payment provider must honour.

    This class defines the full payment lifecycle: authorise → capture → refund.
    Business logic anywhere in the app can depend on this contract without
    caring which payment provider is wired in at runtime.
    """

    def __init__(self, api_key: str, sandbox_mode: bool = True):
        # Shared setup lives here — every processor needs these
        self._api_key = api_key
        self._sandbox = sandbox_mode
        self._transaction_log: list[str] = []

    @abstractmethod
    def authorise(self, amount_pence: int, currency: str) -> PaymentResult:
        """Reserve funds on the customer's card without capturing yet."""
        ...

    @abstractmethod
    def capture(self, transaction_id: str) -> PaymentResult:
        """Collect the previously authorised funds."""
        ...

    @abstractmethod
    def refund(self, transaction_id: str, amount_pence: int) -> PaymentResult:
        """Return funds to the customer for a completed transaction."""
        ...

    @classmethod
    @abstractmethod
    def from_environment(cls) -> "PaymentProcessor":
        """Factory method — each provider knows where its own config lives."""
        ...

    # ── Non-abstract method — shared behaviour all processors inherit ──
    def log_transaction(self, transaction_id: str, action: str) -> None:
        """Appends a human-readable record. Not abstract — subclasses get this free."""
        entry = f"{action.upper()} | txn={transaction_id} | sandbox={self._sandbox}"
        self._transaction_log.append(entry)
        print(f"  [AUDIT] {entry}")

    def get_transaction_log(self) -> list[str]:
        return list(self._transaction_log)  # Return a copy to protect the internal state


# ── Concrete implementation: Stripe ──
class StripeProcessor(PaymentProcessor):

    @classmethod
    def from_environment(cls) -> "StripeProcessor":
        # In real life you'd read os.environ['STRIPE_API_KEY'] here
        return cls(api_key="sk_test_stripe_fake_key", sandbox_mode=True)

    def authorise(self, amount_pence: int, currency: str) -> PaymentResult:
        # Simulating a Stripe API call — real code would use the stripe SDK
        print(f"  [Stripe] Authorising {amount_pence}p {currency}...")
        fake_txn_id = f"pi_stripe_{amount_pence}"
        self.log_transaction(fake_txn_id, "authorise")
        return PaymentResult(success=True, transaction_id=fake_txn_id)

    def capture(self, transaction_id: str) -> PaymentResult:
        print(f"  [Stripe] Capturing {transaction_id}...")
        self.log_transaction(transaction_id, "capture")
        return PaymentResult(success=True, transaction_id=transaction_id)

    def refund(self, transaction_id: str, amount_pence: int) -> PaymentResult:
        print(f"  [Stripe] Refunding {amount_pence}p on {transaction_id}...")
        self.log_transaction(transaction_id, "refund")
        return PaymentResult(success=True, transaction_id=f"re_{transaction_id}")


# ── Concrete implementation: PayPal ──
class PayPalProcessor(PaymentProcessor):

    @classmethod
    def from_environment(cls) -> "PayPalProcessor":
        return cls(api_key="paypal_sandbox_fake_key", sandbox_mode=True)

    def authorise(self, amount_pence: int, currency: str) -> PaymentResult:
        print(f"  [PayPal] Creating order for {amount_pence}p {currency}...")
        fake_txn_id = f"ORDER-paypal-{amount_pence}"
        self.log_transaction(fake_txn_id, "authorise")
        return PaymentResult(success=True, transaction_id=fake_txn_id)

    def capture(self, transaction_id: str) -> PaymentResult:
        print(f"  [PayPal] Approving order {transaction_id}...")
        self.log_transaction(transaction_id, "capture")
        return PaymentResult(success=True, transaction_id=transaction_id)

    def refund(self, transaction_id: str, amount_pence: int) -> PaymentResult:
        print(f"  [PayPal] Issuing refund of {amount_pence}p on {transaction_id}...")
        self.log_transaction(transaction_id, "refund")
        return PaymentResult(success=True, transaction_id=f"REF-{transaction_id}")


# ── Business logic that works against the CONTRACT, not the implementation ──
def checkout_service(processor: PaymentProcessor, cart_total_pence: int) -> None:
    """This function has zero knowledge of Stripe, PayPal, or any provider.
       It only knows it received something that satisfies the PaymentProcessor contract.
    """
    print(f"\n--- Checkout: processing {cart_total_pence}p ---")

    auth_result = processor.authorise(cart_total_pence, "GBP")
    if not auth_result.success:
        print(f"Authorisation failed: {auth_result.error_message}")
        return

    capture_result = processor.capture(auth_result.transaction_id)
    if capture_result.success:
        print(f"Payment complete! Transaction: {capture_result.transaction_id}")
    else:
        print(f"Capture failed: {capture_result.error_message}")


# ── Wire it together ──
stripe = StripeProcessor.from_environment()
paypal = PayPalProcessor.from_environment()

checkout_service(stripe, 4999)   # £49.99 via Stripe
checkout_service(paypal, 1250)   # £12.50 via PayPal

print("\n--- Stripe audit log ---")
for entry in stripe.get_transaction_log():
    print(f"  {entry}")

# Demonstrating Python Protocols as an alternative to ABC
# for pure interface contracts (no shared state, no shared behaviour)

from typing import Protocol, runtime_checkable


@runtime_checkable  # Allows isinstance() checks against the protocol
class Serialisable(Protocol):
    """Any class that has to_json() and from_json() satisfies this protocol.
       No inheritance required — this is structural (duck-typed) typing.
    """

    def to_json(self) -> str:
        ...

    @classmethod
    def from_json(cls, json_string: str) -> "Serialisable":
        ...


import json


class UserProfile:
    """UserProfile satisfies Serialisable WITHOUT explicitly inheriting from it.
       Python checks the shape, not the family tree.
    """

    def __init__(self, username: str, email: str):
        self.username = username
        self.email = email

    def to_json(self) -> str:
        # Converts the instance to a JSON string
        return json.dumps({"username": self.username, "email": self.email})

    @classmethod
    def from_json(cls, json_string: str) -> "UserProfile":
        data = json.loads(json_string)
        return cls(username=data["username"], email=data["email"])


def save_to_cache(item: Serialisable, cache_key: str) -> None:
    """Accepts anything that looks like a Serialisable — no ABC needed here."""
    serialised = item.to_json()
    print(f"  [CACHE] Saving to key '{cache_key}': {serialised}")


profile = UserProfile(username="ada_lovelace", email="ada@babbage.io")

print(f"Is UserProfile an instance of Serialisable? {isinstance(profile, Serialisable)}")
save_to_cache(profile, "user:ada_lovelace")

roundtripped = UserProfile.from_json(profile.to_json())
print(f"Round-tripped username: {roundtripped.username}")