Boas práticas para anotações
****************************

Autor:
   Larry Hastings


Resumo
^^^^^^

Este documento foi projetado para encapsular as melhores práticas para
trabalhar com anotações. Se você escrever um código Python que examina
"__annotations__" nos objetos Python, nós o encorajamos a seguir as
diretrizes descritas abaixo.

Este documento está dividido em quatro seções: melhores práticas para
acessar as anotações de um objeto no Python  na versão 3.10 e versões
mais recente, melhores práticas para acessar as anotações de um objeto
no Python na versão 3.9 e versões mais antiga, outras melhores
práticas para "__annotations__" para qualquer versão do Python e
peculiaridades do "__annotations__".

Note que este documento é específico sobre trabalhar com
"__annotations__", não para o uso *de* anotações. Se você está
procurando por informações sobre como usar "type hints" no seu código,
por favor veja o módulo "typing"


Acessando o dicionário de anotações de um objeto no Python 3.10 e nas versões mais recentes
===========================================================================================

O Python 3.10 adicionou uma nova função para a biblioteca padrão:
"inspect.get_annotations()". A partir do Python 3.10 até 3.13, chamar
esta função é a melhor prática para acessar o dicionário de anotações
de qualquer objeto com suporte a anotações. Esta função pode até
"destextualizar" anotações textualizadas para você.

No Python 3.14, há um novo módulo "annotationlib" com funcionalidade
para trabalhar com anotações. Isso inclui uma função
"annotationlib.get_annotations()", que substitui
"inspect.get_annotations()".

Se por alguma razão "inspect.get_annotations()" não for viável para o
seu caso de uso, você pode acessar o membro de dados "__annotations__"
manualmente. As melhores práticas para isto também mudaram no Python
3.10: a partir do Python 3.10, "o.__annotations__" é garantido
*sempre* funcionar em funções, classes e módulos Python. Se você tem
certeza que o objeto que você está examinando é um desses três
*exatos* objetos, pode simplesmente usar "o.__annotations__" para
chegar no dicionário de anotações do objeto.

Contudo, outros tipos de chamáveis -- por exemplo, chamáveis criados
por "functools.partial()" -- podem não ter um atributo
"__annotations__" definido. Ao acessar o "__annotations__" de um
objeto possivelmente desconhecido, as melhores práticas nas versões de
Python 3.10 e mais novas é chamar "getattr()" com três argumentos, por
exemplo "getattr(o, '__annotations__', None)".

Antes de Python 3.10, acessar "__annotations__" numa classe que não
define anotações mas que possui uma classe base com anotações retorna
o "__annotations__" da classe pai. A partir do Python 3.10, a anotação
da classe filha será um dicionário vazio.


Acessando o dicionário de anotações de um objeto no Python 3.9 e nas versões mais antigas
=========================================================================================

Em Python 3.9 e versões mais antigas, acessar o dicionário de
anotações de um objeto é muito mais complicado que em versões mais
novas. O problema é uma falha de design em versões mais antigas do
Python, especificamente a respeito de anotações de classe.

As melhores práticas para acessar os dicionários de anotações de
outros objetos, funções, outros chamáveis e módulos - são as mesmas
melhores práticas para 3.10, supondo que você não esteja chamando
"inspect.get_annotations()": você deve usar a função "getattr()" com
três argumentos para acessar os atributos do objeto "__annotations__".

Infelizmente, essas não são as melhores práticas para classes. O
problema é que, como "__annotations__" é opcional nas classes, e posto
que classes podem herdar atributos das suas classes base, acessar o
atributo "__annotations__" de uma classe pode inesperadamente retornar
o dicionário de anotações de uma *classe base.*  Por exemplo:

   class Base:
       a: int = 3
       b: str = 'abc'

   class Derived(Base):
       pass

   print(Derived.__annotations__)

Isso mostrará o dicionário de anotações de "Base", não de "Derived".

Seu código terá que ter um caminho de código separado se o objeto que
você está examinando for uma classe ("isinstance(o, type)"). Nesse
caso, a melhor prática depende de um detalhe de implementação do
Python 3.9 e anteriores: se uma classe tiver anotações definidas, elas
serão armazenadas no dicionário "__dict__" da classe. Como a classe
pode ou não ter anotações definidas, a melhor prática é chamar o
método "get()" no dict da classe.

Considerando tudo isso, aqui está um exemplo de código que acessa de
forma segura o atributo "__annotations__" em um objeto arbitrário em
Python 3.9 e anteriores:

   if isinstance(o, type):
       ann = o.__dict__.get('__annotations__', None)
   else:
       ann = getattr(o, '__annotations__', None)

Após executar este código, "ann" deve ser um dicionário ou "None".
Você é encorajado a fazer uma checagem dupla do tipo de "ann"
utilizando "isinstance()" antes de uma análise mais aprofundada.

Observe que alguns objetos de tipos exóticos ou malformados podem não
ter atributo um "__dict__", portanto, para maior segurança, talvez
você também queira usar "getattr()" para acessar "__dict__".


Recuperando manualmente anotações transformadas em strings
==========================================================

Em situações em que as anotações podem ter sido transformadas em
strings, e caso queira avaliar essas strings para produzir os valores
de Python que elas representam, é melhor chamar
"inspect.get_annotations()" para fazer isto por você.

