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 comkey_name
ouparent
. Caso sejaNone
, ela recua sobre o comportamento dekey_name
eparent
. É útil quando você usaallocate_ids()
para reservar códigos numéricos para novas entidades.Para o valor de
key
, use uma instânciaKey
.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
. Quandokeys
é uma lista, o valor de retorno é uma lista correspondente de instâncias do modelo com valoresNone
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
- 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.
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
. Casoids
seja uma lista, o valor retornado será uma lista correspondente de instâncias do modelo com valoresNone
, 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
- 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
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
. Casokey_names
seja uma lista, o valor retornado será uma lista correspondente de instâncias do modelo com valoresNone
, 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 emkwds
é 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 argumentoread_policy
oudeadline
.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 classeQuery
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çãoNotSavedError
. - 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 ouNone
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:
|
|