Observação: o Python 2.7 chegou ao fim do suporte em 31 de janeiro de 2024. Os aplicativos Python 2.7 atuais continuarão a ser executados e a receber tráfego. No entanto, o App Engine pode bloquear a reimplantação de aplicativos que usam ambientes de execução após o término da data de suporte. Recomendamos que você migre para a versão compatível mais recente do Python.

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 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, verbose_name=None, verbose_name=None, verbose_name=False, verbose_name=None, verbose_name=None, verbose_name=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.

padrão

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 com o restante do código do aplicativo. Isso inclui o armazenamento em cache dos valores padrão das propriedades. Não defina um default 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, o valor da propriedade não pode ser 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. 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. Você sempre pode acessar o atributo default da propriedade para receber esse valor e atribuí-lo explicitamente.

validador

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 nunca serão retornadas por consultas que classificam ou filtram essa propriedade, semelhante às propriedades Blob e Text.

Observação: toda propriedade indexada adiciona uma pequena quantidade de código extra, uso de CPU e latência para chamadas put() e delete(). Se você nunca vai precisar filtrar ou classificar em uma propriedade, considere usar indexed=False para evitar esse código extra. No entanto, tome cuidado. Se mais tarde você decidir que quer que a propriedade seja indexada, mudá-la para indexed=True apenas afetará gravações daquele ponto em diante. Entidades gravadas originalmente com indexed=False não serão indexadas novamente.

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 básica verifica se value não é None caso seja obrigatório (o argumento required no construtor base de 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 precisa ter efeitos colaterais.

empty(value)

Retorna True caso o valor seja considerado um valor vazio para esse tipo de propriedade. A implementação básica é equivalente a not value, sendo 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.