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

CKTIS / Python

União de tipos X | None e anotações com referências antecipadas

Usa `X | None` para aceitar um valor do tipo `X` ou `None`. Se a classe for definida mais adiante, coloca a anotação inteira entre aspas ou usa a importação de `__future__`.

Versão: Python 3.12

Sintaxe

# Without the future import
class X: ...

value: X | None
value: "X | None"
def make_board(ticket: "Ticket") -> "Board": ...

# Alternative in Python 3.12: copy the next three lines without
# their comment prefixes into a separate module, with the import first.
# from __future__ import annotations
# value: X | None
# def make_board(ticket: Ticket) -> Board: ...

Em Python 3.12, X | None aceita um valor do tipo X ou None. Esta sintaxe está disponível desde Python 3.10 e equivale a typing.Optional[X] e a typing.Union[X, None], não a uma chamada a typing.Union(...). Aqui, | normalmente cria uma união de tipos, não faz um OU bit a bit entre inteiros; uma metaclasse com o seu próprio método __or__ pode alterar o resultado. A anotação não impõe o tipo em tempo de execução nem permite omitir um argumento sem valor predefinido.

Sem a importação de __future__, o Python 3.12 avalia as anotações normais de uma função quando esta é definida. Se User ainda não estiver definido, User | None lança NameError. Coloca a união inteira entre aspas: "User|None". Se for avaliado de imediato, "User" | None lança TypeError. Da mesma forma, "Ticket" e "Board" numa assinatura referem-se a classes definidas mais adiante, não a valores do tipo str.

Em alternativa, coloca from __future__ import annotations no início do módulo e escreve User | None, Ticket e Board sem aspas nas anotações. O Python 3.12 passa a guardar as anotações como cadeias de caracteres. Esta importação não adia a avaliação de uma atribuição normal como Alias = User | None.

Depois de as classes estarem definidas, typing.get_type_hints() pode resolver as referências guardadas em __annotations__. Nessa altura, os nomes têm de estar disponíveis no espaço de nomes adequado; se necessário, fornece globalns ou localns. Um nome em falta pode causar NameError. A avaliação de anotações pode executar código arbitrário, pelo que não deves resolver anotações de fontes não fiáveis.

Exemplos

from typing import get_type_hints


def make_board(ticket: "Ticket") -> "Board":
    return Board(ticket)


class Ticket:
    def __init__(self, owner: "User|None") -> None:
        self.owner = owner


class Board:
    def __init__(self, ticket: Ticket) -> None:
        self.ticket = ticket


class User:
    pass


print(Ticket.__init__.__annotations__["owner"])
print(get_type_hints(Ticket.__init__)["owner"] == (User | None))
board_hints = get_type_hints(make_board)
print(board_hints["ticket"] is Ticket, board_hints["return"] is Board)
print(make_board(Ticket(None)).ticket.owner is None)

Resultado

User|None
True
True True
True

A primeira linha mostra a cadeia original `User|None`. A segunda confirma a resolução da união e a terceira, a resolução das duas referências a classes. A quarta mostra que o código cria um `Ticket` cujo proprietário é `None`.

Lições relacionadas

  • Python · Lição 1 · Avançado · Versão: 5

Fontes