Abstract base classes and protocols

When several classes should be usable in the same place, the code that uses them needs to know what they have in common. That shared promise is an interface: a set of methods and what they mean. Python offers three ways to express one, from the loosest to the strictest.

Duck typing

If it walks like a duck and quacks like a duck, treat it as a duck. Python does not ask for a family tree. A function simply calls the method it needs:

class Duck:
    def speak(self):
        return "Quack"


class Robot:
    def speak(self):
        return "Beep"


def announce(thing):
    print(thing.speak())


announce(Duck())
announce(Robot())

Quack
Beep

Duck and Robot share no parent. announce works with both because both have a speak method. This is duck typing, and it is how most Python code is written. It needs no ceremony, and it is the reason the language feels flexible.

The cost is that mistakes surface late, when the call is made:

class Stone:
    pass


def announce(thing):
    print(thing.speak())


try:
    announce(Stone())
except AttributeError as error:
    print("AttributeError:", error)

AttributeError: 'Stone' object has no attribute 'speak'

Nothing told the author of Stone that speak was expected. The next two tools make the expectation explicit, one at run time and one for type checkers.

Abstract base classes

An abstract base class (ABC) is a parent class that declares methods its subclasses must provide. Inherit from ABC and mark each required method with @abstractmethod:

from abc import ABC, abstractmethod


class Shape(ABC):
    @abstractmethod
    def area(self):
        """Return the area as a number."""


class Square(Shape):
    def __init__(self, side):
        self.side = side

    def area(self):
        return self.side**2


try:
    Shape()
except TypeError:
    print("TypeError: cannot create an abstract Shape")
print(Square(3).area())
print(isinstance(Square(3), Shape))

TypeError: cannot create an abstract Shape
9
True

Shape cannot be instantiated, because it is incomplete. Square supplies area, so it is concrete and works normally. Because Square inherits from Shape, isinstance(Square(3), Shape) is True. The body of the abstract method is only a docstring, which says what implementers should do.

The wording of the TypeError message varies between Python versions, so the examples catch the exception type and print their own text.

The check happens when you create an instance. A subclass that forgets one of the required methods stays abstract:

from abc import ABC, abstractmethod


class Shape(ABC):
    @abstractmethod
    def area(self):
        """Return the area as a number."""

    @abstractmethod
    def perimeter(self):
        """Return the perimeter as a number."""


class Square(Shape):
    def __init__(self, side):
        self.side = side

    def area(self):
        return self.side**2


try:
    Square(3)
except TypeError:
    print("TypeError: Square is still abstract")
print(sorted(Shape.__abstractmethods__))

TypeError: Square is still abstract
['area', 'perimeter']

Square implemented area but not perimeter, so Square(3) failed, before any method could be called with half a class. The set __abstractmethods__ lists what is still missing. This is the main benefit over duck typing: the error comes at the moment of creation, and it names the missing piece.

Abstract and concrete together

An ABC can mix abstract methods with ordinary ones. The ordinary methods are written once and use the abstract ones, which gives you a fixed procedure with steps the subclasses fill in:

from abc import ABC, abstractmethod


class Report(ABC):
    @abstractmethod
    def body(self):
        """Return the report text."""

    def render(self):
        return f"=== report ===\n{self.body()}\n=== end ==="


class SalesReport(Report):
    def body(self):
        return "sales: 42"


print(SalesReport().render())

=== report ===
sales: 42
=== end ===

Marking implementations with @override

The @override decorator from the inheritance lesson fits naturally here: it states that a method implements something from the parent, and a type checker confirms that the parent has it. 3.12+Requires version 3.12 or later

from abc import ABC, abstractmethod
from typing import override


class Greeter(ABC):
    @abstractmethod
    def greet(self, name):
        """Return a greeting."""


class Formal(Greeter):
    @override
    def greet(self, name):
        return f"Good day, {name}."


print(Formal().greet("Asha"))

Good day, Asha.

Protocols: interfaces without inheritance

An ABC forces every implementer to inherit from it. That is a problem when the class comes from a library you cannot change, or when you would rather not tie unrelated classes to a shared parent. A protocol describes the required methods, and any class that has them counts as a match, with no inheritance at all. typing.Protocol arrived in Python 3.8, so every supported version has it.

from typing import Protocol


class Drawable(Protocol):
    def draw(self) -> str: ...


class Circle:
    def draw(self) -> str:
        return "()"


class Label:
    def __init__(self, text):
        self.text = text

    def draw(self) -> str:
        return f"[{self.text}]"


def render(items: list[Drawable]) -> str:
    return " ".join(item.draw() for item in items)


print(render([Circle(), Label("hi"), Circle()]))

() [hi] ()

Three things are new here:

• class Drawable(Protocol) declares the shape. The method body is ..., the literal Ellipsis, which is a conventional “nothing here” for a signature.
• -> str and list[Drawable] are type hints, which you met in the type hints lesson. They tell readers and checkers what to expect.
• Circle and Label never mention Drawable. They match because they have a draw method with a compatible signature.

