Modelar objetos de dados com dataclasses

Quando uma classe serve principalmente para guardar dados, uma dataclass pode gerar automaticamente métodos comuns. Importe o decorador da biblioteca padrão e aplique-o à classe com @dataclass.

Uma Tarefa tem dois campos: título e prioridade.

Os campos anotados orientam a criação dos métodos padrão.

Nesta classe, titulo e prioridade viram argumentos do __init__ gerado. A representação também mostra os valores dos campos.

Execute este código no seu editor ou no interpretador Python.

As anotações declaram os campos para a dataclass, mas não verificam nem convertem automaticamente os argumentos em tempo de execução. Portanto, este código é aceito na construção, embora o valor não corresponda ao tipo indicado:

Em uma dataclass, um campo sem valor padrão se torna um argumento obrigatório do __init__ gerado. Um campo com = recebe um padrão e pode ser omitido na construção.

Na declaração básica, coloque todos os campos obrigatórios antes dos campos com padrão. Essa ordem permite que o inicializador tenha uma assinatura válida e previsível.

A ordem dos campos é preservada nos argumentos gerados.

Crie este arquivo e execute-o no seu computador.

Use field para configurar um campo de dataclass quando um valor padrão precisa ser criado para cada instância. Listas e dicionários são mutáveis: se fossem compartilhados como padrão, uma alteração em uma tarefa poderia aparecer em outra.

Por isso, dataclasses rejeitam uma lista ou um dicionário escrito diretamente como valor padrão de um campo. A solução é default_factory.

Cada construção sem argumento para etiquetas aciona uma nova criação de lista.

Digite e execute este exemplo no seu editor ou no interpretador Python.

Ao omitir etiquetas, o inicializador gerado chama list() para aquela construção. Assim, primeira.etiquetas e segunda.etiquetas são objetos distintos. O campo continua aceitando uma lista fornecida explicitamente por quem cria a tarefa.

Agora execute este complemento após o código anterior.

default_factory só é usado quando o argumento etiquetas é omitido. Ao passar etiquetas_da_equipe para as duas tarefas, você fornece a mesma lista às duas instâncias. Não há cópia automática; por isso, alterar uma referência altera o conteúdo visto pela outra.

Em uma dataclass, o inicializador gerado recebe os argumentos e atribui os campos à instância. Se a classe define __post_init__, ele é chamado automaticamente em seguida.

Esse método é um bom lugar para ajustar valores e verificar regras do domínio que precisam ser verdadeiras no momento da construção.

A normalização acontece antes das verificações que dependem do valor ajustado.

strip() remove espaços no início e no fim antes de testar se restou conteúdo.

A chamada automática acontece quando Tarefa(...) cria a instância. Depois disso, uma atribuição comum a um campo não chama __post_init__ novamente.

Por exemplo, tarefa.prioridade = -1 altera o atributo sem disparar a validação acima. Portanto, __post_init__ protege a entrada na construção, não todas as mudanças futuras.

Por padrão, a dataclass gera __repr__ e __eq__ usando seus campos. Com field, você pode decidir separadamente se um campo aparece na representação (repr) e se participa da igualdade (compare).

Isso é útil para etiquetas: elas podem ser metadados da tarefa, sem definir se duas tarefas representam o mesmo valor.

A representação e a igualdade consultam configurações distintas.

Use repr=False e compare=False no mesmo campo quando ele não deve aparecer nem definir igualdade.

Com o padrão eq=True, a igualdade gerada compara os campos cujo compare é verdadeiro, mas apenas entre instâncias do mesmo tipo concreto. Assim, uma instância de Tarefa não é igual a uma instância de outra classe, mesmo que os valores dos atributos pareçam iguais.

No decorador, repr=False impede a geração de __repr__, e eq=False impede a geração de __eq__. Essas opções não removem uma implementação que já exista na hierarquia da classe; apenas dizem à dataclass para não gerar aquele método.

Uma dataclass comum gera igualdade, mas não cria automaticamente métodos como < e >. Portanto, comparar duas tarefas com < falha até que você peça essa geração.

Use order=True no decorador para gerar __lt__, __le__, __gt__ e __ge__. Essa opção depende de eq=True: não é válido solicitar ordenação com eq=False.

Prioridade menor vem primeiro; em empate, o título decide.

A ordem segue os campos declarados que participam da comparação.

Os campos participantes são consultados na ordem em que aparecem na classe, como numa comparação de tuplas. Para Tarefa, o critério é equivalente a comparar (prioridade, titulo).

Assim, prioridade é o critério principal e título só resolve empates. As etiquetas não influenciam a ordem porque foram declaradas com compare=False.

Ao usar @dataclass(frozen=True), a instância é construída normalmente, mas seus campos não podem ser atribuídos nem removidos pelas operações usuais depois da construção. Isso é útil quando o objeto deve representar um valor estável.

A camada congelada protege a referência armazenada no campo; ela não congela automaticamente o objeto para o qual essa referência aponta.

Crie esta classe em um arquivo Python e execute os exemplos nas próximas telas.

Depois de criada, a tentativa de substituir titulo, substituir etiquetas ou remover um desses campos gera FrozenInstanceError. Essa exceção indica que a operação tentou alterar a estrutura da instância congelada.

Execute uma operação por vez para observar a exceção.

O campo etiquetas continua apontando para a mesma lista criada ou recebida na construção. Portanto, chamar um método mutável da própria lista, como append, altera seu conteúdo sem reatribuir o campo.

Este código não tenta substituir etiquetas; ele modifica a lista já armazenada.

Quando você não define __hash__, a dataclass decide seu comportamento a partir de eq e frozen:

• eq=True e frozen=False (o padrão): define __hash__ como None. A instância não é hashável.
• eq=True e frozen=True: gera __hash__ usando os campos que participam da comparação.
• eq=False: não altera o hash herdado, com ou sem frozen=True. Em uma classe que deriva diretamente de object, o hash continua baseado na identidade.

A primeira regra evita usar como chave um objeto mutável cuja igualdade pode mudar depois de inserido em um dicionário ou conjunto.

Compare as três configurações mais comuns.

Uma chave congelada com str e int pode ser usada em um conjunto.

Como eq=True é padrão, ChaveTarefa compara prioridade e titulo. Como também é congelada, a dataclass gera um hash compatível com esses campos.

Um campo com compare=False fica fora da igualdade e, por padrão, também fica fora do hash gerado. Assim, metadados que não definem o valor da chave não precisam influenciar sua identificação.

Execute este exemplo no seu computador.

A referência ao campo não pode ser substituída; o conteúdo da lista ainda pode mudar.

Use Tarefa para o objeto que muda durante o trabalho: ela tem título, prioridade, estado de conclusão e etiquetas. Para agrupamento em conjuntos, use ChaveTarefa, menor e congelada.

Em Tarefa, apenas prioridade e titulo definem igualdade e ordenação. As etiquetas são metadados: não aparecem no repr nem participam das comparações.

Crie um arquivo chamado modelo_tarefa.py, copie o código completo abaixo e execute python modelo_tarefa.py. Se todos os assert passarem, o script termina sem mostrar erro.