Se estiver usando Python 3.9 ou anterior, ou por algum motivo não
puder usar "inspect.get_annotations()", será necessário replicar sua
lógica. Considere examinar a implementação de
"inspect.get_annotations()" na versão de Python atual e seguir uma
abordagem similar.

Resumindo, caso deseje avaliar uma anotação transformada em string em
um objeto arbitrário "o":

* Se "o" for um módulo, use "o.__dict__" como "globals" ao chamar
  "eval()".

* Se "o" for uma classe, use "sys.modules[o.__module__].__dict__" como
  "globals", e "dict(vars(o))" como "locals", quando chamar "eval()".

* Se "o" for um chamável envolto em um invólucro usando
  "functools.update_wrapper()", "functools.wraps()" ou
  "functools.partial()", desenvolva-o iterativamente acessando
  "o.__wrapped__" ou "o.func" conforme apropriado, até encontrar a
  função raiz.

* Caso "o" seja chamável (mas não uma classe), use "o.__globals__"
  como globals quando chamar "eval()".

Contudo, nem todas strings usadas como anotações podem ser convertidas
em valores de Python utilizando "eval()". Valores de string poderiam
teoricamente conter qualquer string válida, e na prática existem casos
válidos para dicas de tipo que requerem anotar com valores de strings
que *não* podem ser executados. Por exemplo:

* Tipos de união **PEP 604** usando "|", antes do suporte a isso ser
  adicionado em Python 3.10.

* Definições que não são necessárias no ambiente de execução, apenas
  importadas quando "typing.TYPE_CHECKING" é verdadeiro.

Caso "eval()" tente executar tais valores, levantará uma exceção.
Então, quando projetar uma biblioteca API que trabalha com anotações,
é recomendado que tente executar os valores das strings apenas quando
for solicitado explicitamente.


Melhores práticas para "__annotations__" em qualquer versão Python
==================================================================

* Evite atribuir diretamente ao membro "__annotations__" dos objetos.
  Deixe que Python gerenciar a configuração de "__annotations__".

* Se você atribuir diretamente ao membro "__annotations__" do objeto,
  sempre o defina como um objeto "dict".

* Evita acessar "__annotations__" diretamente em qualquer objeto. Em
  vez disso, use "annotationlib.get_annotations()" (Python 3.14+) ou
  "inspect.get_annotations()" (Python 3.10+).

* Caso acesse diretamente o membro "__annotations__" de um objeto,
  certifique-se de que ele é um dicionário antes de tentar examinar
  seu conteúdo.

* Evite modificar o dicionário "__annotations__".

* Evite deletar o atributo "__annotations__" de um objeto.


Peculiaridades de "__annotations__"
===================================

Em todas as versões de Python 3, objetos de função criam
preguiçosamente um dicionário de anotações caso nenhuma anotação seja
definida nesse objeto. Você pode deletar o atributo "__annotations__"
utilizando "del fn.__annotations__", mas ao acessar
"fn.__annotations__" o objeto criará um novo dicionário vazio que será
armazenado e retornado como suas anotações. Apagar as anotações de uma
função antes que ela tenha criado preguiçosamente seu dicionário de
anotações irá produzir um "AttributeError"; ao utilizar "del
fn.__annotations__" duas vezes em sequência, é garantido que será
produzido um "AttributeError".

O citado no parágrafo acima também se aplica para classes e objetos de
módulo em Python 3.10 e posteriores.

Em todas as versões de Python 3, você pode definir "__annotations__"
como "None" em um objeto de função. Contudo, acessar em sequência as
anotações nesse objeto utilizando "fn.__annotations__" irá criar
preguiçosamente um dicionário vazio como descrito no primeiro
parágrafo dessa seção. Isso *não* é válido para módulos e classes, em
qualquer versão de Python; esses objetos permitem atribuir
"__annotations__" a qualquer valor de Python, e armazenam qualquer
valor atribuído.

Se Python transformar sua anotação em string (utilizando "from
__future__ import annotations"), e você especificar uma string como
anotação, essa string será posta entre aspas. Na prática a anotação
receberá aspas *duplas*. Por exemplo:

   from __future__ import annotations
   def foo(a: "str"): pass

   print(foo.__annotations__)

Isso exibe "{'a': "'str'"}". Não considere isso como uma
"peculiaridade"; foi mencionado aqui simplesmente porque pode ser
surpreendente.

Se você usar uma classe com uma metaclasse personalizada e acessar
"__annotations__" na classe, poderá observar um comportamento
inesperado; consulte a **749** para obter alguns exemplos. Você pode
evitar essas peculiaridades usando "annotationlib.get_annotations()"
no Python 3.14+ ou "inspect.get_annotations()" no Python 3.10+. Em
versões anteriores do Python, você pode evitar esses bugs acessando as
anotações do "__dict__" da classe (por exemplo,
"cls.__dict__.get('__annotations__', None)").

Em algumas versões do Python, instâncias de classes podem ter um
atributo "__annotations__". No entanto, essa funcionalidade não é
suportada. Se precisar das anotações de uma instância, você pode usar
"type()" para acessar sua classe (por exemplo,
"annotationlib.get_annotations(type(myinstance))" no Python 3.14+).
