Protocols and Structural Typing

18 min · Intermediate

Python programs rely on duck typing: if it has a pay method, it can pay. Protocols let you write that rule in a type hint, so a checker can confirm it before the program runs.

Duck typing needs a name

Protocol is a class that lists the methods and attributes an object must have. Any class that has them matches the protocol, with no inheritance needed.

Python code often accepts "anything that can do this", such as anything with a pay method. A protocol writes that rule down so a checker can verify it.

Python

from typing import Protocol
class Payable(Protocol):    def pay(self, amount: float) -> str: ...

The ... body means "no code here". A protocol lists methods and attributes. It is never used to build objects.

Matching by shape

Structural typing means a type matches by its shape, the methods and attributes it has, not by its parent classes. It is duck typing that a checker can verify.

A class matches a protocol just by having the right methods. It never names the protocol or inherits from it.

Python

1class Card:2    def pay(self, amount: float) -> str:3        return f"Card paid {amount}"4
5def checkout(method: Payable, amount: float) -> str:6    return method.pay(amount)

A Payable protocol needs a pay method. Card has pay, so it matches. Cash only has collect, so it does not match. Matching is by shape, with no inheritance.

Example 1 · Two classes, one protocol

Python

1from typing import Protocol2
3class Payable(Protocol):4    def pay(self, amount: float) -> str: ...5
6class Card:7    def pay(self, amount: float) -> str:8        return f"Card paid {amount}"9
10class Wallet:11    def pay(self, amount: float) -> str:12        return f"Wallet paid {amount}"13
14def checkout(method: Payable, amount: float) -> str:15    return method.pay(amount)16
17for method in (Card(), Wallet()):18    print(checkout(method, 50.0))

Output

Card paid 50.0
Wallet paid 50.0

What this code does

Card and Wallet share no parent, yet both fit Payable.
Adding a new payment class later needs no change to checkout.

Example 2 · mypy rejects a class with the wrong shape

Runs in: Your terminal

Terminal

mypy checkout.py

Output

checkout.py:23: error: Argument 1 to "checkout" has incompatible type "Cash"; expected "Payable"  [arg-type]
Found 1 error in 1 file (checked 1 source file)

What this code does

Cash has collect, not pay, so mypy rejects the second call.
Running the file would also fail, but only when that line is reached. mypy finds it first.

Card never mentions Payable, yet checkout(Card(), 50.0) passes the check. A class with no pay method would be rejected.

Attributes in a protocol

A protocol can also list attributes. Any object that has an attribute with that name and type matches.

Python

class HasName(Protocol):    name: str
def greet(thing: HasName) -> str:    return f"Hello, {thing.name}"

Example 3 · A protocol for an attribute

Python

1from typing import Protocol2
3class HasName(Protocol):4    name: str5
6class Student:7    def __init__(self, name: str) -> None:8        self.name = name9
10class Course:11    def __init__(self, name: str, fee: int) -> None:12        self.name = name13        self.fee = fee14
15def greet(thing: HasName) -> str:16    return f"Hello, {thing.name}"17
18print(greet(Student("Asha")))19print(greet(Course("Python", 4000)))

Output

Hello, Asha
Hello, Python

What this code does

greet needs only a name. It does not care about fee.
Both classes match, though they are unrelated.

A student, a course and a customer can all be passed to greet, as long as each one has a name string. This keeps the function from depending on any one class.

Protocol or abstract base class

An abstract base class forces a class to inherit and to fill in every method. A protocol asks for no inheritance and is checked only by tools such as mypy.

Python

1from abc import ABC, abstractmethod2
3class PayableBase(ABC):4    @abstractmethod5    def pay(self, amount: float) -> str: ...6
7class Broken(PayableBase):8    pass

Example 4 · An abstract class fails at runtime

Python

1from abc import ABC, abstractmethod2
3class PayableBase(ABC):4    @abstractmethod5    def pay(self, amount: float) -> str: ...6
7class Broken(PayableBase):8    pass9
10try:11    Broken()12except TypeError as error:13    print(error)

Output

Can't instantiate abstract class Broken without an implementation for abstract method 'pay'

What this code does

The abstract base class stops the object from being built at all.
A protocol gives no such runtime error. Its check happens in mypy.

Creating Broken() fails at runtime, because pay is missing. Use a protocol for code you do not own, or when a shared parent is not wanted. Use an abstract base class when you also want shared code and a runtime error.

Checking a protocol at runtime

runtime_checkable is a decorator that lets isinstance and issubclass test an object against a protocol. It checks only that the named methods exist.

A plain protocol cannot be used with isinstance. Add @runtime_checkable when you need that. It only checks that the names exist, not their signatures.

Python

1import io2from typing import Protocol, runtime_checkable3
4@runtime_checkable5class Closeable(Protocol):6    def close(self) -> None: ...7
8print(isinstance(io.StringIO(), Closeable))

Example 5 · runtime_checkable

Python

1import io2from typing import Protocol, runtime_checkable3
4@runtime_checkable5class Closeable(Protocol):6    def close(self) -> None: ...7
8print(isinstance(io.StringIO(), Closeable))9print(isinstance(42, Closeable))

Output

True
False

What this code does

A StringIO has a close method, so it matches.
An int does not. Only the method name is tested, not its arguments or return type.

Use this sparingly. The strength of a protocol is the static check before the program runs.

Next step

Check your understanding

11 quick questions

Duck typing needs a name

Protocol is a class that lists the methods and attributes an object must have. Any class that has them matches the protocol, with no inheritance needed.

Python code often accepts "anything that can do this", such as anything with a pay method. A protocol writes that rule down so a checker can verify it.

1from typing import Protocol2 3class Payable(Protocol):4 def pay(self, amount: float) -> str: ...5 6class Card:7 def pay(self, amount: float) -> str:8 return f"Card paid {amount}"9 10class Wallet:11 def pay(self, amount: float) -> str:12 return f"Wallet paid {amount}"13 14def checkout(method: Payable, amount: float) -> str:15 return method.pay(amount)16 17for method in (Card(), Wallet()):18 print(checkout(method, 50.0))

1from typing import Protocol2 3class HasName(Protocol):4 name: str5 6class Student:7 def __init__(self, name: str) -> None:8 self.name = name9 10class Course:11 def __init__(self, name: str, fee: int) -> None:12 self.name = name13 self.fee = fee14 15def greet(thing: HasName) -> str:16 return f"Hello, {thing.name}"17 18print(greet(Student("Asha")))19print(greet(Course("Python", 4000)))

1from abc import ABC, abstractmethod2 3class PayableBase(ABC):4 @abstractmethod5 def pay(self, amount: float) -> str: ...6 7class Broken(PayableBase):8 pass9 10try:11 Broken()12except TypeError as error:13 print(error)

1import io2from typing import Protocol, runtime_checkable3 4@runtime_checkable5class Closeable(Protocol):6 def close(self) -> None: ...7 8print(isinstance(io.StringIO(), Closeable))9print(isinstance(42, Closeable))