Structural Subtyping with Protocol

Also Known As

TL;DR

Explanation

Protocol (typing.Protocol, Python 3.8+): a class satisfies a Protocol if it has all required attributes and methods, regardless of inheritance. Unlike ABC (which requires explicit subclassing), Protocol works at type-check time without modifying existing classes. @runtime_checkable enables isinstance() checks at runtime. Use for: typing third-party classes you cannot modify, documenting expected interfaces without coupling to a class hierarchy, and expressing duck types with static type safety.

Common Misconception

Why It Matters

Common Mistakes

• Using Protocol when ABC is more appropriate — use ABC when you want enforcement at class definition time
• Not adding @runtime_checkable when isinstance() checks are needed
• Protocol with mutable attributes — structural subtyping with mutable attributes can be surprising
• Forgetting that satisfying the Protocol is checked at type-check time not runtime (without @runtime_checkable)

Code Examples

# Any type — loses all type safety:
def process(reader: Any) -> str:
    return reader.read()  # No type checking — any attribute access allowed

# ABC — requires modifying existing classes:
from abc import ABC, abstractmethod
class Readable(ABC):
    @abstractmethod
    def read(self) -> str: ...
# All implementing classes must inherit Readable — invasive coupling

from typing import Protocol, runtime_checkable

@runtime_checkable
class Readable(Protocol):
    def read(self) -> str: ...

def process(reader: Readable) -> str:
    return reader.read()  # Type-checked — must have read() -> str

# Any class with read() -> str satisfies it — no inheritance needed:
class FileReader:
    def read(self) -> str: return open(self.path).read()

class MockReader:
    def read(self) -> str: return 'mock data'

process(FileReader())  # Type-safe
process(MockReader())  # Type-safe
isinstance(MockReader(), Readable)  # True (runtime_checkable)

References

• ↗ https://peps.python.org/pep-0544/

Tags

Related Terms