Protocols & Structural Typing

typing.Protocol enables static duck typing: any class with matching methods satisfies the protocol without subclassing. This is the typing-layer companion to OOP structural patterns.

Recipe

from typing import Protocol
 
class SupportsWrite(Protocol):
    def write(self, data: bytes) -> int: ...
 
def persist(stream: SupportsWrite, payload: bytes) -> None:
    stream.write(payload)

When to reach for this:

• Typing file-like objects and streams
• Defining ports in hexagonal architecture
• Testing with fakes without ABC inheritance
• Gradual typing on duck-typed legacy code

Working Example

from typing import Protocol, runtime_checkable
 
@runtime_checkable
class Repository(Protocol):
    def get(self, item_id: int) -> dict[str, object]: ...
    def save(self, item: dict[str, object]) -> None: ...
 
class InMemoryRepo:
    def __init__(self) -> None:
        self._data: dict[int, dict[str, object]] = {}
 
    def get(self, item_id: int) -> dict[str, object]:
        return self._data[item_id]
 
    def save(self, item: dict[str, object]) -> None:
        self._data[int(item["id"])] = item
 
def service(repo: Repository) -> None:
    repo.save({"id": 1, "name": "Ada"})
    assert repo.get(1)["name"] == "Ada"
 
if __name__ == "__main__":
    service(InMemoryRepo())
    print(isinstance(InMemoryRepo(), Repository))

What this demonstrates:

• InMemoryRepo satisfies Repository without inheritance
• Service depends on structural interface
• @runtime_checkable enables isinstance in tests
• Methods use ... ellipsis bodies in Protocol definition

Deep Dive

How It Works

• PEP 544 - Structural subtyping for static checkers.
• Nominal vs structural - ABC requires inheritance; Protocol does not.
• runtime_checkable - isinstance checks method names only - shallow.
• Protocol inheritance - Extend protocols to add methods.
• @property in Protocol - Declare read-only attributes structurally.

Protocol vs ABC

Python Notes

class Readable(Protocol):
    def read(self, n: int = -1) -> bytes: ...
 
# Generic protocol
from typing import TypeVar
T = TypeVar("T", contravariant=True)
 
class Box(Protocol[T]):
    def put(self, item: T) -> None: ...

Gotchas

• isinstance false confidence - runtime_checkable shallow. Fix: Do not rely for security boundaries.
• Protocol runtime inheritance - Typing only - do not expect Protocol base behavior at runtime.
• Private methods - Protocol cannot see name-mangled methods. Fix: Public interface methods only.
• Structural drift - Implementation changes break checker silently at call sites. Fix: CI mypy on both sides.
• Duplicate Protocol definitions - Structural equivalence not automatic across modules. Fix: Import shared Protocol type.

Alternatives

FAQs

Related

• Protocols & Structural Typing - runtime OOP view
• Abstract Base Classes - nominal alternative
• Generics & TypeVar - generic protocols
• mypy & pyright Setup - checker config

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.