A classe Property

Observação: é altamente recomendável a desenvolvedores que criam novos aplicativos usar a biblioteca de cliente NDB, porque ela oferece diversos benefícios em comparação com esta biblioteca de cliente, como armazenamento em cache automático de entidades por meio da API Memcache. Se você estiver usando a antiga biblioteca de cliente do DB, leia o Guia de migração de DB para NDB.

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

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

Introdução

Uma classe de propriedade descreve o tipo de valor, valor padrão, lógica de validação e outros recursos de uma propriedade de um Model. Cada classe de propriedade é uma subclasse da classe Property. A API de armazenamento de dados inclui classes de propriedade para cada um dos tipos de valor de armazenamento de dados e diversas outras que fornecem recursos adicionais além dos tipos do armazenamento de dados. Consulte Tipos e classes de propriedade.

Uma classe de propriedade pode aceitar a configuração de argumentos passados ao construtor. O construtor da classe base aceita vários argumentos normalmente compatíveis em todas as classes de propriedade, inclusive todos os fornecidos na API de armazenamento de dados. Essa configuração pode incluir um valor padrão, a necessidade ou não de um valor explícito, uma lista de valores aceitáveis e lógica personalizada de validação. Consulte a documentação de um tipo específico de propriedade para mais informações sobre como configurá-la.

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

Construtor

O construtor da classe base Property é definido conforme abaixo:

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

A superclasse das definições da propriedade de modelo.

Argumentos

verbose_name
Um nome amigável da propriedade. Este argumento precisa ser sempre o primeiro de um construtor de propriedade. A biblioteca djangoforms o usa a fim de criar rótulos para campos de formulário, e outros podem usá-lo com uma finalidade semelhante.
name
O nome de armazenamento da propriedade, usado em consultas. Ele assume como padrão o nome de atributo usado na propriedade. As classes de modelo têm atributos além das propriedades (que não podem ser usados em propriedades). Por isso, uma propriedade pode usar name para usar um nome de atributo reservado como nome da propriedade no armazenamento de dados e um nome diferente no atributo da propriedade. Consulte Nomes de propriedades não permitidos para mais informações.
default

Um valor padrão para a propriedade. Se o valor da propriedade jamais receber um valor ou receber um valor None, o valor será considerado o valor padrão.

Observação: as definições de classe Model são armazenadas em cache com o restante do código do aplicativo. Isso inclui o armazenamento em cache dos valores padrão das propriedades. Não defina um padrão na definição do modelo com dados específicos da solicitação (como users.get_current_user()). Em vez disso, defina um método __init__() para a classe Model que inicializa os valores da propriedade.

required

Se True, a propriedade não poderá ter um valor None. Uma instância de modelo precisa inicializar todas as propriedades obrigatórias no construtor. Dessa maneira, a instância não é criada com valores ausentes. 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 obrigatória e que tenha um valor padrão vai utilizá-lo se não receber um valor no construtor. No entanto, a propriedade não poderá ser atribuída a um valor None, e não haverá maneira automática de restaurar o valor padrão depois que outro valor ter sido atribuído. Você sempre pode acessar o atributo default da propriedade para receber esse valor e atribuí-lo explicitamente.

validator
Uma função que precisa ser chamada para validar o valor da propriedade quando este é atribuído. A função utiliza o valor como o único argumento dela e vai gerar uma exceção se o valor for inválido. O validador indicado será chamado depois da realização de outra validação, como a verificação de valor de uma propriedade obrigatória. Quando uma propriedade não obrigatória não recebe um valor, o validador é chamado com argumento None.
choices
Uma lista de valores aceitáveis para a propriedade. Se definido, não será possível atribuir um valor fora da lista à propriedade. Assim como acontece com required e outra validação, uma instância de modelo precisa inicializar todas as propriedades com opções. Dessa maneira, a instância não é criada com valores inválidos. Se choices for None, todos os valores que passarem na validação serão aceitáveis.
indexed

Se essa propriedade precisa ser incluída nos índices internos e definidos pelo desenvolvedor. Se False, as entidades gravadas no armazenamento de dados jamais serão retornadas por consultas que classificam ou filtram essa propriedade, semelhantes às propriedades Blob e Text.

Observação: todas as propriedades indexadas adicionam um pequeno volume de sobrecarga, custo de CPU e latência a chamadas put() e delete(). Se você jamais precisar filtrar ou classificar uma propriedade, considere usar indexed=False para evitar essa sobrecarga. No entanto, tome cuidado. Se depois decidir que você quer que a propriedade seja indexada, alterá-la de volta para indexed=True só afetará as gravações desse ponto em diante. As entidades originalmente escritas com indexed=False não serão reindexadas.

Atributos da classe

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

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

Métodos de instância

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

default_value()

Retorna o valor padrão da propriedade. A implementação base usa o valor do argumento default passado para o construtor. Uma classe de propriedade pode substituir isso para fornecer um comportamento de valor padrão especial, como o recurso auto-now de DateTimeProperty.

validate(value)

A rotina de validação completa da propriedade. Caso value seja válido, ele retorna o valor inalterado ou adaptado ao tipo obrigatório. Do contrário, ele vai gerar uma exceção apropriada.

A implementação base verifica se o valor não é None caso obrigatório (o argumento obrigatório ao construtor Property base). O valor é uma das opções válidas caso a propriedade tenha sido configurada com as opções (o argumento choices), ele passa o validador personalizado, caso haja um (o argumento validator).

A rotina de validação é chamada quando é instanciado um modelo usando o tipo de propriedade (com valores padrão ou inicializados) e quando é atribuído um valor a uma propriedade desse tipo. A rotina não precisa ter efeitos colaterais.

empty(value)

Retorna True caso o valor seja considerado um valor vazio para esse tipo de propriedade. A implementação base equivale a not value, suficiente para a maioria dos tipos. Outros tipos, como um booleano, podem ignorar este método com um teste mais apropriado.

get_value_for_datastore(model_instance)

Retorna o valor que precisa ser armazenado para essa propriedade na instância de modelo dada no armazenamento de dados. A implementação básica retorna simplesmente o valor nativo do Python da propriedade na instância de modelo. Uma classe de propriedade pode ignorar isto para utilizar um tipo de dados diferente daquele da instância de modelo para o armazenamento de dados ou ainda para realizar outra conversão de dados imediatamente antes de armazenar a instância de modelo.

make_value_from_datastore(value)

Retorna a representação nativa do Python do valor indicado do armazenamento de dados. A implementação base simplesmente retorna o valor. Uma classe de propriedade pode ignorá-la para usar a instância de modelo um tipo de dados diferente daquele do armazenamento de dados.

make_value_from_datastore_index_value(value)

Retorna a representação nativa do Python do valor indicado do índice do armazenamento de dados. A implementação base simplesmente retorna o valor. Uma classe de propriedade pode ignorá-la para usar a instância de modelo um tipo de dados diferente daquele do armazenamento de dados.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Python 2