Tratar valores opcionais e uniões de tipos

Use | quando um valor pode seguir um entre tipos alternativos. Por exemplo, int | str informa que o contrato aceita um número inteiro ou um texto.

A união descreve possibilidades; ela não converte valores. Se uma variável recebe "42", ela continua sendo str, mesmo que o contrato também admita int.

Leia a anotação como duas possibilidades para o mesmo valor.

A mesma anotação pode aparecer em diferentes pontos do contrato.

Na variável, a união limita os valores que podem ser atribuídos. No parâmetro, limita os argumentos aceitos. No retorno, informa que a chamada pode produzir qualquer uma das alternativas declaradas.

Como nas outras anotações, isso é um contrato para análise estática: Python não passa a validar automaticamente os valores em tempo de execução. O mypy pode apontar usos incompatíveis ao analisar o código.

Enquanto valor pode ser int ou str, uma operação só é segura se funcionar para ambos os tipos. str(valor) é aceitável: tanto inteiros quanto textos podem ser representados como texto.

Já valor + 1 não é justificado pelo contrato: funciona para int, mas não para str. O mypy sinaliza esse tipo de risco; a anotação não escolhe qual alternativa chegou na execução.

O comentário indica o ponto que o mypy deve rejeitar.

Em uma anotação, str | None significa que o valor pode ser um texto ou None. Isso não diz se quem chama a função pode deixar o argumento de fora.

A possibilidade de omitir depende de existir um valor padrão na assinatura. Portanto, são duas decisões independentes:

• Tipos aceitos: a anotação, como str ou str | None.
• Argumento opcional na chamada: a presença de = algum_valor.

Compare o que cada parte da assinatura controla.

Cada função ilustra uma combinação diferente. O corpo foi omitido porque o foco é o contrato do parâmetro.

A forma T | None pode aparecer onde um valor talvez esteja ausente: em uma variável local, em um parâmetro ou no retorno de uma função. Em todos os casos, ela descreve as alternativas possíveis do valor.

Observe que somente consultar_id pode retornar None; já nome_digitado é uma variável que pode guardar esse valor.

Compare as duas anotações:

• list[int | str]: a união está dentro dos colchetes. Cada elemento da mesma lista pode ser int ou str.
• list[int] | list[str]: a união está fora dos colchetes. O valor inteiro é uma lista de inteiros ou uma lista de textos.

Portanto, mover | muda o contrato.

A posição de | indica se a escolha ocorre elemento a elemento ou para a coleção como um todo.

Para escolher a anotação, observe o formato permitido:

• Quer permitir [1, "dois"]? Use list[int | str].
• Quer permitir [1, 2] ou ["um", "dois"], mas não uma mistura? Use list[int] | list[str].

Essa comparação descreve contratos por valores literais; não depende de regras de compatibilidade entre variáveis de listas.

Mesmo que um dicionário armazene apenas inteiros, uma busca com get sem valor padrão pode não encontrar a chave. Por isso, o resultado admite None.

Em dict[str, int], a expressão pontos.get("ana") tem tipo int | None: o int vem de um valor encontrado; o None, de uma chave ausente.

A anotação dos valores do dicionário não elimina a possibilidade de a chave consultada estar ausente.

A operação abaixo seria insegura sem uma verificação.

Guarde a consulta em uma variável local e teste-a com is None. No ramo verdadeiro, ela é None. No else, essa possibilidade foi excluída: ali, pontuacao é int e pode participar da soma.

Você também pode escrever a condição positiva como is not None; nesse caso, o ramo verdadeiro recebe o valor presente.

A soma está no ramo em que None não é mais uma possibilidade.

Nos dois exemplos, a chave existe; apenas seus valores são falsos em uma condição booleana.

Uma anotação como int | str informa que a variável pode conter uma das duas alternativas. Antes de usar uma operação exclusiva de um tipo, use isinstance para descobrir qual alternativa está presente naquele ramo.

Em if isinstance(valor, int):, o ramo verdadeiro trabalha com int. Como a união simples tem apenas int e str, no else resta str.

A condição divide as alternativas ainda possíveis em ramos seguros.

A multiplicação e upper() não são justificadas para os dois tipos ao mesmo tempo. Elas ficam nos ramos que comprovam seu tipo.

Quando o valor é int | str | None, uma verificação de ausência vem antes: após confirmar que não é None, restam int | str. Então isinstance separa essas duas alternativas.

Cada operação aparece somente depois da evidência que a justifica.

O segundo if é alcançado apenas quando dado não é None.

Uma cláusula de guarda trata logo no início um caso que não seguirá para o processamento principal. Se o parâmetro é str | None, teste None e termine esse ramo com return. Depois da guarda, o único tipo possível para nome é str.

O ramo que recebe None termina; apenas o ramo com texto alcança upper().

O retorno representa uma resposta válida para a ausência de nome.

Escolha a saída conforme o contrato da função. Use return quando a alternativa é prevista e há uma resposta útil para ela. Use raise quando aquela alternativa viola uma exigência da função. Nos dois casos, o ramo termina: o processamento seguinte só é alcançado pelos tipos restantes.

Aqui, a função exige uma idade numérica. None não tem resposta alternativa: é uma entrada inválida.

Uma anotação como int | str continua sendo o contrato da variável. O estreitamento obtido por uma condição vale apenas onde o fluxo fornece essa evidência.

Quando dois caminhos que continuam se reencontram, o mypy combina os tipos que podem chegar àquele ponto. Por isso, uma união pode voltar a ser relevante após um if.

Use reveal_type somente ao verificar o arquivo com mypy; remova-o antes da execução normal.

Um caminho que termina com return ou raise não alcança o código seguinte. Assim, seu tipo não participa da junção.

No exemplo, após retornar no caso de None, o restante da função recebe somente int. A anotação do parâmetro não mudou; o fluxo eliminou uma alternativa naquele ponto.

O tipo conhecido também é atualizado após uma nova atribuição compatível com a anotação declarada. Se uma variável declarada como str | None recebe None novamente, operações de texto deixam de estar justificadas até outra verificação.

Não basta lembrar que a variável já foi str em um trecho anterior: analise o ponto exato da operação.

Nesta função, chave: str | None = None aceita uma chave de texto ou None; o = None permite que o argumento seja omitido. Ao chamar apresentar(), a função recebe o padrão None. Ao chamar apresentar(None), o chamador fornece None explicitamente. Dentro desta função, ambos seguem o mesmo caso de “nenhuma chave informada”.

Depois da guarda para chave, catalogo.get(chave) tem tipo int | str | None: a chave pode não existir. Só depois de excluir None é seguro separar int de str com isinstance.

Cada ramo elimina possibilidades antes de executar uma operação específica.

No seu editor, crie um arquivo chamado consulta_tipado.py com o código abaixo. Substitua os # TODO sem usar Any, cast ou supressões do mypy.

Use saídas antecipadas para: (1) tratar chave is None; (2) tratar uma chave ausente; e então use isinstance(valor, int) antes da soma. No ramo restante, aplique upper() ao texto.

Corrija somente os trechos marcados com TODO.

Compare com sua versão depois de tentar. A mesma guarda que torna a chamada de get válida também elimina None no restante da função.