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

CKTIS / Python

Referências antecipadas em anotações de tipo

Em Python 3.12, coloque entre aspas o nome de um tipo que ainda não está disponível ao definir um método. Resolva a referência mais tarde se precisar do objeto da classe.

Versão: Python 3.12

Sintaxe

# Quote a name that is not bound yet:
def f(value: "Later") -> "Later": ...

# For a union, quote the entire expression:
def g(value: "int | Later") -> None: ...

# Alternatively, as a separate module using postponed evaluation:
from __future__ import annotations

def f(value: Later) -> Later: ...

Uma referência antecipada numa anotação de tipo aponta para um tipo cujo nome ainda não está disponível no local onde a função é definida. Em Python 3.12, sem avaliação adiada, as anotações de função são avaliadas ao executar def, não ao chamar a função. Se o nome do tipo ainda não estiver disponível, usá-lo sem aspas provoca NameError. As anotações ajudam as ferramentas de verificação estática; o próprio Python não as usa para verificar argumentos nem valores devolvidos.

Em WorkItem.from_dict, -> "WorkItem" refere-se à classe cujo corpo ainda está a ser executado. Em Project.add_module, module: "Module" refere-se a uma classe definida mais abaixo. Em ambos os casos, a cadeia de caracteres literal regista a referência sem procurar logo o nome. Numa união, coloque toda a expressão entre aspas: "int | Module". Sem avaliação adiada, int | "Module" provoca TypeError, porque | recebe um tipo e uma cadeia de caracteres.

Em alternativa, coloque from __future__ import annotations no início do módulo, depois da eventual docstring. Em Python 3.12, esta importação guarda as anotações de função como cadeias de caracteres, pelo que pode escrever -> WorkItem e module: Module sem aspas. Não adia a avaliação de expressões comuns fora das anotações, como os valores predefinidos dos parâmetros.

No exemplo, __annotations__ contém cadeias de caracteres. Depois de ambas as classes estarem definidas, typing.get_type_hints() procura os nomes nos espaços de nomes relevantes e resolve as referências para os objetos das classes. Um nome em falta ainda pode provocar NameError, por exemplo se só tiver sido importado em if TYPE_CHECKING:. Não resolva anotações que não sejam de confiança: avaliar as suas expressões pode executar código.

Exemplos

from typing import get_type_hints


class WorkItem:
    def __init__(self, title: str) -> None:
        self.title = title

    @classmethod
    def from_dict(cls, data: dict[str, str]) -> "WorkItem":
        return cls(data["title"])


class Project:
    def __init__(self) -> None:
        self.modules = []

    def add_module(self, module: "Module") -> None:
        self.modules.append(module)


class Module:
    pass


print(repr(WorkItem.from_dict.__annotations__["return"]))
print(repr(Project.add_module.__annotations__["module"]))
print(get_type_hints(WorkItem.from_dict)["return"] is WorkItem)
print(get_type_hints(Project.add_module)["module"] is Module)

Resultado

'WorkItem'
'Module'
True
True

As duas primeiras linhas mostram as representações das cadeias de caracteres de `__annotations__`. Os dois resultados `True` confirmam que as anotações resolvidas correspondem exatamente aos objetos das classes `WorkItem` e `Module`.

Lições relacionadas

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

Fontes