Aviso: nos próximos meses, vamos reorganizar o site de documentação do App Engine para facilitar a localização de conteúdo e o alinhamento ao restante dos produtos do Google Cloud. O mesmo conteúdo estará disponível, mas a navegação agora corresponderá ao restante dos produtos do Cloud.

O Python 2 não é mais compatível com a comunidade. Recomendamos que você migre aplicativos do Python 2 para o Python 3.

A classe Model

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.

Model é a superclasse para definições de modelo de dados.

Model é definido no módulo google.appengine.ext.db.

Introdução

Um aplicativo define um modelo de dados por meio de uma classe que faz da Model uma subclasse. As propriedades do modelo são definidas por meio dos atributos de classe e instâncias da classe Property. Por exemplo:

class Story(db.Model):
  title = db.StringProperty()
  body = db.TextProperty()
  created = db.DateTimeProperty(auto_now_add=True)

Ao instanciar uma subclasse da classe Model, um aplicativo cria uma nova entidade de dados. As propriedades de uma entidade são atribuídas usando os atributos da instância ou como argumentos de palavra-chave do construtor.

s = Story()
s.title = "The Three Little Pigs"

s = Story(title="The Three Little Pigs")

O nome da subclasse de modelo é usado como nome do tipo de entidade do Datastore. O Datastore reserva todos os nomes de tipo que começam com dois sublinhados (__). Não utilize esses nomes nas subclasses de modelos.

Os nomes dos atributos são usados como nomes das propriedades correspondentes de uma entidade. Os atributos das instâncias de modelos com nomes que começam com um sublinhado (_) são ignorados, assim o aplicativo usará tais atributos para armazenar dados em uma instância de modelo que não foi salva no Datastore.

O Datastore e a API da classe de modelos impõem diversas restrições em relação aos nomes de propriedades e aos atributos da instância de modelo. Para uma descrição completa, veja Nomes de propriedades não permitidos.

Cada entidade tem uma chave, um identificador exclusivo que representa a entidade. A chave inclui um nome de chave opcional, uma string exclusiva entre as entidades do tipo fornecido. O tipo e o nome da chave da entidade podem ser usados com os métodos Key.from_path() e Model.get_by_key_name() para recuperar a entidade.

Uma entidade também tem uma entidade pai opcional. Os relacionamentos pai-filha formam grupos de entidades, que são usados para controlar as transações e a localização dos dados no Datastore. Um aplicativo cria um relacionamento pai-filha entre duas entidades, transferindo a entidade pai para o construtor da entidade filha como o argumento parent.

O método Model.get_or_insert() pode ser usado para recuperar uma entidade não existente, criando-a no Datastore, se necessário:

keyname = "some_key"
s = Story.get_or_insert(keyname, title="The Three Little Pigs")

Observação: uma instância de modelo não tem uma entidade correspondente no Datastore até ser gravada (put) pela primeira vez, seja explicitamente ou por meio de Model.get_or_insert().

Para criar um dict que seja cópia dos dados de instância de um modelo, use a função db.to_dict.

Construtor

O construtor da classe Model é definido da seguinte maneira:

class Model (parent=None, key_name=None, **kwds)

A superclasse para as definições de modelo de dados.

Durante a construção, cada método validate() da propriedade é chamado. As exceções de tais chamadas se estendem para os autores das chamadas deste construtor.

Argumentos

parent

A instância ou chave do modelo da entidade que é o pai da nova entidade.

key_name

O nome da chave da entidade. Esse nome se torna parte da chave principal. Caso seja None, um código numérico gerado pelo sistema será usado para a chave.

Para o valor key_name, não use o formato __*__.

O nome da chave é armazenado como uma string Unicode, com valores str convertidos como texto ASCII.

Chamar put() nesse objeto substituirá qualquer entidade do Datastore atual pela mesma chave.

kwds

Valores iniciais das propriedades da instância, como argumentos de palavras-chave. Cada nome corresponde a um atributo definido na classe Model.

Outros argumentos de palavras-chave

key

A instância Key explícita para a entidade. Não pode ser usada com key_name ou parent. Caso seja None, ela recua sobre o comportamento de key_name e parent. É útil quando você usa allocate_ids() para reservar códigos numéricos para novas entidades.

Para o valor de key, use uma instância Key.

Chamar put() nesse objeto substituirá qualquer entidade do Datastore atual pela mesma chave.

Métodos de classe

A classe Model tem os seguintes métodos de classe:

Model.get (chaves)

Recupera a(s) instância(s) do modelo para a(s) chave(s) fornecida(s). As chaves têm de representar entidades do tipo do modelo. Caso uma chave fornecida não seja do tipo correto, uma exceção KindError será gerada.

Esse método é semelhante à função db.get(), com outra verificação de tipos.

Argumentos

keys

A chave da entidade a ser recuperada, uma representação de string da chave, uma lista de chaves ou as representações de string correspondentes.

read_policy

Política de leitura que especifica o nível desejado de consistência de dados:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.

Observação: consultas globais (não ancestrais) ignoram esse argumento.

