My favorites | Português | Sign in

A classe Property

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 os valores são validados e como são armazenados no armazenamento de dados.

Property é fornecida 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 Modelo. 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 Property.

Uma classe de propriedade pode aceitar a configuração a partir de argumentos passados ao construtor. O construtor da classe base suporta diversos argumentos que são suportados normalmente em todas as classes de propriedade, incluindo todos aqueles fornecidos na API de armazenamento de dados. Esta 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 obter 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 para uma instância de 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 de classe de propriedade são "descritores" que personalizam o comportamento dos atributos das instâncias de Model. Para obter mais informações sobre descritores, consulte a documentação sobre Python.

Construtor

O construtor da classe base Property é definido como é mostrado abaixo:

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

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

Argumentos:

verbose_name
Um nome amigável da propriedade. Este argumento deve ser sempre o primeiro de um construtor de propriedade. A biblioteca djangoforms utiliza esse argumento para criar rótulos para campos de formulário e outras podem usá-lo para uma finalidade semelhante.
name
O nome de armazenamento da propriedade, usado nas consultas. O padrão é o nome de atributo usado para a propriedade. Como as classes de modelo possuem atributos além das propriedades (e que não podem ser usados para propriedades), uma propriedade pode utilizar name para usar um nome de atributo reservado como nome da propriedade no armazenamento de dados e um nome diferente para o atributo da propriedade. Para obter mais informações, consulte Nomes de propriedade não permitidos.
default

Um valor padrão para a propriedade. Se não for dado um valor à propriedade ou se o valor dado for None, o valor será considerado o padrão.

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

required

Se True, o valor da propriedade não pode ser None. Uma instância de modelo deve inicializar todas as propriedades obrigatórias em seu construtor, para que a instância não seja criada com valores ausentes. A tentativa de criar uma instância sem a inicialização de uma propriedade obrigatória ou de atribuir None a uma propriedade obrigatória emitirá um BadValueError.

Uma propriedade obrigatória e que possui valor padrão irá utilizá-lo caso não receba um valor no construtor. Entretanto, não é possível atribuir o valor None à propriedade e não há uma forma automática de restaurar o valor padrão após a atribuição de outro valor. Para obter este valor e atribuí-lo explicitamente, acesse o atributo default da propriedade.

validator
Uma função que deve ser chamada para validar o valor da propriedade quando este é atribuído. A função toma o valor como seu único argumento e emite uma exceção se o valor não for válido. O validador dado será chamado após a realização de outra validação, como a verificação de valor de uma propriedade obrigatória.
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 em required e outras validações, uma instância de modelo deve 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 passarem na validação serão aceitáveis.

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 valor nativo de Python.

Métodos da instância

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

default_value()

Retorna o valor padrão para a propriedade. A implementação básica utiliza o valor do argumento default passado ao construtor. Uma classe de propriedade pode ignorar isto para fornecer um comportamento especial de valor padrão, como o recurso auto-now de DateTimeProperty.

validate(valor)

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

A implementação básica verifica se o valor não é None caso seja obrigatório (o argumento required no construtor base da Property), se o valor é uma das opções válidas caso a propriedade tenha sido configurada com opções (o argumento choices) e se o valor passa na validação padrão, se houver (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 deve ter efeitos colaterais.

empty(valor)

Retorna True se o valor for considerado vazio para este tipo de propriedade. A implementação básica é equivalente a not value, sendo suficiente para a maioria dos tipos. Outros tipos, como o booleano, podem ignorar este método com um teste mais apropriado.

get_value_for_datastore(model_instance)

Retorna o valor que deve ser armazenado para esta propriedade na instância de modelo dada no armazenamento de dados. A implementação básica retorna simplesmente o valor nativo de 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 de Python para o valor dado do armazenamento de dados. A implementação básica retorna simplesmente o valor. Uma classe de propriedade pode ignorar isso para utilizar um tipo de dados diferente do armazenamento de dados na instância de modelo.