Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / Python

Uniões de tipos: X | Y e X | None

Nas anotações de tipos, a união X | Y representa um valor do tipo X ou Y, enquanto a união X | None também admite None. As anotações descrevem os valores permitidos, mas não impõem automaticamente verificações em tempo de execução.

Versão: Python 3.14; repository image, production runtime not attested

Sintaxe

X | Y
X | None

Com o comportamento normal de |, X | Y cria uma união de tipos equivalente a typing.Union[X, Y]: um valor pode ser do tipo X ou Y. Em tempo de execução, porém, uma metaclasse personalizada pode redefinir __or__. Mesmo que ambos os operandos sejam tipos, X | Y pode então devolver algo diferente de uma união e, nesse caso, não equivale a typing.Union[X, Y]. É possível combinar mais tipos, por exemplo, int | str | None. Neste contexto, | combina tipos, não valores booleanos. Esta sintaxe está disponível desde Python 3.10; em Python 3.14, os objetos de união são instâncias de typing.Union, e types.UnionType é um alias desta classe.

Como união de tipos, X | None representa um valor do tipo X ou o valor None e equivale a typing.Optional[X]. Não significa que um argumento possa ser omitido: só um valor predefinido, como value: int | None = None, permite omiti-lo numa chamada. As anotações não verificam nem convertem automaticamente os argumentos em tempo de execução; o código tem de tratar None por si próprio.

A ordem dos elementos não afeta a igualdade da união, e os duplicados são removidos: int | str == str | int e int | str | int == int | str. As uniões podem ser usadas com isinstance() e issubclass(), mas os tipos parametrizados, como list[int], não são adequados a estas verificações. A verificação isinstance([1], int | list[int]) gera TypeError.

Ao avaliar uma expressão de união em tempo de execução, não combines um tipo com uma referência textual a uma classe: int | "Foo" falha. Se uma anotação precisar dessa referência, coloca toda a expressão entre aspas: "int | Foo". No exemplo, describe trata explicitamente None e, em seguida, converte os restantes valores em texto.

Identificadores de referência abrangidos por esta entrada: X | None / X | Y type union.

Exemplos

def describe(value: int | str | None) -> str:
    if value is None:
        return "missing"
    return str(value)

print(describe(7))
print(describe("hello"))
print(describe(None))
print(isinstance("hello", int | str))

Resultado

7
hello
missing
True

O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.

Fontes