deadline

Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é aumentado além do valor padrão de 60 segundos, mas diminuído para garantir que uma determinada operação falhe rapidamente. Por exemplo, se quiser retornar uma resposta mais rápida ao usuário, repita a operação, tente uma diferente ou adicione essa operação a uma fila de tarefas.

Quando keys consiste em uma chave única ou a representação de string correspondente, este método retorna a instância de modelo associada à chave, caso ela esteja no Datastore. Do contrário, retornará None. Quando keys é uma lista, o valor de retorno é uma lista correspondente de instâncias do modelo com valores None onde não houver entidades para uma determinada chave.

Consulte também a função db.get().

Model.get_by_id (ids, parent=None)

Recupera a(s) instância(s) do modelo para o(s) código(s) numérico(s) fornecido(s).

Argumentos

ids

Um código de entidade numérico ou uma lista de códigos numéricos.

parent

A entidade pai das entidades solicitadas, como um modelo ou chave, ou None, que é o padrão quando as entidades solicitadas não têm um pai. Várias entidades solicitadas por uma chamada precisam ter o mesmo pai.

read_policy

Política de leitura que especifica o nível desejado de consistência de dados:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.

Observação: consultas globais (não ancestrais) ignoram esse argumento.

deadline

Caso ids seja composto de um único código numérico, esse método retornará a instância de modelo associada ao código, desde que ele esteja no Datastore. Caso contrário, retornará None. Caso ids seja uma lista, o valor retornado será uma lista correspondente de instâncias do modelo com valores None, em que não há entidades para um determinado código numérico.

Model.get_by_key_name (key_names, parent=None)

Recupera a(s) instância(s) do modelo para a(s) chave(s) ou nome(s) de chave(s) fornecido(s).

Argumentos

key_names

Um nome de chave ou uma lista de nomes de chave.

parent

A entidade pai das entidades solicitadas, como instância de modelo ou chave ou None, que é o padrão quando as entidades solicitadas não têm um pai. Várias entidades solicitadas por uma chamada precisam ter o mesmo pai.

read_policy

Política de leitura que especifica o nível desejado de consistência de dados:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas limitados a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Abrange diversos grupos de entidades, mas de vez em quando retorna resultados obsoletos. Em geral, as consultas de consistência eventual são executadas mais rapidamente do que as de consistência forte, mas não há garantias.

Observação: consultas globais (não ancestrais) ignoram esse argumento.

deadline

Quando key_names consiste em um único nome de chave, este método retorna a instância de modelo associada ao nome, caso ele esteja no Datastore. Do contrário, retornará None. Caso key_names seja uma lista, o valor retornado será uma lista correspondente de instâncias do modelo com valores None, em que não há entidades para um determinado nome de chave.

Model.get_or_insert (key_name, **kwds)

Tenta adquirir a entidade do tipo do modelo com o nome de chave fornecido. Se existir, ela será retornada por get_or_insert(). Se não existir, uma nova entidade com o tipo, o nome e os parâmetros dados em kwds é criada, armazenada e retornada.

As operações "get", assim como as operações "put" subsequentes (possíveis) são agrupadas em uma transação para garantir atomicidade. Isso significa que get_or_insert() nunca substituirá uma entidade existente. Ela incluirá uma nova entidade apenas caso não tenha entidade alguma com o tipo e nome fornecidos. Em outras palavras, get_or_insert() é equivalente ao seguinte código Python:

def txn(key_name, **kwds):
  entity = Story.get_by_key_name(key_name, parent=kwds.get('parent'))
  if entity is None:
    entity = Story(key_name=key_name, **kwds)
    entity.put()
  return entity

def get_or_insert(key_name, **kwargs):
  return db.run_in_transaction(txn, key_name, **kwargs)

get_or_insert('some key', title="The Three Little Pigs")

Argumentos

key_name: O nome da chave da entidade
kwds: Argumentos de palavra-chave a serem transferidos para o construtor da classe de modelo, se não tiver uma instância com o nome de chave especificado. O argumento parent será obrigatório caso a entidade desejada tenha um pai.

Observação: get_or_insert() não aceita um argumento read_policy ou deadline.

O método retorna uma instância da classe de modelo que representa a entidade solicitada, seja ela existente ou criada pelo método. Como em todas as operações do Datastore, esse método gera um TransactionFailedError, caso a transação não seja concluída.

Model.all (keys_only=False)

Retorna um objeto Query que representa todas as entidades do tipo correspondente a esse modelo. Os métodos no objeto de consulta podem aplicar filtros e ordens de classificação à consulta antes de ela ser executada. Consulte a página da classe Query para mais informações.

Argumentos

keys_only: Caso a consulta retorne entidades completas ou apenas chaves. As consultas que retornam chaves são mais rápidas e usam menos tempo de CPU do que as que retornam entidades completas.

Model.gql (query_string, *args, **kwds)

Executa uma consulta GQL nas instâncias deste modelo.

Argumentos

