Chapter 19 — Protocols and Structural Subtyping

1. Opening problem

A service needs an object that can send a message.

Nominal design:

class MessageSenderBase:
    def send(
        self,
        recipient: str,
        message: str,
    ) -> None:
        raise NotImplementedError

Every implementation must inherit from the base.

Structural design:

from typing import Protocol


class MessageSender(
    Protocol
):
    def send(
        self,
        recipient: str,
        message: str,
    ) -> None:
        ...

Any object with a compatible send method satisfies the protocol statically, even without inheritance.

This is static duck typing.

---

2. Nominal versus structural subtyping

Nominal subtyping asks:

Did the class explicitly inherit or declare a relationship?

Structural subtyping asks:

Does the object provide the required shape and behavior?

TypeScript interfaces are structurally typed.

Python protocols bring a similar concept to static analysis while preserving Python's runtime duck-typing tradition.

Example implementation:

class EmailSender:
    def send(
        self,
        recipient: str,
        message: str,
    ) -> None:
        ...

No protocol inheritance is required.

def notify(
    sender: MessageSender,
) -> None:
    sender.send(
        "steve@example.com",
        "Welcome",
    )

A type checker accepts EmailSender when its method is compatible.

---

3. Small protocols

Good:

class SupportsClose(
    Protocol
):
    def close(self) -> None:
        ...

Potentially excessive:

class EnterpriseRepository(
    Protocol
):
    def find(...): ...
    def find_all(...): ...
    def save(...): ...
    def delete(...): ...
    def begin(...): ...
    def commit(...): ...
    def rollback(...): ...
    def refresh(...): ...
    def lock(...): ...

Large protocols:

• reduce substitutability;
• make fakes expensive;
• couple unrelated operations;
• create interface segregation problems.

Prefer capability-oriented protocols.

---

4. Protocol attributes

class HasName(
    Protocol
):
    name: str

Compatible class:

class User:
    def __init__(
        self,
        name: str,
    ) -> None:
        self.name = name

Attribute mutability matters.

A writable protocol attribute may reject a read-only property because callers are allowed to assign.

Read-only protocol property:

class HasName(
    Protocol
):
    @property
    def name(self) -> str:
        ...

Now a compatible implementation only needs readable access.

Design protocol mutability intentionally.

---

5. Method compatibility

Protocol:

class Loader(
    Protocol
):
    def load(
        self,
        key: str,
    ) -> bytes:
        ...

Implementation:

class FileLoader:
    def load(
        self,
        key: str,
    ) -> bytes:
        ...

Compatibility considers:

• parameter types;
• return types;
• positional and keyword behavior;
• optional parameters;
• variance;
• overloads;
• properties and mutability.

A method with a narrower accepted parameter may not be compatible.

---

6. Protocol inheritance

class Readable(
    Protocol
):
    def read(self) -> bytes:
        ...


class Closable(
    Protocol
):
    def close(self) -> None:
        ...


class ReadableResource(
    Readable,
    Closable,
    Protocol,
):
    pass

This composes capabilities.

Do not use protocol inheritance to create deep conceptual taxonomies. Keep contracts focused.

---

7. Generic protocols

class Source[T](
    Protocol
):
    def get(self) -> T:
        ...

class Repository[ID, T](
    Protocol
):
    def find(
        self,
        entity_id: ID,
    ) -> T | None:
        ...

    def save(
        self,
        entity: T,
    ) -> None:
        ...

Generic protocols express relationships without requiring implementation inheritance.

Use variance deliberately for producer-only or consumer-only protocols.

---

8. Callback protocols

Callable cannot describe every callback shape.

class ErrorReporter(
    Protocol
):
    def __call__(
        self,
        message: str,
        *,
        code: int | None = None,
    ) -> None:
        ...

Compatible function:

def report_error(
    message: str,
    *,
    code: int | None = None,
) -> None:
    ...

Callback protocols can express:

• keyword-only parameters;
• overloaded calls;
• generic methods;
• named arguments;
• attributes on callable objects.

---

9. Explicit protocol inheritance

An implementation may explicitly inherit:

class EmailSender(
    MessageSender
):
    ...

Benefits:

• documents intention;
• missing abstract protocol members may be reported;
• shared protocol defaults can be inherited.

Costs:

• creates nominal coupling;
• may affect MRO;
• is unnecessary for structural compatibility.

Explicit inheritance is useful when implementer intent should be visible.

It is not required.

---

10. Default protocol methods

class Named(
    Protocol
):
    @property
    def name(self) -> str:
        ...

    def display_name(
        self,
    ) -> str:
        return self.name.title()

A structurally compatible class that does not inherit from Named does not automatically receive display_name.

Default implementation is inherited only by explicit subclasses.

Protocols primarily describe contracts, not reusable mixin behavior.

