2.17. Type hints

O Python permite anotar parâmetros de função e valores de retorno com informações de tipo. As anotações são ignoradas em tempo de execução – nada as verifica, nada faz conversão com base nelas – mas elas servem como documentação para quem lê e para o IDE.

2.17.1. Sintaxe de anotação

Uma anotação de 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 deveria ser passado e o que será retornado. Chamar add("hi", "there") não lança erro – o Python executa o corpo de qualquer forma. As dicas são um contrato, não uma verificação.

Um parâmetro pode ter tanto um valor padrão quanto uma anotação:

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

O CPython tem uma notação mais rica (Optional, Union, genéricos) por meio do módulo typing, mas esses recursos são pesados no MicroPython e raramente necessários no código cotidiano de câmera.

2.17.2. MicroPython em tempo de execução

O MicroPython faz o parsing das anotações e depois as ignora. Não há um módulo typing para importar na câmera; tentar usar Optional[int] ou list[int] ou falhará na importação ou se comportará silenciosamente como um acesso de atributo comum, dependendo da build do firmware.

Atenha-se a nomes de tipo simples (int, float, str, bool, bytes, list, tuple, dict) nas anotações. Eles não custam nada 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 tooltips, autocompletar e dicas inline. Uma função anotada com -> int mostra int como seu tipo de retorno quando o cursor passa sobre a chamada. Um parâmetro anotado com : str autocompleta métodos de string no argumento dentro do corpo da função.

Esse é o ganho prático de escrever anotações em um runtime que as ignora: melhor suporte do editor sem custo algum quando o script roda na câmera.

2.17.4. Anotações de variáveis

Anotações em atribuições simples funcionam da mesma forma:

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

Elas também são ignoradas em tempo de execução. Seu uso principal é deixar o tipo pretendido óbvio quando o lado direito não o torna óbvio – tipicamente quando o valor inicial é um espaço reservado que será substituído mais tarde.