Abstract Base Classes in Python: Enforce Contracts, Not Just Code

# ============================================================
# WITHOUT ABC: Missing method discovered at call time (or never)
# ============================================================

class PaymentProcessorUnsafe:
    """Regular base class — no enforcement."""

    def charge(self, amount: float) -> bool:
        # This default implementation is a TRAP.
        # It looks like an interface but returns None silently.
        pass

    def refund(self, amount: float) -> bool:
        pass


class CryptoProcessorBroken(PaymentProcessorUnsafe):
    """Developer forgot to implement charge(). Python does not care."""

    def refund(self, amount: float) -> bool:
        print(f"Refunding ${amount} in crypto")
        return True
    # charge() is missing — but this class instantiates fine.


broken = CryptoProcessorBroken()  # No error. No warning. Nothing.
result = broken.charge(99.99)     # Calls base class method. Returns None.
print(f"Charge result: {result}")  # None
print(f"Truthiness:    {bool(result)}")  # False

# In production: if result: send_confirmation() — skipped.
# The customer's order goes through. The payment does not.

print()

# ============================================================
# WITH ABC: Missing method caught at instantiation time
# ============================================================

from abc import ABC, abstractmethod


class PaymentProcessorSafe(ABC):
    """ABC — enforces the contract. Cannot be instantiated directly."""

    @abstractmethod
    def charge(self, amount: float) -> bool:
        """Charge the customer. Must return True on success."""
        pass

    @abstractmethod
    def refund(self, amount: float) -> bool:
        """Refund the customer. Must return True on success."""
        pass


class CryptoProcessorStillBroken(PaymentProcessorSafe):
    """Same developer, same mistake — forgot charge()."""

    def refund(self, amount: float) -> bool:
        print(f"Refunding ${amount} in crypto")
        return True


# This line raises TypeError IMMEDIATELY — before any business logic runs.
try:
    broken_safe = CryptoProcessorStillBroken()
except TypeError as e:
    print(f"ABC caught the bug at instantiation time:")
    print(f"  {e}")
    print(f"  Missing methods: {PaymentProcessorSafe.__abstractmethods__}")

# The bug is caught during development, during import, during CI —
# never in production, never at 2 AM, never silently.

from abc import ABC, abstractmethod
from typing import List, Dict, Any


class ReportExporter(ABC):
    """
    ABC defining the contract for all report exporters.

    Contract:
      - file_extension (property): must return the file extension string
      - export(): must write data to a file and return the full path
      - validate_data(): must validate data before export; raise ValueError on failure

    Shared utilities:
      - get_output_filename(): builds the filename from base name and extension
      - log_export(): logs export operations (all subclasses get this for free)

    Any subclass that does not implement ALL abstract methods and properties
    will raise TypeError at instantiation time — before any data is processed.
    """

    @property
    @abstractmethod
    def file_extension(self) -> str:
        """
        Return the file extension for this exporter (e.g., 'csv', 'md', 'pdf').
        This is an abstract PROPERTY — subclasses must use @property to override.
        """
        pass

    @abstractmethod
    def export(self, data: List[Dict[str, Any]], output_path: str) -> str:
        """
        Export the report data to a file.
        Must return the absolute path to the created file.
        Must call validate_data() before writing.
        """
        pass

    @abstractmethod
    def validate_data(self, data: List[Dict[str, Any]]) -> bool:
        """
        Validate the data before exporting.
        Must raise ValueError on invalid data.
        Must return True on valid data.
        """
        pass

    # --- Concrete methods: shared utilities, free for all subclasses ---

    def get_output_filename(self, base_name: str) -> str:
        """
        Build the output filename using the subclass's file_extension property.
        All subclasses inherit this without reimplementing.
        """
        return f"{base_name}.{self.file_extension}"

    def log_export(self, path: str, row_count: int) -> None:
        """
        Standardised export logging. Every exporter logs in the same format.
        """
        print(f"[{self.__class__.__name__}] Exported {row_count} rows to {path}")


# ============================================================
# Concrete implementation: CsvExporter
# ============================================================

class CsvExporter(ReportExporter):
    """Exports reports to CSV format."""

    @property
    def file_extension(self) -> str:
        return "csv"

    def validate_data(self, data: List[Dict[str, Any]]) -> bool:
        if not data:
            raise ValueError("Cannot export empty dataset to CSV")
        if not all(isinstance(row, dict) for row in data):
            raise ValueError("All rows must be dictionaries")
        # Verify all rows have the same keys (consistent schema)
        keys = set(data[0].keys())
        for i, row in enumerate(data[1:], start=1):
            if set(row.keys()) != keys:
                raise ValueError(
                    f"Row {i} has different keys than row 0: "
                    f"expected {keys}, got {set(row.keys())}"
                )
        return True

    def export(self, data: List[Dict[str, Any]], output_path: str) -> str:
        self.validate_data(data)
        full_path = f"{output_path}/{self.get_output_filename('report')}"

        headers = list(data[0].keys())
        print(f"Writing CSV to: {full_path}")
        print(f"  Headers: {', '.join(headers)}")
        print(f"  Rows: {len(data)}")

        self.log_export(full_path, len(data))
        return full_path