Use a helper function or mixin when code reuse is the real goal.

---

11. runtime_checkable

from typing import (
    Protocol,
    runtime_checkable,
)


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

Now:

isinstance(
    resource,
    SupportsClose,
)

can perform a limited structural runtime check.

Limitations:

• generally checks attribute presence, not full signatures;
• does not validate parameter or return types;
• can be slower than normal nominal checks;
• dynamic objects may behave unexpectedly;
• passing the check does not prove semantic correctness.

Do not confuse runtime-checkable protocols with complete runtime validation.

---

12. Semantic contracts

An object may structurally match:

class Transaction(
    Protocol
):
    def commit(self) -> None:
        ...

    def rollback(self) -> None:
        ...

But methods may not provide correct transaction semantics.

Static structure cannot verify:

• atomicity;
• durability;
• idempotency;
• authorization;
• ordering;
• side effects;
• performance;
• exception behavior.

Documentation and tests remain essential.

---

13. Protocols versus ABCs

Use a protocol when:

• structural compatibility is desired;
• third-party objects should work without modification;
• fakes should be simple;
• behavior matters more than identity;
• static checking is the main requirement.

Use an ABC when:

• runtime nominal identity matters;
• shared implementation exists;
• instantiation must be restricted;
• framework registration depends on inheritance;
• class-level lifecycle is required.

They can also be combined, but avoid duplicate abstractions without purpose.

---

14. Protocols versus concrete types

Do not create a protocol automatically for every dependency.

Concrete type:

def render(
    template: JinjaTemplate,
) -> str:
    ...

may be appropriate when the function genuinely depends on Jinja-specific behavior.

Protocol:

class Template(
    Protocol
):
    def render(
        self,
        context: dict[str, object],
    ) -> str:
        ...

is valuable when implementations are expected to vary or tests benefit from a smaller contract.

The protocol should be owned near the consumer, not necessarily near the implementation.

---

15. Consumer-owned interfaces

Suppose an application service needs:

class UserLookup(
    Protocol
):
    def find_email(
        self,
        user_id: int,
    ) -> str | None:
        ...

This protocol belongs to the application use case.

A large database repository may implement the capability implicitly.

Why consumer-owned?

• contract stays minimal;
• use case controls what it needs;
• infrastructure does not dictate domain abstractions;
• test fakes remain small.

This is an important dependency-inversion principle.

---

16. Testing with protocol-shaped fakes

class FakeUserLookup:
    def __init__(
        self,
        emails: dict[int, str],
    ) -> None:
        self._emails = emails

    def find_email(
        self,
        user_id: int,
    ) -> str | None:
        return self._emails.get(
            user_id
        )

No framework base class is required.

The fake can implement only the needed capability.

This reduces test coupling.

---

17. Protocol property variance

Problem:

class Box(
    Protocol
):
    content: object

An implementation with content: str may be unsafe if callers can assign any object through the protocol.

Read-only property:

class Box(
    Protocol
):
    @property
    def content(
        self,
    ) -> object:
        ...

A string-returning property can be compatible because callers only read it.

Mutable attributes force invariance-like reasoning.

---

18. Recursive protocols

class TreeNode(
    Protocol
):
    @property
    def children(
        self,
    ) -> list["TreeNode"]:
        ...

Recursive protocols can model trees and graphs.

Consider using read-only sequences rather than mutable lists:

from collections.abc import Sequence


class TreeNode(
    Protocol
):
    @property
    def children(
        self,
    ) -> Sequence["TreeNode"]:
        ...

This improves variance and prevents callers from mutating implementation-owned collections.

---

19. Modules as protocols

Python typing can conceptually treat modules as satisfying protocols because modules have attributes.

Example dependency:

class Clock(
    Protocol
):
    def now(self) -> datetime:
        ...

A module exposing now() may satisfy the same structural contract in suitable contexts.

In practice, small objects are often easier to inject and test than modules.

---

20. Built-in protocols and ABCs

Prefer standard abstractions when they already express the requirement:

from collections.abc import (
    Iterable,
    Iterator,
    Mapping,
    Sequence,
)

Instead of defining:

class CanIterate(
    Protocol
):
    def __iter__(self):
        ...

Use Iterable[T].

Standard protocols improve interoperability and reader familiarity.

---

21. TypeScript comparison

TypeScript interfaces are structurally typed by default.

Python protocols are opt-in static descriptions within a dynamically typed language.

Differences:

• runtime classes remain independent unless explicitly inherited;
• runtime_checkable is limited;
• Python method binding and descriptor behavior affect compatibility;
• multiple checker implementations may report edge cases differently;
• protocols should align with Python's existing runtime duck typing.

---

22. Production case study: storage dependency

Overly broad dependency:

