A classe Property

Nota: os programadores que criam novas aplicações são fortemente aconselhados a usar a biblioteca de cliente NDB, que tem várias vantagens em comparação com esta biblioteca de cliente, como o armazenamento em cache automático de entidades através da API Memcache. Se estiver a usar atualmente a biblioteca cliente DB mais antiga, leia o guia de migração de DB para NDB

A classe Property é a superclasse das definições de propriedades para modelos de dados. Uma classe Property define o tipo de valor de uma propriedade, como os valores são validados e como os valores são armazenados no arquivo de dados.

O Property é fornecido pelo módulo google.appengine.ext.db.

Introdução

Uma classe de propriedade descreve o tipo de valor, o valor predefinido, a lógica de validação e outras caraterísticas de uma propriedade de um Model. Cada classe de propriedade é uma subclasse da classe de propriedade. A API Datastore inclui classes de propriedades para cada um dos tipos de valores do Datastore e vários outros que oferecem funcionalidades adicionais além dos tipos do Datastore. Consulte o artigo Tipos e classes de propriedades.

Uma classe de propriedade pode aceitar a configuração de argumentos transmitidos ao construtor. O construtor da classe base suporta vários argumentos que são normalmente suportados em todas as classes de propriedades, incluindo todos os fornecidos na API Datastore. Essa configuração pode incluir um valor predefinido, se é necessário ou não um valor explícito, uma lista de valores aceitáveis e uma lógica de validação personalizada. Consulte a documentação de um tipo de propriedade específico para obter mais informações sobre a configuração da propriedade.

Uma classe de propriedade define o modelo de uma propriedade da base de dados. Não contém o valor da propriedade para uma instância do modelo. As instâncias da classe Property pertencem à classe Model e não às instâncias da classe. Em termos de Python, as instâncias da classe de propriedades são "descritores" que personalizam o comportamento dos atributos das instâncias do modelo. Consulte a documentação do Python para obter mais informações sobre descritores.

Construtor

O construtor da classe base Property é definido da seguinte forma:

class Property(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None, indexed=True)

A superclasse das definições de propriedades do modelo.

Argumentos

verbose_name

Um nome intuitivo da propriedade. Este tem de ser sempre o primeiro argumento de um construtor de propriedades. A biblioteca djangoforms usa-o para criar etiquetas para campos de formulários, e outros podem usá-lo para um propósito semelhante.

name

O nome de armazenamento da propriedade, usado em consultas. Esta opção é predefinida como o nome do atributo usado para a propriedade. Uma vez que as classes de modelos têm atributos diferentes das propriedades (que não podem ser usadas para propriedades), uma propriedade pode usar name para usar um nome de atributo reservado como o nome da propriedade no arquivo de dados e usar um nome diferente para o atributo da propriedade. Consulte o artigo Nomes de propriedades não permitidos para mais informações.

predefinição

Um valor predefinido para a propriedade. Se o valor da propriedade nunca receber um valor ou receber um valor de None, o valor é considerado o valor predefinido.

Nota: as definições da classe de modelo são colocadas em cache juntamente com o resto do código da aplicação. Isto inclui o armazenamento em cache dos valores predefinidos das propriedades. Não defina um valor predefinido na definição do modelo com dados específicos do pedido (como users.get_current_user()). Em alternativa, defina um método __init__() para a classe Model que inicialize os valores das propriedades.

obrigatório

Se True, a propriedade não pode ter um valor de None. Uma instância do modelo tem de inicializar todas as propriedades obrigatórias no respetivo construtor para que a instância não seja criada com valores em falta. Uma tentativa de criar uma instância sem inicializar uma propriedade obrigatória ou uma tentativa de atribuir None a uma propriedade obrigatória gera um BadValueError.

Uma propriedade que é obrigatória e tem um valor predefinido usa o valor predefinido se não for indicado nenhum no construtor. No entanto, não é possível atribuir à propriedade um valor de None, e não existe uma forma automática de restaurar o valor predefinido depois de ter sido atribuído outro valor. Pode sempre aceder ao atributo default da propriedade para obter este valor e atribuí-lo explicitamente.