query_string: A parte da consulta GQL depois de SELECT * FROM model, implícita ao utilizar esse método de classe.
args: Vinculações de parâmetros posicionais, semelhantes ao construtor GqlQuery().
kwds: Vinculações de parâmetros de palavras-chave, semelhantes ao construtor GqlQuery().

s = Story.gql("WHERE title = :1", "Little Red Riding Hood")

s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")

O valor de retorno é um objeto GqlQuery, usado para acessar os resultados.

Model.kind ()

Retorna o tipo do modelo, geralmente o nome da subclasse Model.

Model.properties ()

Retorna um dicionário com todas as propriedades definidas para esta classe de modelo.

Métodos da instância

As instâncias de modelo têm os métodos abaixo:

key ()

Retorna a Key do Datastore para essa instância de modelo.

A chave de uma instância de modelo inclui o tipo de entidade da instância com um identificador exclusivo. Esse identificador é uma string de nome de chave, atribuída explicitamente pelo aplicativo no momento da criação da instância, ou é um código numérico de números inteiros, atribuído automaticamente pelo App Engine no momento em que a instância é gravada (put) no Datastore. Chamar key() antes de a instância ser atribuída a um identificador gerará uma exceção NotSavedError.

put ()

Armazena a instância de modelo no Datastore. Caso a instância de modelo tenha acabado de ser criada e nunca tenha sido armazenada, este método criará uma nova entidade de dados no Datastore. Caso contrário, ele atualizará a entidade de dados com os valores da propriedade atual.

O método retorna a chave da entidade armazenada.

Caso os dados não tenham sido confirmados, será criada uma exceção TransactionFailedError.

Argumentos

deadline: Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é configurado acima do valor padrão de 60 segundos, mas ajustado para baixo para garantir que uma determinada operação falhe rapidamente. Por exemplo, para retornar uma resposta mais rápida ao usuário, repita a operação, tente uma operação diferente ou adicione essa operação a uma fila de tarefas.

delete ()

Exclui a instância de modelo do Datastore. Caso a instância nunca tenha sido gravada (put) no Datastore, essa exclusão criará uma exceção NotSavedError.

Argumentos

deadline: Tempo máximo de espera, em segundos, para que o Datastore retorne um resultado antes de cancelar com um erro. Aceita um número inteiro ou um valor de ponto flutuante. Não é configurado acima do valor padrão de 60 segundos, mas ajustado para baixo para garantir que uma determinada operação falhe rapidamente. Por exemplo, para retornar uma resposta mais rápida ao usuário, repita a operação, tente uma operação diferente ou adicione essa operação a uma fila de tarefas.

is_saved ()

Retornará True caso a instância do modelo tenha sido gravada (put) no Datastore pelo menos uma vez.

Esse método verifica apenas se a instância foi gravada no Datastore pelo menos uma vez desde que foi criada. Ele não verifica a atualização das propriedades da instância desde a última vez em que foi gravada.

dynamic_properties ()

Retorna uma lista dos nomes de todas as propriedades dinâmicas definidas para esta instância de modelo. Isso se aplica apenas a instâncias de classes Expando. Para instâncias de modelo não Expando, é retornada uma lista vazia.

parent ()

Retorna uma instância de modelo para a entidade pai dessa instância ou None caso essa instância não tenha um pai.

parent_key ()

Retorna a Key da entidade pai dessa instância ou None caso essa instância não tenha um pai.

to_xml ()

Retorna uma representação XML da instância de modelo.

Os valores da propriedade estão em conformidade com as especificações Atom e Data.

Nomes de propriedade não permitidos

O Datastore e a respectiva API impõem diversas restrições em relação aos nomes das propriedades de entidades e atributos de instância de modelo.

O Datastore reserva todos os nomes de propriedades que começam e terminam com dois caracteres sublinhados (__*__). Não é possível que uma entidade do Datastore tenha uma propriedade com tal nome.

A API de modelo do Python ignora todos os atributos em uma classe Model ou Expando que começam com um sublinhado (_). O aplicativo usa esses atributos para associar dados aos objetos do modelo não salvos no Datastore.

Por fim, a API de modelo do Python usa atributos de objetos para definir propriedades de um modelo. Como padrão, as propriedades da entidade do armazenamento de dados são nomeadas segundo os atributos. Como a classe Model tem diversas propriedades e métodos para outros fins, esses atributos não são usados para propriedades na API do Python. Por exemplo, não é possível acessar uma propriedade de Model com o atributo key.

No entanto, uma propriedade especifica um nome para o Datastore, diferente do nome do atributo, fornecendo um argumento name para o construtor da propriedade. Isso permite que a entidade do Datastore tenha um nome de propriedade semelhante a um atributo reservado na classe Model e use um nome de atributo diferente na classe.

class MyModel(db.Model):
  obj_key = db.StringProperty(name="key")

Os nomes de atributos abaixo são reservados pela classe Model na API do Python:

all
app
copy
delete
entity
entity_type
fields
from_entity
get
gql
instance_properties

is_saved
key
key_name
kind
parent
parent_key
properties
put
setdefault
to_xml
update