typing.Self em Python para Métodos Fluentes

typing.Self representa o tipo concreto da classe em que um método é chamado. Em APIs fluentes, ele preserva a subclasse depois de retornar self, sem declarar manualmente um 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")

No exemplo, o verificador entende que filtrar() sobre ConsultaAuditada continua produzindo ConsultaAuditada. O mesmo padrão funciona em classmethods que constroem cls e em __enter__() quando o context manager retorna a própria instância.

Boas práticas

Não anote com Self um método que sempre cria explicitamente a classe base, pois uma chamada pela subclasse não retornará o subtipo prometido. Para versões anteriores ao Python 3.11, avalie o backport em typing_extensions de acordo com a política de compatibilidade do projeto.

Conecte o conceito ao guia de type hints e aos usos de classmethod e staticmethod.

A documentação oficial de typing.Self, consultada em 22 de julho de 2026, detalha a API e seus limites.