class StorageService(
    Protocol
):
    def upload(...): ...
    def download(...): ...
    def delete(...): ...
    def list(...): ...
    def generate_url(...): ...
    def change_permissions(...): ...

A report exporter only needs:

class ByteWriter(
    Protocol
):
    def write(
        self,
        path: str,
        content: bytes,
    ) -> None:
        ...

Use case:

class ReportExporter:
    def __init__(
        self,
        writer: ByteWriter,
    ) -> None:
        self._writer = writer

Infrastructure adapters can satisfy the narrow contract.

---

23. Common mistakes

Protocol for every class

Create one only when abstraction adds value.

Large protocol

Split capabilities.

Using protocol as mixin

Structural implementers do not inherit default code.

runtime_checkable as validation

It checks limited structure.

Writable attributes without intent

Use properties for read-only requirements.

Infrastructure-owned contract

Let consumers define minimal needs.

Recreating standard protocols

Use Iterable, Mapping, and similar abstractions.

Ignoring semantic behavior

Structure does not prove correctness.

---

24. English vocabulary

Term	Meaning
protocol	structural behavioral contract
structural subtyping	compatibility based on members
nominal subtyping	compatibility based on declared inheritance
capability	small unit of supported behavior
consumer-owned interface	contract defined by the code using it
runtime-checkable	supporting limited isinstance checks
semantic contract	behavioral meaning beyond method shape
adapter	object translating one interface to another
interface segregation	keeping contracts focused
implicit implementation	satisfying a protocol without inheritance

Useful sentences:

• “The implementation satisfies the protocol structurally.”
• “The protocol is owned by the consuming use case.”
• “This writable attribute makes the contract unnecessarily restrictive.”
• “The runtime check verifies member presence, not signatures.”
• “The protocol describes a capability rather than a hierarchy.”
• “The structural match does not guarantee transaction semantics.”

---

25. Speaking task

Explain for twelve minutes:

How Python protocols compare with TypeScript interfaces.

Include nominal typing, structural typing, runtime checks, and consumer-owned contracts.

---

26. Writing task

Write a 500-word architecture review of a codebase with one 40-method repository protocol implemented by every persistence adapter and fake.

---

27. Exercises

Exercise 1

Create a small protocol for writing bytes.

Exercise 2

Create a callback protocol with keyword-only severity.

Exercise 3

Create a generic read-only Source.

Exercise 4

Demonstrate the limits of runtime_checkable.

Exercise 5

Refactor a large service interface into consumer-owned capabilities.

Exercise 6

Choose between a protocol, ABC, and concrete type in three scenarios.

---

28. Complete solutions

Solution 1

from typing import Protocol


class ByteWriter(
    Protocol
):
    def write(
        self,
        path: str,
        content: bytes,
    ) -> None:
        ...

Solution 2

from typing import (
    Literal,
    Protocol,
)

Severity = Literal[
    "info",
    "warning",
    "error",
]


class Reporter(
    Protocol
):
    def __call__(
        self,
        message: str,
        *,
        severity: Severity,
    ) -> None:
        ...

Solution 3

from typing import Protocol


class Source[T](
    Protocol
):
    def get(self) -> T:
        ...

Because the protocol only produces T, covariance may be inferred or declared explicitly in compatibility syntax depending on target tooling.

Solution 4

from typing import (
    Protocol,
    runtime_checkable,
)


@runtime_checkable
class HasRun(
    Protocol
):
    def run(
        self,
        value: int,
    ) -> str:
        ...


class Incorrect:
    def run(self) -> None:
        pass


print(
    isinstance(
        Incorrect(),
        HasRun,
    )
)

The runtime structural check may pass because a run attribute exists, even though the signature and return contract are incompatible.

Static checking remains essential.

Solution 5

Instead of one large repository, define:

class UserReader(
    Protocol
):
    def find_user(
        self,
        user_id: int,
    ) -> User | None:
        ...


class UserWriter(
    Protocol
):
    def save_user(
        self,
        user: User,
    ) -> None:
        ...


class UnitOfWork(
    Protocol
):
    def commit(self) -> None:
        ...

Each use case depends only on the capabilities it needs.

Solution 6

Use a protocol for a third-party-compatible clock dependency.

Use an ABC for a framework plugin requiring runtime registration and shared implementation.

Use a concrete type when a function intentionally depends on one library's specialized API and substitution is not needed.

---

29. Chapter checkpoint

You should now be able to explain:

1. nominal versus structural subtyping;
2. implicit protocol implementation;
3. small capability protocols;
4. protocol attributes;
5. generic protocols;
6. callback protocols;
7. default protocol methods;
8. runtime_checkable limitations;
9. protocols versus ABCs;
10. consumer-owned contracts;
11. testing with structural fakes;
12. semantic contracts.