# ============================================================
# Concrete implementation: MarkdownExporter
# ============================================================

class MarkdownExporter(ReportExporter):
    """Exports reports as Markdown tables."""

    @property
    def file_extension(self) -> str:
        return "md"

    def validate_data(self, data: List[Dict[str, Any]]) -> bool:
        if not data:
            raise ValueError("Cannot export empty dataset to Markdown")
        if len(data) > 1000:
            raise ValueError(
                f"Markdown export limited to 1000 rows for readability, got {len(data)}"
            )
        return True

    def export(self, data: List[Dict[str, Any]], output_path: str) -> str:
        self.validate_data(data)
        full_path = f"{output_path}/{self.get_output_filename('report')}"

        print(f"Writing Markdown table to: {full_path}")
        print(f"  Rows: {len(data)}")

        self.log_export(full_path, len(data))
        return full_path


# ============================================================
# Broken implementation: demonstrates ABC enforcement
# ============================================================

class BrokenExporter(ReportExporter):
    """Forgot to implement validate_data() and file_extension."""

    def export(self, data: List[Dict[str, Any]], output_path: str) -> str:
        return f"{output_path}/report.broken"


# ============================================================
# Plugin loader: trusts the ABC contract blindly
# ============================================================

def run_export(exporter: ReportExporter, data: List[Dict], path: str) -> None:
    """
    Accepts ANY ReportExporter. Does not check which concrete class it is.
    The ABC guarantees .export(), .validate_data(), and .file_extension exist.
    """
    print(f"\nUsing exporter: {exporter.__class__.__name__} (.{exporter.file_extension})")
    output = exporter.export(data, path)
    print(f"Export complete: {output}")


# Sample data
sales_data = [
    {"product": "Widget A", "units_sold": 120, "revenue": 2400.00},
    {"product": "Widget B", "units_sold": 85,  "revenue": 3400.00},
    {"product": "Gadget X", "units_sold": 200, "revenue": 9800.00},
]

# These work — both satisfy the ABC contract
run_export(CsvExporter(), sales_data, "/tmp/reports")
run_export(MarkdownExporter(), sales_data, "/tmp/reports")

# This fails at instantiation — ABC catches the missing methods
print("\n--- Attempting to instantiate BrokenExporter ---")
try:
    run_export(BrokenExporter(), sales_data, "/tmp/reports")
except TypeError as e:
    print(f"ABC enforcement: {e}")
    print(f"Missing methods: {ReportExporter.__abstractmethods__}")

from abc import ABC, abstractmethod


class Serializable(ABC):
    """ABC representing anything that can be serialized to a string."""

    @abstractmethod
    def serialize(self) -> str:
        """Convert this object to a string representation."""
        pass


class LegacyDataRecord:
    """
    This class was written before Serializable existed.
    It lives in a third-party library we cannot modify.
    But it does implement serialize() — so logically it qualifies.
    """

    def __init__(self, source: str, data: str):
        self.source = source
        self.data = data

    def serialize(self) -> str:
        return f'{{"source": "{self.source}", "data": "{self.data}"}}'


class LegacyRecordWithoutSerialize:
    """
    This class does NOT implement serialize().
    Registering it is a mistake — but Python will not stop you.
    """

    def __init__(self, value: int):
        self.value = value


# Register the legacy class as a virtual subclass of Serializable.
# This tells Python's ABC machinery that LegacyDataRecord honours
# the Serializable contract — purely a type declaration.
Serializable.register(LegacyDataRecord)

# DANGER: We can also register a class that does NOT implement serialize().
# Python does not check. register() is trust-based, not validated.
Serializable.register(LegacyRecordWithoutSerialize)


# --- Demonstrate the behaviour ---

legacy_good = LegacyDataRecord("legacy_system", "opaque_blob")
legacy_bad = LegacyRecordWithoutSerialize(42)

print("=== isinstance() checks ===")
print(f"LegacyDataRecord is Serializable?          {isinstance(legacy_good, Serializable)}")
print(f"LegacyRecordWithoutSerialize is Serializable? {isinstance(legacy_bad, Serializable)}")

print(f"\n=== __subclasses__() — only REAL subclasses, not registered ===")
print(f"Serializable.__subclasses__(): {Serializable.__subclasses__()}")
# Empty — registered classes do not appear in __subclasses__()

print(f"\n=== Calling serialize() ===")
print(f"Good legacy record: {legacy_good.serialize()}")

try:
    legacy_bad.serialize()
except AttributeError as e:
    print(f"Bad legacy record: AttributeError — {e}")
    print("  register() did NOT verify that serialize() exists.")
    print("  isinstance() returns True, but the method is missing.")

print(f"\n=== Key insight ===")
print("register() is a type tag for isinstance() — NOT a validation mechanism.")
print("Use it only for code you cannot modify that genuinely implements the interface.")
print("Always write a test that calls each abstract method after registering.")