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

# Without ABCs — the silent bug problem

class PaymentProcessor:
    """Base class for all payment processors."""

    def charge(self, amount: float, currency: str) -> bool:
        """Charge the customer. Must be implemented by subclasses."""
        # This is just a placeholder — it does NOTHING useful
        pass

    def refund(self, transaction_id: str) -> bool:
        """Refund a previous charge. Must be implemented by subclasses."""
        pass


class CryptoProcessor(PaymentProcessor):
    """Handles crypto payments — but the developer forgot to implement charge()."""

    def refund(self, transaction_id: str) -> bool:
        print(f"Refunding crypto transaction {transaction_id}")
        return True

    # charge() is NOT implemented — Python doesn't care, yet


# This line works fine — no errors at instantiation
crypto = CryptoProcessor()

# The bug is invisible until this exact moment in production:
result = crypto.charge(99.99, "USD")  # Returns None silently — disaster
print(f"Charge result: {result}")     # Prints None instead of raising an error

from abc import ABC, abstractmethod
from datetime import datetime


class PaymentProcessor(ABC):
    """
    Abstract base class that defines the CONTRACT every payment processor must honour.
    This class itself cannot be instantiated — it's a blueprint only.
    """

    @abstractmethod
    def charge(self, amount: float, currency: str) -> bool:
        """
        Charge a customer for a given amount.
        Every concrete subclass MUST implement this method.
        """
        pass  # No implementation here — subclasses must provide it

    @abstractmethod
    def refund(self, transaction_id: str) -> bool:
        """
        Refund a previous transaction.
        Every concrete subclass MUST implement this method.
        """
        pass

    def log_transaction(self, action: str, amount: float) -> None:
        """
        NOT abstract — this is shared behaviour all processors get for free.
        Concrete methods in an ABC work just like regular methods.
        """
        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
        print(f"[{timestamp}] {action}: ${amount:.2f} via {self.__class__.__name__}")


class CreditCardProcessor(PaymentProcessor):
    """Concrete implementation for credit card payments."""

    def charge(self, amount: float, currency: str) -> bool:
        # Simulate charging the credit card
        self.log_transaction("CHARGE", amount)  # Uses the inherited concrete method
        print(f"  -> Credit card charged {amount} {currency}")
        return True

    def refund(self, transaction_id: str) -> bool:
        print(f"  -> Credit card refund issued for transaction {transaction_id}")
        return True


class CryptoProcessor(PaymentProcessor):
    """This class forgets to implement charge() — watch what happens."""

    def refund(self, transaction_id: str) -> bool:
        print(f"  -> Crypto refund issued for {transaction_id}")
        return True

    # charge() is still missing — but now Python will CATCH this


# --- Test the contract enforcement ---

# This works perfectly — CreditCardProcessor implements all abstract methods
cc_processor = CreditCardProcessor()
cc_processor.charge(149.99, "USD")
cc_processor.refund("TXN-2024-001")

print()

# This will FAIL immediately at instantiation — before any charge() is called
try:
    broken_processor = CryptoProcessor()  # TypeError fires right here
except TypeError as contract_violation:
    print(f"Contract violation caught: {contract_violation}")

# You can also check if a class is abstract before instantiating
print(f"\nPaymentProcessor is abstract: {PaymentProcessor.__abstractmethods__}")

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


class ReportExporter(ABC):
    """
    ABC that defines the contract for any report export plugin.
    Third-party developers implement this to add new export formats.
    """

    @property
    @abstractmethod
    def file_extension(self) -> str:
        """
        Subclasses MUST define this as a property.
        Using @property + @abstractmethod enforces that it's accessed like .file_extension
        not as a method call like .file_extension()
        """
        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.
        """
        pass

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

    def get_output_filename(self, base_name: str) -> str:
        """
        Concrete helper method — builds the output filename using the
        subclass's file_extension property. Free for all subclasses to use.
        """
        return f"{base_name}.{self.file_extension}"


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

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

    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")
        return True

    def export(self, data: List[Dict[str, Any]], output_path: str) -> str:
        self.validate_data(data)  # Always validate before exporting

        # Simulate writing to CSV
        headers = list(data[0].keys())
        full_path = f"{output_path}/{self.get_output_filename('report')}"

        print(f"Writing CSV to: {full_path}")
        print(f"  Headers: {', '.join(headers)}")
        print(f"  Rows written: {len(data)}")

        return full_path


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 len(data) > 1000:
            raise ValueError("Markdown export limited to 1000 rows for readability")
        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 written: {len(data)}")

        return full_path


# --- Simulated plugin loader ---

def run_export(exporter: ReportExporter, data: List[Dict], path: str) -> None:
    """
    This function accepts ANY ReportExporter — it doesn't care which concrete
    class it is, because the ABC guarantees .export() and .validate_data() exist.
    """
    print(f"Using exporter: {exporter.__class__.__name__} (.{exporter.file_extension})")
    output = exporter.export(data, path)
    print(f"Export complete: {output}\n")


# Sample sales report 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},
]

# Works with any exporter that satisfies the ReportExporter contract
run_export(CsvExporter(), sales_data, "/tmp/reports")
run_export(MarkdownExporter(), sales_data, "/tmp/reports")

from abc import ABC, abstractmethod


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

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


class LegacyDataRecord:
    """
    This class was written before Serializable existed.
    We can't modify it — it's from a third-party library.
    But it does implement serialize() — so logically it qualifies.
    """

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


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


# Now isinstance() recognises LegacyDataRecord as Serializable
legacy_record = LegacyDataRecord()

print(f"Is LegacyDataRecord a Serializable? {isinstance(legacy_record, Serializable)}")
print(f"Is it in the MRO? {LegacyDataRecord in Serializable.__subclasses__()}")
print(f"But __abstractmethods__ is NOT enforced for registered classes: {legacy_record.serialize()}")

# KEY INSIGHT: register() does NOT enforce the abstract methods — it's purely a type tag.
# If LegacyDataRecord didn't have serialize(), isinstance() would still return True.
# That's intentional for working with legacy code, but it's a gotcha to know.