O Python 2.7 atingiu o fim do suporte e vai ser descontinuado a 31 de janeiro de 2026. Após a descontinuação, não vai poder implementar aplicações Python 2.7, mesmo que a sua organização tenha usado anteriormente uma política organizacional para reativar as implementações de runtimes antigos. As suas aplicações Python 2.7 existentes vão continuar a ser executadas e a receber tráfego após a data de descontinuação. Recomendamos que migre para a versão suportada mais recente do Python.

Esta página foi traduzida pela API Cloud Translation.

A classe Model

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 Model é a superclasse para as definições do modelo de dados.

Model está definido no módulo google.appengine.ext.db.

Introdução

Uma aplicação define um modelo de dados definindo uma classe que é uma subclasse de Model. As propriedades do modelo são definidas através de atributos de classe e Property instâncias de classe. Por exemplo:

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

Uma aplicação cria uma nova entidade de dados ao instanciar uma subclasse da classe Model As propriedades de uma entidade podem ser atribuídas através de atributos da instância ou como argumentos de palavras-chave para o construtor.

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

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

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

Os nomes dos atributos são usados como os nomes das propriedades correspondentes numa entidade. Os atributos de instância do modelo cujos nomes começam com um sublinhado (_) são ignorados, pelo que a sua aplicação pode usar esses atributos para armazenar dados numa instância do modelo que não é guardada no Datastore.

A API Datastore e a classe de modelo impõem várias restrições aos nomes das propriedades e aos atributos das instâncias do modelo. Consulte a secção Nomes de propriedades não permitidos para uma descrição completa.

Cada entidade tem uma chave, um identificador exclusivo que representa a entidade. A chave pode incluir um nome da chave opcional,uma string única entre as entidades do tipo indicado. 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 obter a entidade.

Uma entidade também pode ter uma entidade principal opcional. As relações principais/secundárias formam grupos de entidades, que são usados para controlar a transacionalidade e a localidade dos dados no Datastore. Uma aplicação cria uma relação principal-secundário entre duas entidades ao transmitir a entidade principal ao construtor da entidade secundária, como o argumento parent.

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

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

Nota: uma instância do modelo não tem uma entidade correspondente no Datastore até ser escrita (put) pela primeira vez, de forma explícita ou através de Model.get_or_insert().

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

Construtor

O construtor da classe Model é definido da seguinte forma:

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

A superclasse para definições de modelos de dados.

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

Argumentos

parent

A instância ou a chave do modelo para a entidade que é a entidade principal da nova entidade.

key_name

O nome da chave da entidade. O nome passa a fazer parte da chave principal. Se None, é usado um ID numérico gerado pelo sistema para a chave.

O valor de key_name não pode ter o formato __*__.

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

A chamada put() neste objeto substitui qualquer entidade do Datastore existente com a mesma chave.

kwds

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

Argumento de palavra-chave adicional

key

A instância Key explícita da entidade. Não pode ser usado com o key_name nem o parent. Se None, recorre ao comportamento para key_name e parent. Útil quando usa allocate_ids() para reservar IDs numéricos para novas entidades.

O valor de key tem de ser uma instância Key válida.

A chamada put() neste objeto substitui qualquer entidade do Datastore existente com a mesma chave.

Métodos de classe

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

Model.get (keys)

Obtém a instância (ou instâncias) do modelo para a chave (ou chaves) fornecida. As chaves têm de representar entidades do tipo do modelo. Se uma chave fornecida não for do tipo correto, é criada uma exceção KindError.

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

Argumentos

chaves

Chave da entidade a obter, uma representação de string da chave ou uma lista de chaves ou das respetivas representações de string.

read_policy

Leia a política que especifica o nível de consistência de dados pretendido:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas está limitado a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Pode abranger vários grupos de entidades, mas, ocasionalmente, pode devolver resultados desatualizados. Em geral, as consultas eventualmente consistentes são executadas mais rapidamente do que as consultas fortemente consistentes, mas não existe qualquer garantia.

Nota: as consultas globais (não antecessoras) ignoram este argumento.

deadline

Tempo máximo, em segundos, de espera para que o Datastore devolva um resultado antes de anular com um erro. Aceita um número inteiro ou um valor de vírgula flutuante. Não pode ser definido acima do valor predefinido (60 segundos), mas pode ser ajustado para baixo para garantir que uma operação específica falha rapidamente (por exemplo, para devolver uma resposta mais rápida ao utilizador, repetir a operação, experimentar uma operação diferente ou adicionar a operação a uma fila de tarefas).

