Type hints e verificação estática

As anotações são documentação que uma ferramenta pode verificar

Python é de tipagem dinâmica: uma variável pode conter qualquer coisa, e um tipo errado só aparece quando a linha roda, talvez em pleno pregão. As anotações de tipo permitem escrever o que uma função espera e devolve: def mid_price(bid: float, ask: float) -> float. O Python as ignora ao executar. O valor delas é que um editor e um verificador estático como mypy ou pyright as leem e avisam de uma chamada errada antes de o código rodar, e que documentam a função melhor que um comentário que envelhece.

# Hints describe the function; Python does not enforce them when it runs
def mid_price(bid: float, ask: float) -> float:
    return (bid + ask) / 2

print(mid_price(100.0, 100.5))                      # 100.25
print(mid_price.__annotations__)                    # {'bid': <class 'float'>, 'ask': <class 'float'>, 'return': <class 'float'>}
print(mid_price(10, 12))                            # 11.0   an int is accepted where float is hinted
try:
    mid_price("a", "b")                             # a checker flags this line before the code runs
except TypeError as error:
    print("only fails when it runs:", error)       # only fails when it runs: unsupported operand type(s) for /

Contêineres, None e uniões

Os contêineres embutidos recebem o tipo dos elementos entre colchetes: list[float], dict[str, float], tuple[str, float] (um tipo por posição). Um valor que pode faltar é float | None, o que obriga o chamador a tratar None; o verificador reclama se ele usar o resultado como número sem checar. Dentro da função, um if x is None: return estreita o tipo e o resto sabe que é um float. Para argumentos só lidos, prefira um tipo geral como Sequence[float] (listas, tuplas) a list[float], para caberem mais chamadores; devolva um tipo concreto, como list[float].

# Containers, an optional result, and narrowing with an is None check
def best_quote(quotes: list[tuple[str, float]]) -> tuple[str, float] | None:
    if not quotes:
        return None
    return min(quotes, key=lambda quote: quote[1])

def describe(quotes: list[tuple[str, float]]) -> str:
    best = best_quote(quotes)
    if best is None:                                 # after this check the checker knows best is a tuple
        return "no quotes"
    venue, price = best
    return f"{venue} at {price:.2f}"

print(describe([("XNAS", 100.02), ("ARCX", 100.01)]))     # ARCX at 100.01
print(describe([]))                                       # no quotes

Formas de dados e o verificador em ação

Um dicionário de chaves fixas, como uma ordem, é melhor descrito do que deixado como dict. Um TypedDict ou uma dataclass nomeia cada campo e seu tipo, de modo que um erro de digitação como order["quantiy"] vira erro no editor e não um KeyError às 15:59. O verificador roda na linha de comando (mypy main.py); imprime cada ponto em que o código contradiz suas anotações e sai com código diferente de zero, então encaixa nas verificações automáticas que você verá adiante. As anotações podem ser adicionadas aos poucos: Any desliga a checagem de um valor e o código sem tipos é simplesmente ignorado. As anotações também são dados que as ferramentas leem em tempo de execução com typing.get_type_hints, exatamente como este laboratório as verifica.

# A TypedDict names the fields of an order; the checker would flag order["quantiy"]
from typing import TypedDict

class Order(TypedDict):
    symbol: str
    quantity: int
    price: float

def notional(order: Order) -> float:
    return order["quantity"] * order["price"]

order: Order = {"symbol": "AAPL", "quantity": 100, "price": 184.5}
print(notional(order))                              # 18450.0
print(Order.__annotations__)                        # {'symbol': <class 'str'>, 'quantity': <class 'int'>, 'price': <class 'float'>}

# The hints can be read at run time, which is how tools (and this lab) inspect a function
import typing

def apply_fee(prices: typing.Sequence[float], fee_rate: float = 0.001) -> list[float]:
    return [price * (1 + fee_rate) for price in prices]

hints = typing.get_type_hints(apply_fee)
print(hints["fee_rate"], hints["return"])           # <class 'float'> list[float]
print(typing.get_origin(hints["prices"]).__name__)  # Sequence
print(apply_fee((100.0, 200.0)))                    # a tuple is accepted: [100.1, 200.2]

• As anotações (bid: float, -> float) documentam uma função e são ignoradas ao executar; um verificador como o mypy as lê.
• Contêineres recebem tipos de elementos (list[tuple[str, float]]); um valor ausente é float | None; argumentos só de leitura podem ser um Sequence[float] geral.
• Use TypedDict ou dataclass para registros, rode o verificador nas suas verificações automáticas, e continue validando dados externos e testando os números.

A seguir: testes com pytest, fixtures, casos parametrizados e as verificações que mantêm uma estratégia honesta.

Lab: o que é avaliado

• Anotar números com mid_price25 pts
• Tipar um contêiner com best_quote25 pts
• Admitir um valor ausente em safe_ratio25 pts
• Aceitar qualquer sequência em apply_fee25 pts