typing.Self en Python para Métodos Fluidos

typing.Self representa el tipo concreto de la clase sobre la que se llama un método. En APIs fluidas conserva la subclase después de devolver self, sin declarar manualmente un TypeVar limitado.

from typing import Self

class Consulta:
    def __init__(self) -> None:
        self.filtros: list[str] = []

    def filtrar(self, expressao: str) -> Self:
        self.filtros.append(expressao)
        return self

class ConsultaAuditada(Consulta):
    pass

consulta = ConsultaAuditada().filtrar("ativo = true")

El verificador entiende que llamar a filtrar() sobre una subclase sigue produciendo esa subclase. El patrón también funciona en classmethods que construyen cls y en __enter__() cuando el context manager devuelve su instancia.

Buenas prácticas

No anotes con Self un método que crea explícitamente la clase base, porque una llamada desde la subclase no devolverá el subtipo prometido. Para versiones anteriores a Python 3.11, considera typing_extensions según la compatibilidad del proyecto.

Relaciona el concepto con la guía de type hints y con classmethod y staticmethod.

La documentación oficial de typing.Self, consultada el 22 de julio de 2026, detalla la API y sus límites.