Se keys consistir numa única chave (ou na respetiva representação de string), este método devolve a instância do modelo associada à chave se a chave existir no Datastore. Caso contrário, devolve None. Se keys for uma lista, o valor de retorno é uma lista correspondente de instâncias do modelo, com valores None onde não existe nenhuma entidade para uma determinada chave.

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

Model.get_by_id (ids, parent=None)

Obtém a instância (ou as instâncias) do modelo para o ID numérico (ou os IDs) especificado.

Argumentos

ids

Um ID da entidade numérico ou uma lista de IDs numéricos.

parent

A entidade principal das entidades pedidas, como um modelo ou uma chave, ou None (a predefinição) se as entidades pedidas não tiverem uma entidade principal. As várias entidades pedidas por uma chamada têm de ter todas o mesmo elemento principal.

read_policy

Leia a política que especifica o nível de consistência de dados pretendido:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas está limitado a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Pode abranger vários grupos de entidades, mas, ocasionalmente, pode devolver resultados desatualizados. Em geral, as consultas eventualmente consistentes são executadas mais rapidamente do que as consultas fortemente consistentes, mas não existe qualquer garantia.

Nota: as consultas globais (não antecessoras) ignoram este argumento.

deadline

Se ids consistir num único ID numérico, este método devolve a instância do modelo associada ao ID se o ID existir no Datastore, caso contrário, None. Se ids for uma lista, o valor de retorno é uma lista correspondente de instâncias do modelo, com valores None onde não existe nenhuma entidade para um determinado ID numérico.

Model.get_by_key_name (key_names, parent=None)

Obtém a instância (ou as instâncias) do modelo para o nome da chave (ou os nomes) fornecido.

Argumentos

key_names

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

parent

A entidade principal das entidades pedidas, como uma instância de modelo ou uma chave, ou None (a predefinição) se as entidades pedidas não tiverem uma entidade principal. As várias entidades pedidas por uma chamada têm de ter o mesmo elemento principal.

read_policy

Leia a política que especifica o nível de consistência de dados pretendido:

STRONG_CONSISTENCY: Garante os resultados mais recentes, mas está limitado a um único grupo de entidades.
EVENTUAL_CONSISTENCY: Pode abranger vários grupos de entidades, mas, ocasionalmente, pode devolver resultados desatualizados. Em geral, as consultas eventualmente consistentes são executadas mais rapidamente do que as consultas fortemente consistentes, mas não existe qualquer garantia.

Nota: as consultas globais (não antecessoras) ignoram este argumento.

deadline

Se key_names consistir num único nome de chave, este método devolve a instância do modelo associada ao nome se o nome existir no Datastore; caso contrário, devolve None. Se key_names for uma lista, o valor devolvido é uma lista correspondente de instâncias do modelo, com valores None onde não existe nenhuma entidade para um determinado nome de chave.

Model.get_or_insert (key_name, **kwds)

Tenta obter a entidade do tipo do modelo com o nome da chave fornecido. Se existir, get_or_insert() devolve-o simplesmente. Se não existir, é criada, armazenada e devolvida uma nova entidade com o tipo, o nome e os parâmetros indicados em kwds.

As operações get e subsequentes (possíveis) put são incluídas numa transação para garantir a atomicidade. Isto significa que get_or_insert() nunca substitui uma entidade existente e insere uma nova entidade se e só se não existir nenhuma entidade com o tipo e o nome indicados. Por 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 palavras-chave a transmitir ao construtor da classe do modelo se não existir uma instância com o nome da chave especificado. O argumento parent é obrigatório se a entidade pretendida tiver um elemento principal.

Nota: o comando get_or_insert() não aceita um argumento read_policy nem deadline.

O método devolve uma instância da classe do modelo que representa a entidade pedida, quer tenha existido ou tenha sido criada pelo método. Tal como acontece com todas as operações do Datastore, este método pode gerar um erro TransactionFailedError se não for possível concluir a transação.

Model.all (keys_only=False)

Devolve um objeto Query que representa todas as entidades do tipo correspondente a este modelo. Os métodos no objeto de consulta podem aplicar filtros e ordenar pedidos à consulta antes de ser executada. Consulte a página da classe Query para mais informações.

Argumentos

keys_only: Se a consulta deve devolver entidades completas ou apenas chaves. As consultas que devolvem chaves são mais rápidas e usam menos tempo da CPU do que as consultas que devolvem entidades completas.

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

Executa uma consulta GQL em instâncias deste modelo.

Argumentos

