Busca en todas las páginas de la documentación
typing.Protocol habilita el tipado pato estático: cualquier clase con métodos coincidentes satisface el protocolo sin necesidad de heredar de él. Este es el compañero en la capa de tipos para los patrones estructurales de OOP.
from typing import Protocol
class SupportsWrite(Protocol):
def write(self, data: bytes) -> int: ...
def persist(stream: SupportsWrite, payload: bytes) -> None:
stream.write(payload)Cuándo usar esto:
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))Lo que esto demuestra:
InMemoryRepo satisface Repository sin herencia.@runtime_checkable habilita isinstance en las pruebas.... (elipsis) en la definición del Protocolo.isinstance verifica solo los nombres de los métodos - superficial.@property en Protocolo - Declara atributos de solo lectura estructuralmente.| Necesidad | Elegir |
|---|---|
| Coincidencia estructural con terceros | Protocolo |
| Forzar en la instanciación | ABC |
Validación profunda con isinstance | Ninguno solo - pruebas + tipos |
class Readable(Protocol):
def read(self, n: int = -1) -> bytes: ...
# Protocolo genérico
from typing import TypeVar
T = TypeVar("T", contravariant=True)
class Box(Protocol[T]):
def put(self, item: T) -> None: ...isinstance - runtime_checkable es superficial. Solución: No depender de él para límites de seguridad.mypy en CI en ambos lados.| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| ABC | Controlar el árbol de herencia | Tipos de terceros |
object | Sin ayuda estática | Necesidad de contratos de métodos |
| zope.interface | Ecosistema heredado | Código nuevo enfocado en tipos |
| clase concreta única | Una implementación | Múltiples formas |
Opcional para claridad de tipado; no es necesario para la coincidencia estructural en tiempo de ejecución.
Declara @property def x(self) -> int: ... en el cuerpo del protocolo.
Fuerte; a menudo más estricto que mypy en casos extremos de superposición de protocolos.
Usa Protocol con __call__ o Callable; Callable es más simple solo para funciones.
No está incorporado; asegúrate de que todos los métodos del protocolo estén implementados; los verificadores informan los faltantes.
Las bibliotecas definen Protocolos que coinciden con la API de tipo pato de ndarray sin importar numpy en stubs solo de tipos.
Depende de servicios tipados con Protocolo para dobles de prueba en funciones de ruta.
Los protocolos en sí mismos no imponen la inmutabilidad; documenta las expectativas de implementación.
3.14 tiene Protocol en la biblioteca estándar; versiones anteriores usaban el backport de typing_extensions.
El artículo de OOP se enfoca en patrones de tiempo de ejecución; esta página se enfoca en la configuración del verificador estático y el diseño de API.
Versiones de la pila: Esta página fue escrita para Python 3.14.0 (estable 3.14, mantenimiento 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+, y uv 0.6+.
Revisado por Chris St. John·Última actualización: 16 jul 2026