Protocol classes: structural typing for duck-typed Python

What it is

A Protocol class (PEP 544, typing.Protocol) lists methods and attributes; any object that provides them satisfies the type, whether or not its class inherits from the protocol. The typing documentation calls this structural subtyping (static duck-typing), in contrast to nominal subtyping through inheritance. The "one-trick ponies" in collections.abc such as Iterable and Sized are the standard library's own examples. A protocol can be generic (class Reader[T](Protocol) from Python 3.12, Protocol[T] before).

Why it matters

Functions that accept "anything with .read()" or "anything with .close()" are everywhere in Python. Without protocols they are annotated as Any (no checking) or as one concrete class (callers must subclass). A protocol lets the consumer state what it needs instead of the producer stating what it is: the type lives next to the code that depends on it, third-party classes fit without modification, and a test double needs only the members actually used.

How to apply

• Define the protocol in the consuming module and keep it minimal: only the members the consumer calls, with precise signatures and ... bodies.
• Use protocols for parameter types and abstract base classes for shared implementation; a protocol carries no code, an ABC can.
• Add @runtime_checkable only where isinstance() is really needed. The documentation states that such checks only test the presence of the given attributes and ignore their type signatures; protocols without the decorator cannot be used with isinstance() at all.
• Name protocols by capability (SupportsClose, Closable), matching typing.SupportsInt and friends.
• Check conformance statically where drift would hurt. PEP 544 states that explicit subclassing is not needed for type checking, but that it lets the checker verify the class at its definition and gives it default implementations. The alternative, assigning an instance to a variable annotated with the protocol, works too; the PEP discourages it in application code because it reads as dead code and needs an instance, so keep it in a test module.

Pitfalls

Attribute members (name: str) are satisfied by plain attributes and properties alike, but a checker rejects a read-only property where a settable attribute is declared. A method whose parameter names differ from the protocol's can be reported as incompatible, because callers may pass them by keyword; mark parameters positional-only (/) where names are not part of the contract. The documentation notes that an isinstance() check against a runtime-checkable protocol can be surprisingly slow compared with a class check, and attributes assigned later in __init__ fail the presence test until set. Protocol classes cannot be instantiated. Explicitly inheriting from a protocol is allowed, but readers then see a nominal relationship where none was needed.