validator

Uma função que deve ser chamada para validar o valor da propriedade quando o valor é atribuído. A função usa o valor como o seu único argumento e gera uma exceção se o valor for inválido. O validador fornecido é chamado após a ocorrência de outra validação, como a verificação de que uma propriedade obrigatória tem um valor. Quando não é atribuído um valor a uma propriedade não obrigatória, o validador é chamado com o argumento None.

escolhas

Uma lista de valores aceitáveis para a propriedade. Se estiver definida, não é possível atribuir à propriedade um valor que não esteja na lista. Tal como acontece com os campos obrigatórios e outras validações, uma instância do modelo tem de inicializar todas as propriedades com opções para que a instância não seja criada com valores inválidos. Se choices for None, todos os valores que, de outra forma, passariam na validação são aceitáveis.

indexado

Se esta propriedade deve ser incluída nos índices incorporados e definidos pelo programador. Se False, as entidades escritas no arquivo de dados nunca são devolvidas por consultas que ordenam ou filtram esta propriedade, de forma semelhante às propriedades Blob e Text.

Nota: cada propriedade indexada adiciona uma pequena quantidade de sobrecarga, custo de CPU e latência às chamadas put() e delete(). Se nunca precisar de filtrar nem ordenar uma propriedade, considere usar indexed=False para evitar essa sobrecarga. No entanto, tenha cuidado! Se decidir mais tarde que quer que a propriedade seja indexada, a alteração para indexed=True só afeta as gravações a partir desse momento. As entidades que foram originalmente escritas com indexed=False não são reindexadas.

Atributos de classe

As subclasses da classe Property definem o seguinte atributo de classe:

data_type

O tipo de dados ou a classe Python que a propriedade aceita como um valor nativo do Python.

Métodos de instância

As instâncias das classes de propriedades têm os seguintes métodos:

default_value()

Devolve o valor predefinido da propriedade. A implementação base usa o valor do argumento predefinido transmitido ao construtor. Uma classe de propriedade pode substituir isto para fornecer um comportamento de valor predefinido especial, como a funcionalidade de data/hora automática de DateTimeProperty.

validate(value)

A rotina de validação completa da propriedade. Se valor for válido, devolve o valor, inalterado ou adaptado ao tipo necessário. Caso contrário, gera uma exceção adequada.

A implementação base verifica se value não é None, se necessário (o argumento required para o construtor de propriedades base), se o valor é uma das opções válidas se a propriedade tiver sido configurada com opções (o argumento choices) e se o valor passa no validador personalizado, se existir (o argumento validator).

A rotina de validação é chamada quando um modelo que usa o tipo de propriedade é instanciado (com valores predefinidos ou inicializados) e quando é atribuído um valor a uma propriedade do tipo. A rotina não deve ter efeitos secundários.

empty(value)

Devolve True se value for considerado um valor vazio para este tipo de propriedade. A implementação base é equivalente a not value, o que é suficiente para a maioria dos tipos. Outros tipos, como um tipo booleano, podem substituir este método por um teste mais adequado.

get_value_for_datastore(model_instance)

Devolve o valor que deve ser armazenado no arquivo de dados para esta propriedade na instância do modelo especificada. A implementação base devolve simplesmente o valor nativo do Python da propriedade na instância do modelo. Uma classe de propriedade pode substituir esta opção para usar um tipo de dados diferente para o arquivo de dados do que para a instância do modelo ou para realizar outra conversão de dados imediatamente antes de armazenar a instância do modelo.

make_value_from_datastore(value)

Devolve a representação nativa do Python para o valor fornecido do arquivo de dados. A implementação base devolve simplesmente o valor. Uma classe de propriedade pode substituir esta opção para usar um tipo de dados diferente para a instância do modelo do que para o arquivo de dados.

make_value_from_datastore_index_value(value)

Devolve a representação nativa do Python para o valor especificado do índice da base de dados. A implementação base devolve simplesmente o valor. Uma classe de propriedade pode substituir esta opção para usar um tipo de dados diferente para a instância do modelo do que para o arquivo de dados.