query_string: A parte da consulta GQL após SELECT * FROM model (que está implícita ao usar este método de classe).
args: Associações de parâmetros posicionais, semelhantes ao construtor GqlQuery().
kwds: Associaçõ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, que pode ser usado para aceder aos resultados.

Model.kind ()

Devolve o tipo do modelo, normalmente o nome da subclasse Model.

Model.properties ()

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

Métodos de instância

As instâncias de modelos têm os seguintes métodos:

key ()

Devolve o Datastore Key para esta instância do modelo.

A chave de uma instância do modelo inclui o tipo de entidade da instância, juntamente com um identificador único. O identificador pode ser uma string de nome da chave, atribuída explicitamente pela aplicação quando a instância é criada, ou um ID numérico inteiro,atribuído automaticamente pelo App Engine quando a instância é escrita (put) no Datastore. Chamar key() antes de ser atribuído um identificador à instância gera uma exceção NotSavedError.

put ()

Armazena a instância do modelo no Datastore. Se a instância do modelo for criada recentemente e nunca tiver sido armazenada, este método cria uma nova entidade de dados no Datastore. Caso contrário, atualiza a entidade de dados com os valores das propriedades atuais.

O método devolve a chave da entidade armazenada.

Se não for possível confirmar os dados, é gerada uma exceção TransactionFailedError.

Argumentos

deadline: Tempo máximo, em segundos, de espera para que o Datastore devolva um resultado antes de anular com um erro. Aceita um número inteiro ou um valor de vírgula flutuante. Não pode ser definido acima do valor predefinido (60 segundos), mas pode ser ajustado para baixo para garantir que uma operação específica falha rapidamente (por exemplo, para devolver uma resposta mais rápida ao utilizador, repetir a operação, experimentar uma operação diferente ou adicionar a operação a uma fila de tarefas).

delete ()

Elimina a instância do modelo do Datastore. Se a instância nunca tiver sido escrita no Datastore, a eliminação gera uma exceção NotSavedError.

Argumentos

deadline: Tempo máximo, em segundos, de espera para que o Datastore devolva um resultado antes de anular com um erro. Aceita um número inteiro ou um valor de vírgula flutuante. Não pode ser definido acima do valor predefinido (60 segundos), mas pode ser ajustado para baixo para garantir que uma operação específica falha rapidamente (por exemplo, para devolver uma resposta mais rápida ao utilizador, repetir a operação, experimentar uma operação diferente ou adicionar a operação a uma fila de tarefas).

is_saved ()

Devolve True se a instância do modelo tiver sido escrita (put) no Datastore, pelo menos, uma vez.

Este método verifica apenas se a instância foi escrita no Datastore, pelo menos, uma vez desde que foi criada. Não verifica se as propriedades da instância foram atualizadas desde a última vez que foram escritas.

dynamic_properties ()

Devolve uma lista dos nomes de todas as propriedades dinâmicas definidas para esta instância do modelo. Isto aplica-se apenas a instâncias de classes Expando. Para instâncias do modelo não expansível, esta função devolve uma lista vazia.

parent ()

Devolve uma instância de modelo para a entidade principal desta instância ou None se esta instância não tiver uma entidade principal.

parent_key ()

Devolve o Key da entidade principal desta instância ou None se esta instância não tiver uma principal.

to_xml ()

Devolve uma representação XML da instância do modelo.

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

Nomes de propriedades não permitidos

O Datastore e a respetiva API impõem várias restrições aos nomes das propriedades das entidades e dos atributos das instâncias dos modelos.

O Datastore reserva todos os nomes de propriedades que começam e terminam com dois carateres de sublinhado (__*__). Uma entidade do Datastore não pode ter uma propriedade com esse nome.

A API Python Model ignora todos os atributos numa classe Model ou Expando que começam com um sublinhado (_). A sua aplicação pode usar estes atributos para associar dados aos objetos do modelo que não são guardados no Datastore.

Por último, a API do modelo Python usa atributos de objetos para definir propriedades de um modelo e, por predefinição, as propriedades da entidade Datastore têm o nome dos atributos. Uma vez que a classe Model tem várias propriedades e métodos para outros fins, esses atributos não podem ser usados para propriedades na API Python. Por exemplo, um modelo não pode ter uma propriedade acedida com o atributo key.

No entanto, uma propriedade pode especificar um nome diferente para o Datastore do que o nome do atributo, fornecendo um argumento name ao construtor da propriedade. Isto 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 seguintes nomes de atributos estão reservados pela classe Model na API 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

A classe Model Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Introdução

Construtor

Métodos de classe

Métodos de instância

Nomes de propriedades não permitidos

A classe Model