2.17. Anotações de tipo

O Python permite-lhe anotar os parâmetros de funções e os valores de retorno com informação de tipo. As anotações são ignoradas em tempo de execução – nada as verifica, nada converte com base nelas – mas servem como documentação para leitores e para o IDE.

2.17.1. Sintaxe de anotação

A anotação de um parâmetro vem após dois pontos. O tipo de retorno vem após -> e antes dos dois pontos do corpo:

def greet(name: str) -> None:
    print("hello,", name)

def add(a: int, b: int) -> int:
    return a + b

def average(values: list) -> float:
    return sum(values) / len(values)

As dicas descrevem o que deve ser passado e o que será devolvido. Chamar add("hi", "there") não levanta exceção – o Python executa o corpo na mesma. As dicas são um contrato, não uma verificação.

Um parâmetro pode ter simultaneamente um valor predefinido e uma anotação:

def greet(name: str, greeting: str = "hello") -> None:
    print(greeting, name)

O CPython tem notação mais rica (Optional, Union, genéricos) através do módulo typing, mas são pesados em MicroPython e raramente necessários para código de câmara do quotidiano.

2.17.2. MicroPython em tempo de execução

O MicroPython analisa as anotações e depois ignora-as. Não existe módulo typing para importar na câmara; tentar usar Optional[int] ou list[int] falhará na importação ou comportar-se-á silenciosamente como acesso simples a atributos, dependendo da versão do firmware.

Atenha-se a nomes de tipo simples (int, float, str, bool, bytes, list, tuple, dict) nas anotações. Não têm qualquer custo em tempo de execução e transmitem a intenção com clareza.

2.17.3. Como o IDE as utiliza

O IDE lê as anotações para alimentar dicas de ferramentas, autocompletar e dicas em linha. Uma função anotada com -> int mostra int como tipo de retorno quando o cursor paira sobre a chamada. Um parâmetro anotado com : str autocompletará métodos de string sobre o argumento dentro do corpo da função.

Este é o benefício prático de escrever anotações num runtime que as ignora: melhor suporte do editor sem qualquer custo quando o script é executado na câmara.

2.17.4. Anotações de variáveis

As anotações em atribuições simples funcionam da mesma forma:

threshold: float = 0.5
name: str = "OpenMV"

Estas também são ignoradas em tempo de execução. O seu uso principal é tornar o tipo pretendido óbvio quando o lado direito não o torna obvio – tipicamente quando o valor inicial é um marcador de posição que será substituído mais tarde.