Abstract Base Classes and Protocols

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

Duck typing

Using an object based on the methods it has, not its class. "If it quacks like a duck…".

Abstract base class (ABC)

A class meant to be inherited from, that cannot be instantiated if abstract methods are missing.

`@abstractmethod`

Marks a method that every concrete subclass must implement.

Concrete class

A class that implements all abstract methods and can be instantiated.

Protocol

A description of required methods and signatures. A class satisfies it by having them, without inheriting.

Structural typing

Types match when their structure (methods) fits, not because of inheritance.

Nominal typing

Types match only if one inherits from the other by name.

`collections.abc`

Module of ABCs for built-in behaviours such as Sequence, Mapping and Iterable.

Fake (test double)

A simple stand-in object used in tests instead of a real, slow or paid service.

1. 1

   Finish the broken class

   In the first example give Broken an area method that returns 0, then call Broken().describe(). The error disappears because the class is now concrete.

2. 2

   Add a second fake

   In the second example write EchoClient whose complete returns the prompt in capitals, and pass it to summarise. You added a new client without touching summarise or inheriting anything.

3. 3

   Check a property of the contract

   Call isinstance(FakeClient("x"), Closeable). It is False. Add a close method to FakeClient and check again.

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

from abc import ABC, abstractmethod


class Shape(ABC):
    @abstractmethod
    def area(self):
        ...


class Square(Shape):
    pass


Square()

1. 1

   Python is built on duck typing: "if it walks like a duck and quacks like a duck, it is a duck". A function that calls thing.quack() does not check the type; any object with a quack method works. This is flexible, but a missing method is found only when the code runs (AttributeError). ABCs and protocols add a way to state and check the contract.

2. 2

   An abstract base class comes from the abc module. Inherit from ABC and mark required methods with @abstractmethod. You cannot create an object from the ABC, and you cannot create one from a subclass that has not implemented every abstract method: Python raises TypeError: Can't instantiate abstract class ... without an implementation for abstract method .... The error appears when the object is created, not later when the method is first called.

3. 3

   An ABC can also contain ordinary, finished methods that all subclasses share. The describe method in the example uses self.area(), which each subclass provides. This is the template method idea: the parent writes the steps and the children fill in the blanks.

4. 4

   The collections.abc module holds ABCs for Python's own protocols: Sequence, Mapping, Iterable, Callable. If you inherit from Sequence and write just __len__ and __getitem__, you get index, count, __contains__, __iter__ and __reversed__ for free. isinstance(x, Iterable) also works for any class that defines __iter__, with no inheritance: the ABC checks the methods.

5. 5

   A Protocol (from typing) describes a shape: class ModelClient(Protocol): def complete(self, prompt: str) -> str: ... (the ... means "body left empty on purpose"). Any class with a matching complete method fits the shape, without inheriting from ModelClient. This is structural typing: types match by structure, not by family tree. A static type checker (Phase 10) verifies it before the program runs. Python itself does not check at runtime unless you add @runtime_checkable, which allows isinstance checks of method names only (not signatures).

6. 6

   Protocols are the standard way to build swappable parts. Write your code against ModelClient. In production pass a real client; in tests pass a FakeClient that returns canned text and records the prompts. The two classes share nothing but method names. Phase 16 builds on exactly this when testing code that calls AI models.

7. 7

   Which to choose? Use a Protocol when you describe what a function needs from its arguments (especially for classes you do not own). Use an ABC when you own the family and want shared code plus a hard runtime error for incomplete subclasses. Often the simplest answer is neither: a plain function argument, as Topic 8.11 shows.

• ↔

  ABCs give an immediate, runtime error for incomplete subclasses, at the cost of forcing inheritance. They suit families you control. For classes you do not control, a Protocol fits without changes.

• ↔

  Protocols keep code flexible and testable, but are only checked by external tools. Without a type checker in your workflow, a Protocol is documentation. With one, it is a proof.

• Done when you can explain duck typing and its weak spot.

• Done when you can write an ABC with @abstractmethod and explain the TypeError for incomplete subclasses.

• Done when you can use collections.abc.Sequence to get methods for free.

• Done when you can write a Protocol and two classes that fit it without inheriting.

• Done when you can explain how a fake client makes AI code testable.