Classes Protocol: tipagem estrutural para o duck typing em Python

O que é

Uma classe Protocol (PEP 544, typing.Protocol) enumera métodos e atributos; qualquer objeto que os forneça satisfaz o tipo, independentemente de sua classe herdar ou não do protocol. A documentação de typing chama isso de subtipagem estrutural (duck typing estático), em oposição à subtipagem nominal por herança. As "one-trick ponies" de collections.abc, como Iterable e Sized, são os exemplos da própria biblioteca padrão. Um protocol pode ser genérico (class Reader[T](Protocol) a partir do Python 3.12, Protocol[T] em versões anteriores).

Por que importa

Funções que aceitam "qualquer coisa com .read()" ou "qualquer coisa com .close()" estão por toda parte em Python. Sem protocols, elas são anotadas como Any (sem verificação nenhuma) ou com uma classe concreta (e quem chama precisa criar uma subclasse). Com um protocol, é o consumidor que declara do que precisa, em vez de o produtor declarar o que é: o tipo fica junto ao código que depende dele, classes de terceiros se encaixam sem modificação e um test double só precisa dos membros que de fato são usados.

Como aplicar

• Defina o protocol no módulo consumidor e mantenha-o mínimo: apenas os membros que o consumidor chama, com assinaturas precisas e corpos ....
• Use protocols para tipos de parâmetros e classes base abstratas para implementação compartilhada; um protocol não carrega código, uma ABC pode carregar.
• Adicione @runtime_checkable apenas onde isinstance() for realmente necessário. A documentação afirma que essas verificações testam apenas a presença dos atributos indicados e ignoram suas assinaturas de tipo; protocols sem o decorator simplesmente não podem ser usados com isinstance().
• Nomeie protocols pela capacidade (SupportsClose, Closable), seguindo o padrão de typing.SupportsInt e similares.
• Verifique a conformidade estaticamente onde uma divergência causaria problemas. A PEP 544 afirma que a herança explícita não é necessária para a verificação de tipos, mas que ela permite ao checker validar a classe já na sua definição e fornece implementações padrão. A alternativa, atribuir uma instância a uma variável anotada com o protocol, também funciona; a PEP desaconselha isso em código de aplicação, porque parece código morto e exige uma instância, então deixe-a em um módulo de testes.

Armadilhas

Membros do tipo atributo (name: str) são satisfeitos tanto por atributos simples quanto por properties, mas o checker rejeita uma property somente leitura onde foi declarado um atributo gravável. Um método cujos nomes de parâmetros diferem dos do protocol pode ser apontado como incompatível, porque quem chama pode passá-los por palavra-chave; marque os parâmetros como positional-only (/) quando os nomes não fizerem parte do contrato. A documentação observa que uma verificação isinstance() contra um protocol runtime-checkable pode ser surpreendentemente lenta em comparação com uma verificação de classe, e que atributos atribuídos mais tarde em __init__ falham no teste de presença até serem definidos. Classes Protocol não podem ser instanciadas. Herdar explicitamente de um protocol é permitido, mas quem lê o código passa a ver uma relação nominal onde ela não era necessária.