At run time, Python does not check any of this. The script above would run identically with no annotations at all. The value comes from a type checker such as mypy or pyright: pass an object without a draw method to render, and it reports the mistake before the program runs. A protocol is, in effect, a duck-typing promise that tools can verify.

Checking at run time

A normal protocol cannot be used with isinstance. Decorate it with @runtime_checkable when you need that:

import io
from typing import Protocol, runtime_checkable


@runtime_checkable
class Closeable(Protocol):
    def close(self) -> None: ...


class Connection:
    def close(self) -> None:
        print("closed")


class Brick:
    pass


print(isinstance(Connection(), Closeable))
print(isinstance(Brick(), Closeable))
print(isinstance(io.StringIO(), Closeable))

True
False
True

The check is shallow. It confirms that the names exist, and nothing more:

from typing import Protocol, runtime_checkable


@runtime_checkable
class Closeable(Protocol):
    def close(self) -> None: ...


class Odd:
    def close(self, a, b, c):  # wrong shape, right name
        return "not what the protocol described"


print(isinstance(Odd(), Closeable))

True

Odd.close takes three required arguments, which does not match the protocol, but isinstance said True because it only looked for the name close. Treat the run-time check as a convenience, and leave the full verification to the type checker.

ABC or Protocol?

Choose an ABC when you control the classes and want Python to refuse incomplete ones, or when you have shared behaviour to inherit. Choose a Protocol when you describe what a function needs from its arguments, especially for code that accepts types from several sources. Plain duck typing remains a good default for small programs.

Common pitfalls

Forgetting ABC. Using @abstractmethod in a class that does not inherit from ABC enforces nothing, and you can instantiate it freely. The parent must be ABC, or have ABCMeta as its metaclass.

Expecting a Protocol to be enforced at run time. Calling render with a non-drawable raises AttributeError when .draw() is reached, as with any duck-typed code. Only a type checker reports it earlier.

Over-abstracting. An interface with one implementation, or an ABC for a hierarchy of two classes, adds files and names for no gain. Add the abstraction when the second or third implementation appears.

Putting logic in the abstract method body and not calling it. An abstract method can have a body, but subclasses must call it explicitly with super().method() to run it. Most abstract methods are better left as a docstring.

upper: HELLO
reverse: OLLEH
OLLEH
Plugin is abstract

from abc import ABC, abstractmethod


class Plugin(ABC):
    name = "plugin"

    @abstractmethod
    def run(self, text):
        """Return the transformed text."""


class Upper(Plugin):
    name = "upper"

    def run(self, text):
        return text.upper()


class Reverse(Plugin):
    name = "reverse"

    def run(self, text):
        return text[::-1]


def apply_all(plugins, text):
    for plugin in plugins:
        text = plugin.run(text)
        print(f"{plugin.name}: {text}")
    return text


result = apply_all([Upper(), Reverse()], "hello")
print(result)
try:
    Plugin()
except TypeError:
    print("Plugin is abstract")

upper: HELLO
reverse: OLLEH
OLLEH
Plugin is abstract

1,pen
2,ink
2 rows

from typing import Protocol


class Exporter(Protocol):
    def export(self, rows: list[dict]) -> str: ...


class CsvExporter:
    def export(self, rows: list[dict]) -> str:
        lines = [",".join(str(v) for v in row.values()) for row in rows]
        return "\n".join(lines)


class CountExporter:
    def export(self, rows: list[dict]) -> str:
        return f"{len(rows)} rows"


def save(exporter: Exporter, rows: list[dict]) -> None:
    print(exporter.export(rows))


rows = [{"id": 1, "name": "pen"}, {"id": 2, "name": "ink"}]
save(CsvExporter(), rows)
save(CountExporter(), rows)

1,pen
2,ink
2 rows

from abc import ABC, abstractmethod


class Animal(ABC):
    @abstractmethod
    def speak(self):
        pass

    @abstractmethod
    def move(self):
        pass


class Fish(Animal):
    def move(self):
        return "swim"


class Dog(Fish):
    def speak(self):
        return "woof"


for cls in [Fish, Dog]:
    try:
        animal = cls()
        print(cls.__name__, animal.speak(), animal.move())
    except TypeError:
        print(cls.__name__, "is abstract")

Fish is abstract
Dog woof swim

Summary

• An interface is the set of methods other code relies on. Duck typing leaves it implicit, and ABCs and Protocols make it explicit.
• An ABC inherits from ABC and marks required methods with @abstractmethod. Python refuses to create an instance while any remain unimplemented.
• A typing.Protocol lists the methods a function expects. Classes match by having them, with no inheritance, and a type checker verifies it.
• @runtime_checkable allows isinstance on a protocol, but it only checks that the names exist.
• @override 3.12+Requires version 3.12 or later can mark the methods that implement an abstract one.
• Use an ABC when you control the classes and want enforcement or shared code. Use a Protocol to describe requirements on code you do not control.
• Going further: the advanced lesson Protocols and structural typing goes deeper into how Protocols are matched and checked.