Python Protocols and Structural Subtyping for Flexible APIs

Tue, 01 Sep 2026 00:00:00 +0700

Python code often depends on behavior rather than a specific class hierarchy. A function may only need an object with a send() method, a read() method, or a pair of repository operations.

typing.Protocol lets type checkers describe those behavioral requirements directly. A class satisfies a protocol by having compatible members; it does not need to inherit from the protocol.

This is structural subtyping: “if it has the required shape, it can be used here.”

Use Python Protocols for Structural Typing at API Boundaries

Tue, 01 Sep 2026 00:00:00 +0700

Python often relies on duck typing: if an object supports the operation a function needs, its concrete class does not matter. typing.Protocol gives static type checkers a way to describe that idea explicitly without requiring implementations to inherit from a shared base class.

Define the behavior you consume

$el.innerText = 'Copy', 2000)" class="absolute top-2 right-2 bg-neutral-700 text-white text-xs px-2 py-1 rounded opacity-0 group-hover:opacity-100 transition-opacity" > Copy

from typing import Protocol

class ByteWriter(Protocol):
    def write(self, data: bytes) -> int: ...


def emit_header(writer: ByteWriter) -> None:
    writer.write(b"NLR1")

Any statically compatible object can satisfy ByteWriter, even if its class never mentions the protocol.

Typing on Nalar

Python Protocols and Structural Subtyping for Flexible APIs

Use Python Protocols for Structural Typing at API Boundaries

Define the behavior you consume