Módulo google.appengine.ext.ndb.model

Resumo

Classes Model e Property, além de material associado.

Uma classe de modelo representa a estrutura de entidades armazenadas no Datastore. Os aplicativos definem classes de modelo para indicar a estrutura das entidades deles e instanciam essas classes de modelo para criar entidades.

Todas as classes de modelo precisam herdar (direta ou indiretamente) de Model. Com as metaclasses, as atribuições diretas na definição da classe de modelo podem ser usadas para declarar a estrutura do modelo:

class Person(Model):
  name = StringProperty()
  age = IntegerProperty()

Já podemos criar uma entidade Person e gravá-la no Cloud Datastore:

p = Person(name='Arthur Dent', age=42)
k = p.put()

O valor de retorno de put() é uma chave (consulte a documentação de ndb/key.py) que poderá ser usada para recuperar a mesma entidade depois:

p2 = k.get()
p2 == p  # Returns True

Para atualizar uma entidade, basta alterar os atributos dela e gravá-la novamente. Observe que isso não altera a chave:

p2.name = 'Arthur Philip Dent'
p2.put()

Também podemos excluir uma entidade usando a chave:

k.delete()

As definições de propriedade no corpo da classe informam ao sistema os nomes e os tipos dos campos a serem armazenados no Cloud Datastore, se precisam ser indexados, o valor padrão deles e muito mais.

Há muitos tipos de Property diferentes. A maioria é indexada por padrão. As exceções aparecem na lista abaixo:

• StringProperty: uma string curta, limitada a 500 bytes.

• TextProperty: uma string ilimitada. Não é indexada.

• BlobProperty: uma string ilimitada. Não é indexada.

• IntegerProperty: um número inteiro assinado de 64 bits.

• FloatProperty: um número de ponto flutuante de precisão dupla.

• BooleanProperty: um valor booleano.

• DateTimeProperty: um objeto de data e hora. Observação: o App Engine sempre usa o UTC como fuso horário.

• DateProperty: um objeto de data.

• TimeProperty: um objeto de tempo.

• GeoPtProperty: uma localização geográfica, ou seja: latitude, longitude.

• KeyProperty: um valor de chave do Cloud Datastore, opcionalmente restrito a se referir a um tipo específico.

• UserProperty: um objeto User (somente para compatibilidade com versões anteriores).

• StructuredProperty: um campo que é estruturado como uma entidade. Veja mais detalhes abaixo.

• LocalStructuredProperty: semelhante a StructuredProperty, mas a representação em disco é um blob opaco. Não é indexada.

• ComputedProperty: uma propriedade com valor calculado de outras propriedades por uma função definida pelo usuário. O valor da propriedade é gravado no Cloud Datastore para que possa ser usado em consultas, mas o valor do Cloud Datastore não é usado quando a entidade é lida de volta.

• GenericProperty: uma propriedade com tipo não restrito, usada principalmente pela classe Expando (veja abaixo), mas também utilizável explicitamente.

• JsonProperty: uma propriedade em que o valor é qualquer objeto que possa ser serializado usando JSON. O valor gravado no Cloud Datastore é uma representação JSON desse objeto.

• PickleProperty: uma propriedade em que o valor é qualquer objeto que pode ser serializado usando o protocolo pickle do Python. O valor gravado no Cloud Datastore é a representação serializada desse objeto, usando o protocolo de pickle mais alto disponível.

A maioria das classes Property tem assinaturas de construtor semelhantes. Elas aceitam vários argumentos de palavras-chave opcionais:

• name=<string>: nome usado para armazenar o valor da propriedade no Datastore. Diferentemente das opções a seguir, ele também pode ser fornecido como um argumento posicional.

• indexed=<bool>: indica se a propriedade será indexada, permitindo consultas no valor desta propriedade

• repeated=<bool>: indica que essa propriedade pode ter vários valores na mesma entidade.

• write_empty_list<bool>: para propriedades de valor repetidos, controla se propriedades sem elementos (a lista vazia) são gravadas no Datastore. Se verdadeiro, são gravadas. Se for falso, nada será gravado no Datastore.

• required=<bool>: indica que esta propriedade precisa receber um valor.

• default=<value>: um valor padrão, se nenhum valor explícito for fornecido.

• choices=<list of values>: uma lista ou tupla de valores permitidos.

• validator=<function>: uma função de validação geral. Ela será chamada com dois argumentos (prop, valor) e retornará o valor validado ou gerará uma exceção. A função também pode modificar o valor, mas chamá-lo novamente no valor modificado não modifica o valor adicional. Por exemplo: um validador que retorna value.strip() ou value.lower() é bom, mas um que retorne valor + '$' não é.

• verbose_name = <value>: um nome legível para esta propriedade. Esse nome legível pode ser usado para marcadores de formulário html.

As opções repetidas e requeridas/padrão são mutuamente exclusivas: uma propriedade repetida não pode ser requerida nem pode especificar um valor padrão (o padrão é sempre uma lista vazia e uma lista vazia é sempre um valor permitido), mas uma propriedade requerida pode ter um padrão.

Alguns tipos de propriedade têm mais argumentos. Alguns tipos de propriedade não aceitam todas as opções.

As propriedades repetidas são sempre representadas como listas do Python. Se houver apenas um valor, a lista terá apenas um elemento. Quando uma nova lista é atribuída a uma propriedade repetida, todos os elementos da lista são validados. Como também é possível alterar listas em uso, as propriedades repetidas são avaliadas novamente antes de serem gravadas no Datastore.

Nenhuma validação acontece quando uma entidade é lida no Cloud Datastore. No entanto, valores de propriedades lidos que têm o tipo errado (por exemplo, um valor de string para um IntegerProperty) são ignorados.

Para propriedades não repetidas, None é sempre um valor possível. Nenhuma validação é chamada quando o valor é definido como None. No entanto, para propriedades requeridas, a gravação da entidade no Cloud Datastore exige que o valor seja diferente de None (e válido).

O StructuredProperty é diferente da maioria das outras propriedades. Ele permite que você defina uma subestrutura para suas entidades. A subestrutura em si é definida usando uma classe de modelo. O valor do atributo é uma instância dessa classe de modelo. No entanto, ele não é armazenado no Datastore como uma entidade separada. Em vez disso, seus valores de atributo são incluídos na entidade pai usando uma convenção de nomenclatura (o nome do atributo estruturado seguido por um ponto seguido pelo nome do subatributo). Exemplo:

class Address(Model):
  street = StringProperty()
  city = StringProperty()

class Person(Model):
  name = StringProperty()
  address = StructuredProperty(Address)

p = Person(name='Harry Potter',
           address=Address(street='4 Privet Drive',
                           city='Little Whinging'))
k.put()

Com isso, seria gravada uma única entidade "Person" com três atributos, como você pode verificar usando o Visualizador do Datastore no Admin Console:

name = 'Harry Potter'
address.street = '4 Privet Drive'
address.city = 'Little Whinging'

Os tipos de propriedade estruturados podem ser aninhados arbitrariamente em profundidade, mas em uma hierarquia de tipos de propriedade estruturada aninhada, apenas um nível pode ter a sinalização de repetição definida. É bom ter várias propriedades estruturadas referenciando a mesma classe de modelo.

Também é bom usar a mesma classe de modelo tanto como uma classe de entidade de nível superior quanto para uma propriedade estruturada. No entanto, as consultas para a classe de modelo retornarão apenas as entidades de nível superior.

O LocalStructuredProperty funciona de maneira semelhante ao StructuredProperty no Python. Exemplo:

class Address(Model):
  street = StringProperty()
  city = StringProperty()

class Person(Model):
  name = StringProperty()
  address = LocalStructuredProperty(Address)

p = Person(name='Harry Potter',
           address=Address(street='4 Privet Drive',
                           city='Little Whinging'))
k.put()

No entanto, os dados gravados no Cloud Datastore são diferentes. Ele grava uma entidade "Person" com um atributo "name" como antes e um atributo 'address' único em que o valor é um blob que codifica o valor "Address" usando a codificação padrão de buffer de protocolo.

Às vezes, o conjunto de propriedades não é conhecido antes do tempo. Nesses casos, você pode usar a classe Expando. Essa é uma subclasse de modelo que cria propriedades dinamicamente, tanto na atribuição quanto ao carregar uma entidade do Cloud Datastore. Exemplo:

class SuperPerson(Expando):
  name = StringProperty()
  superpower = StringProperty()

razorgirl = SuperPerson(name='Molly Millions',
                        superpower='bionic eyes, razorblade hands',
                        rasta_name='Steppin' Razor',
                        alt_name='Sally Shears')
elastigirl = SuperPerson(name='Helen Parr',
                         superpower='stretchable body')
elastigirl.max_stretch = 30  # Meters

Você pode inspecionar as propriedades de uma instância expando usando o atributo _properties:

>>> print razorgirl._properties.keys() ['rasta_name', 'name', 'superpower', 'alt_name'] >>> print elastigirl._properties {'max_stretch': GenericProperty('max_stretch'), 'name': StringProperty('name'), 'superpower': StringProperty('superpower')}

Observação: esta propriedade existe também para instâncias simples de Model, mas não é tão interessante para elas.

A classe Model oferece suporte básico a consultas. É possível criar um objeto Query chamando o método de classe query(). A iteração de um objeto Query retorna as entidades correspondentes à consulta, uma de cada vez.

Os objetos Query são totalmente descritos na docstring de query.py, mas há um atalho acessível que só está disponível por meio de Model.query(): argumentos posicionais são interpretados como expressões de filtro que são combinadas por meio de um operador AND. Exemplo:

Person.query(Person.name == 'Harry Potter', Person.age >= 11)

é equivalente a:

Person.query().filter(Person.name == 'Harry Potter', Person.age >= 11)

Os argumentos de palavra-chave são transmitidos para .query() junto com o construtor Query().

É possível consultar os valores de campo das propriedades estruturadas. Por exemplo:

qry = Person.query(Person.address.city == 'London')

Várias funções de nível superior também residem neste módulo:

• transaction() executa uma função dentro de uma transação.

• get_multi() lê várias entidades de uma só vez.

• put_multi() grava várias entidades de uma só vez.

• delete_multi() exclui várias entidades de uma só vez.

Todas elas também têm uma variante * async() correspondente. As funções * _multi_async() retornam uma lista de futuros.

Por último, estes (sem variantes assíncronas):

• in_transaction() testa se você está executando atualmente em uma transação.

• @transactional decora funções que serão executadas em uma transação.

Há muitos outros recursos interessantes. Por exemplo, as subclasses Model podem definir hooks pré e pós-chamada para a maioria das operações (get, put, delete, allocate_ids) e as classes Property podem ser subclassificadas para atender a várias necessidades. A documentação para gravar uma subclasse Property está na docstring da classe Property.

Índice

Classe google.appengine.ext.ndb.model.KeyFonte

Bases: object

Uma chave de armazenamento de dados imutável.

Para flexibilidade e praticidade, várias assinaturas de construtor são aceitas.

A maneira principal de criar uma chave é usar argumentos posicionais: - Key(kind1, id1, kind2, id2, …).

Esta é uma maneira abreviada para qualquer uma destas duas formas mais longas: - Key(pairs=[(kind1, id1), (kind2, id2), …]) - Key(flat=[kind1, id1, kind2, id2, …])

Qualquer uma das formas de construtor acima pode transmitir outra chave usando parent=<key>. Os pares (kind, id) da chave pai são inseridos antes dos pares (kind, id) serem transmitidos explicitamente.

Você também pode criar uma chave com base em uma string codificada "segura para URL": - Key(urlsafe=<string>)

Para fins internos, existem os seguintes construtores: - Key(reference=<reference>): passa um objeto Reference de nível inferior. - Key(serialized=<string>): passa um Reference de nível inferior serializado. - Key(<dict>): para liberação, o mesmo de Key(**<dict>).

A string "url-safe" é realmente um Reference serializado codificado em base64 seguro para Web, mas é melhor pensar nela apenas como uma string exclusiva opaca.

Outros argumentos de palavra-chave do construtor: - app=<string>: especifique o ID do aplicativo. - namespace=<string>: especifique o namespace.

Se um Reference for passado (usando um de referência, serializado ou seguro para URL), os argumentos e as palavras-chave de namespace precisarão corresponder ao que já está presente no Reference (depois da decodificação, se necessário). A palavra-chave pai não pode ser combinada com um Reference de maneira alguma.

As chaves são imutáveis, o que significa que um objeto Key não poderá ser modificado depois de ter sido criado. Isso é aplicado pela implementação, assim como o Python permite.

Para acessar o conteúdo de uma chave, os seguintes métodos e operações são aceitos:

• repr(key), str(key): retornam uma representação de string semelhante à forma de construtor mais curta, omitindo o app e o namespace, a menos que eles sejam diferentes do valor padrão.

• key1 == key2, key1 != key2 – comparação de igualidade entre chaves.

• hash(key): um valor de hash suficiente para armazenar Keys em um dict.

• key.pairs(): uma tupla de pares (kind, id).

• key.flat(): uma tupla de valores kind e id simples, ou seja (kind1, id1, kind2, id2…).

• key.app(): o ID do aplicativo.

• key.id(): o código da string ou do inteiro no último par (kind, id) ou None, caso a chave esteja incompleta.

• key.string_id(): o código da string no último par (kind, id) ou None, caso a chave tenha um código do inteiro ou esteja incompleta.

• key.integer_id(): o código do inteiro no último par (kind, id) ou None, caso a chave tenha um código da string ou esteja incompleta.

• key.namespace(): o namespace.

• key.kind(): um atalho para key.pairs()[-1][0].

• key.parent(): um Key criado com base em todos, menos os últimos pares (kind, id).

• key.urlsafe(): um Reference serializado codificado em base64 seguro para Web.

• key.serialized(): um Reference serializado.

• key.reference(): um objeto Reference. O autor da chamada promete não mudá-lo.

As chaves também são compatíveis com a interação com o armazenamento de dados. Esses métodos são os únicos que interagem em qualquer tipo de atividade de E/S. Para objetos Future, consulte o documento de ndb/tasklets.py.

• key.get(): retorne a entidade de Key.

• key.get_async(): retorne um Future com o resultado eventual que será a entidade de Key.

• key.delete(): exclua a entidade de Key.

• key.delete_async(): exclua de maneira assíncrona a entidade de Key.

As chaves podem ser serializadas.

É melhor evitar Key subclasse. Seria difícil acertá-lo.

app()Fonte

Retorne o ID do aplicativo.

delete(**ctx_options)Fonte

Exclua de maneira síncrona a entidade para essa Key.

Trata-se de um ambiente autônomo caso não haja uma entidade assim.

delete_async(**ctx_options)Fonte

Programe a exclusão da entidade para essa Key.

Isso retorna um Future com um resultado disponibilizado assim que a exclusão é concluída. Se essa entidade não existir, um Future continuará sendo retornado. Em todos os casos, o resultado de Future é None (ou seja, não há como saber se a entidade existiu ou não).

flat()Fonte

Retorne uma tupla de valores kind e id alternados.

classmethod from_old_key(old_key)Fonte

get(**ctx_options)Fonte

Consiga de maneira síncrona a entidade dessa Key.

Retorne None, caso não haja essa entidade.

get_async(**ctx_options)Fonte

Retorne um Future com um resultado que seja a entidade de Key.

Se essa entidade não existir, um Future continuará sendo retornado, e o resultado de retorno eventual Future será None.

id()Fonte

Retorne o código de string ou inteiro no último par (kind, id), caso haja.

Retorna

Um código de string ou inteiro ou None, caso a chave esteja incompleta.

integer_id()Fonte

Retorne o código do inteiro no último par (kind, id), caso haja.

Retorna

Um código de inteiro ou None, caso a chave tenha um código de string ou esteja incompleta.

kind()Fonte

Retorne o tipo da entidade referenciada.

Este é o tipo do último par (kind, id).

namespace()Fonte

Retorne o namespace.

pairs()Fonte

Retorne uma tupla de pares (kind, id).

parent()Fonte

Retorne um Key criado com base em todos, menos os últimos pares (kind, id).

Se houver apenas um par (kind, id), retorne None.

reference()Fonte

Retorne o objeto Reference deste Key.

Esta é uma instância entity_pb.Reference, uma classe de buffer de protocolo usada pela API de nível inferior para o armazenamento de dados.

OBSERVAÇÃO: o autor da chamada não precisa modificar o valor de retorno.

root()Fonte

Retorne a chave raiz. Trata-se do próprio pai ou superior.

serialized()Fonte

Retorne o objeto Reference serializado deste Key.

string_id()Fonte

Retorne o código da string no último par (kind, id), caso haja.

Retorna

Um código de string ou None, caso a chave tenha um código de inteiro ou esteja incompleta.

to_old_key()Fonte

urlsafe()Fonte

Retorne uma codificação de string segura para URL que codifica Reference de Key.

Essa string é compatível com outras APIs e linguagens e com as strings usadas para representar Keys no GQL e no Admin Console do App Engine.

Classe google.appengine.ext.ndb.model.BlobKey(blob_key)Fonte

Bases: object

Chave usada para identificar um blob no Blobstore.

Esse objeto encapsula uma string usada internamente pela Blobstore API para identificar blobs de aplicativo. O BlobKey corresponde ao nome da entidade BlobReference subjacente.

Essa classe é exposta na API em google.appengine.ext.db e google.appengine.ext.blobstore.

ToXml()source

Classe google.appengine.ext.ndb.model.GeoPt(lat, lon=None)Fonte

Bases: object

Um ponto geográfico, especificado por coordenadas de latitude e longitude de ponto flutuante. Muitas vezes é usada para integrar com sites de mapas como o Google Maps. Ele também pode ser usado como coordenadas ICBM.

Trata-se do elemento georss:point. Na saída XML, as coordenadas são fornecidas como os atributos lat e lon. Consulte: http://georss.org/

Serializa para '<lat>,<lon>'. Gera BadValueError caso transmita uma string serializada inválida ou se lat e lon não forem pontos flutuantes válidos nos intervalos [-90, 90] e [-180, 180], respectivamente.

ToXml()source

lat = None

lon = None

Exceçãogoogle.appengine.ext.ndb.model.RollbackFonte

Bases: google.appengine.api.datastore_errors.Error

Pode ser gerado por funções de transação quando elas querem fazer rollback, em vez de confirmar. Qualquer exceção gerada por uma função de transação causará um rollback. Isso é essencialmente para fins de praticidade. Consulte Datastore.RunInTransaction para ver detalhes.

Classe google.appengine.ext.ndb.model.IndexFonte

Bases: google.appengine.ext.ndb.model._NotEqualMixin

Objeto imutável que representa um índice.

ancestor

Se este é um índice ancestral, um bool.

kind

O tipo indexado, uma string.

properties

Uma lista de objetos PropertyIndex que fornece as propriedades indexadas.

Classe google.appengine.ext.ndb.model.IndexStateFonte

Bases: google.appengine.ext.ndb.model._NotEqualMixin

Objeto imutável que representa o índice e o estado dele.

definition

Um objeto Index que descreve o índice.

id

O código do índice, um inteiro.

state

O estado do índice, uma string.

Os valores possíveis são "error", "delete", "serving" ou "building".

Classe google.appengine.ext.ndb.model.IndexPropertyFonte

Bases: google.appengine.ext.ndb.model._NotEqualMixin

Objeto imutável que representa uma única propriedade em um índice.

direction

A direção no índice dessa propriedade, "asc" ou "desc".

name

O nome da propriedade indexada, uma string.

Classe google.appengine.ext.ndb.model.ModelAdapter(default_model=None, id_resolver=None)Fonte

Bases: google.appengine.datastore.datastore_rpc.AbstractAdapter

Conversões entre classes Key e Model "our" e protobufs.

Ele é necessário para criar um objeto Connection, que, por sua vez, é necessário para criar um objeto Context.

Consulte a docstring da classe base para mais informações sobre as assinaturas.

entity_to_pb(ent)Fonte

key_to_pb(key)Fonte

pb_to_entity(pb)Fonte

pb_to_index(pb)Fonte

pb_to_key(pb)Fonte

Classe google.appengine.ext.ndb.model.ModelAttributeFonte

Bases: object

Uma classe Base que significa a presença de um método _fix_up().

Classe google.appengine.ext.ndb.model.ModelKeyFonte

Bases: google.appengine.ext.ndb.model.Property

Propriedade especial para armazenar a chave Model.

Classe google.appengine.ext.ndb.model.MetaModel(name, bases, classdict)Fonte

Bases: type

Metaclasse de Model.

Ele existe para corrigir as propriedades. Elas precisam saber o nome delas. Isso é feito chamando-se o método _fix_properties() da classe.

Classe google.appengine.ext.ndb.model.Model(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model._NotEqualMixin

Uma classe que descreve as entidades do Cloud Datastore.

As instâncias de Model costumam ser chamadas de entidades. Todas as classes de modelo herdadas de Model automaticamente têm MetaModel como a metaclasse dele. Dessa maneira, as propriedades são corrigidas devidamente após a classe, uma vez definida a classe.

Por causa disso, não é possível usar o mesmo objeto Property para descrever várias propriedades - você precisa criar objetos Property separados para cada propriedade. Por exemplo, isto não funciona:

wrong_prop = StringProperty()
class Wrong(Model):
  wrong1 = wrong_prop
  wrong2 = wrong_prop

O tipo normalmente é igual ao nome da classe (exclusivo do nome do módulo ou qualquer outro escopo pai). Para modificar o tipo, defina um método de classe chamado _get_kind(), da seguinte maneira:

class MyModel(Model):
  @classmethod
  def _get_kind(cls):
    return 'AnotherKind'

classmethod allocate_ids(size=None, max=None, parent=None, **ctx_options)Fonte

Aloca um intervalo de códigos de chave para esta classe de modelo.

Parâmetros

• size: número de códigos a serem alocados. É possível especificar size ou max, mas não ambos.

• max: código máximo a ser alocado. É possível especificar size ou max, mas não ambos.

• parent: chave pai onde os códigos serão alocados.

• **ctx_options: opções de contexto.

Retorna

Uma tupla com (start, end) para o intervalo alocado, inclusive.

classmethod allocate_ids_async(size=None, max=None, parent=None, **ctx_options)Fonte

Aloca um intervalo de códigos de chave para esta classe de modelo.

Trata-se da versão assíncrona de Model._allocate_ids().

classmethod get_by_id(*args, **kwds)source

Retorna uma instância da classe Model por código.

Na verdade, trata-se apenas de uma forma abreviada de Key(cls, id, …).get().

Parâmetros

• id: o código de uma string ou chave de inteiro

• parent: chave pai opcional do modelo a ser conseguido

• namespace: namespace opcional

• app: código do app opcional

• **ctx_options: opções de contexto

Retorna

Uma instância de modelo ou None, caso não encontrada.

classmethod get_by_id_async(*args, **kwds)Fonte

Retorna uma instância da classe Model por código (e app, namespace).

Trata-se da versão assíncrona de Model._get_by_id().

classmethod get_or_insert(*args, **kwds)Fonte

Recupera de maneira transacional uma entidade existente ou cria uma nova.

Argumentos posicionais:

name: nome da chave a ser recuperado ou criado.

Argumentos de palavra-chave

• namespace: namespace opcional

• app: código do app opcional.

• parent: chave da entidade pai, caso haja alguma.

• context_options: objeto ContextOptions (não argumentos de palavra-chave) ou "None".

• **kwds: argumentos de palavra-chave a serem passados para o construtor da classe de modelo, caso uma instância do nome da chave especificada ainda não exista. Se uma instância com key_name e parent fornecidos já existir, esses argumentos serão descartados.

Retorna

Instância existente da classe Model com o nome da chave especificada e pai ou um novo recém-criado.

classmethod get_or_insert_async(*args, **kwds)Fonte

Recupera de maneira transacional uma entidade existente ou cria uma nova.

Trata-se da versão assíncrona de Model._get_or_insert().

classmethod gql(query_string, *args, **kwds)Fonte

Execute uma consulta GQL.

has_complete_key()Fonte

Retorne se esta entidade tem uma chave concluída.

key

Propriedade especial para armazenar a chave Model.

populate(**kwds)Fonte

Preencha uma instância de argumentos de palavra-chave.

Cada argumento de palavra-chave será usado para definir uma propriedade correspondente. As palavras-chave precisam se referir ao nome da propriedade válido. Isso é semelhante a passar argumentos de palavra-chave para o construtor Model, exceto pelo fato de nenhuma provisão para key, id ou parent ser feita.

put(**ctx_options)Fonte

Grave essa entidade no Cloud Datastore.

Se a operação criar ou concluir uma chave, o atributo key da entidade será definido como a chave nova e completa.

Retorna

A chave da entidade. Ela é sempre uma chave concluída.

put_async(**ctx_options)Fonte

Grave essa entidade no Cloud Datastore.

Trata-se da versão assíncrona de Model._put().

classmethod query(*args, **kwds)Fonte

Crie um objeto Query para essa classe.

Parâmetros

• distinct: bool opcional, forma abreviada de group_by = projection.

• *args: usado para aplicar um filtro inicial.

• **kwds: são passados para o construtor Query().

Retorna

Um objeto Query.

to_dict(*args, **kwds)Fonte

Retorna um dict que contém os valores de propriedade da entidade.

Parâmetros

• include: conjunto opcional de nomes de propriedade a serem incluídos. Por padrão, inclui todos.

• exclude: conjunto opcional de nomes de propriedade a serem pulados. Por padrão, não pula nenhum. Um nome contido em include e exclude é excluído.

Classe google.appengine.ext.ndb.model.Expando(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Model

Subclasse de modelo para dar suporte a nomes e tipos Property dinâmicos.

Consulte o docstring do módulo para detalhes.

google.appengine.ext.ndb.model.transaction(*args, **kwds)Fonte

Execute um retorno de chamada em uma transação.

Parâmetros

• callback: uma função ou uma tasklet a ser chamada

• **ctx_options: opções de transação

Entre as opções úteis estão:

retries=N: repetir até N vezes (ou seja, tentar até N+1 vezes) propagation=<flag>: determina como uma transação existente precisa ser

propagados, em que <flag> pode ser um dos seguintes: TransactionOptions.NESTED: inicia uma transação aninhada (é o

padrão, mas transações aninhadas reais ainda não estão implantadas. Dessa maneira, você só pode usá-la fora de uma transação existente).

TransactionOptions MANDATORY: uma transação já precisa estar em andamento. TransactionOptions ALLOWED: caso uma transação esteja em andamento, vincule a ela. TransactionOptions INDEPENDENT: inicie sempre uma nova transação em paralelo.

xg=True: no Armazenamento de dados de alta replicação, ative transações entre

grupos, ou seja, permita a gravação de até cinco grupos de entidades.

read_only=True: indica que uma transação não fará gravações, o que

potencialmente possibilita mais capacidade.

AVISO: usar algo diferente de NESTED na sinalização de propagação pode ter consequências estranhas. Durante o uso de ALLOWED ou MANDATORY, caso uma exceção seja gerada, a transação possivelmente não será segura para commit. Durante o uso de INDEPENDENT, não costuma ser seguro retornar valores lidos para o autor da chamada (como foram lidos na transação do autor da chamada).

Retorna

O que callback() retorna.

Gera

• O que callback() gera. Datastore_errors.TransactionFailedError

• Caso haja falha na transação.

Observação:

Para passar argumentos para uma função de retorno de chamada, use um lambda. Por exemplo,

def my_callback(key, inc):

…

transaction(lambda: my_callback(Key(…), 1))

google.appengine.ext.ndb.transaction_async(*args, **kwds)Fonte

Execute um retorno de chamada em uma transação.

Trata-se da versão assíncrona de transaction().

google.appengine.ext.ndb.model.in_transaction()Fonte

Retorne se uma transação está ativa no momento.

google.appengine.ext.ndb.model.transactional(_func=None, **options)Fonte

google.appengine.ext.ndb.model.transactional_async(_func=None, **options)Fonte

google.appengine.ext.ndb.model.transactional_tasklet(_func=None, **options)Fonte

google.appengine.ext.ndb.model.non_transactional(_func=None, **options)Fonte

google.appengine.ext.ndb.model.get_multi(keys, **ctx_options)Fonte

Busca uma sequência de chaves.

Parâmetros

• keys: uma sequência de chaves

• **ctx_options: opções de contexto

Retorna

Uma lista com itens que são uma instância de Model ou None, caso a chave não tenha sido encontrada.

google.appengine.ext.ndb.model.get_multi_async(keys, **ctx_options)Fonte

Busca uma sequência de chaves.

Parâmetros

• keys: uma sequência de chaves

• **ctx_options: opções de contexto

Retorna

Uma lista de Futures.

google.appengine.ext.ndb.model.put_multi(entities, **ctx_options)Fonte

Armazena uma sequência de instâncias de Model.

Parâmetros

• entities: uma sequência de instâncias de Model

• **ctx_options: opções de contexto

Retorna

Uma lista com as chaves armazenadas.

google.appengine.ext.ndb.model.put_multi_async(entities, **ctx_options)Fonte

Armazena uma sequência de instâncias de Model.

Parâmetros

• entities: uma sequência de instâncias de Model

• **ctx_options: opções de contexto

Retorna

Uma lista de Futures.

google.appengine.ext.ndb.model.delete_multi(keys, **ctx_options)Fonte

Exclui uma sequência de chaves.

Parâmetros

• keys: uma sequência de chaves

• **ctx_options: opções de contexto

Retorna

Uma lista com itens que são todos None, um por chave excluída.

google.appengine.ext.ndb.model.delete_multi_async(keys, **ctx_options)Fonte

Exclui uma sequência de chaves.

Parâmetros

• keys: uma sequência de chaves

• **ctx_options: opções de contexto

Retorna

Uma lista de Futures.

google.appengine.ext.ndb.model.get_indexes(**ctx_options)Fonte

Receba uma estrutura de dados que representa os índices configurados.

Parâmetros

**ctx_options: opções de contexto

Retorna

Uma lista de objetos Index.

google.appengine.ext.ndb.model.get_indexes_async(**ctx_options)Fonte

Receba uma estrutura de dados que representa os índices configurados.

Parâmetros

**ctx_options: opções de contexto

Retorna

Um Future.

google.appengine.ext.ndb.model.make_connection(config=None, default_model=None, _api_version=u'datastore_v3', _id_resolver=None)Fonte

Crie um novo objeto Connection com o adaptador correto.

Opcionalmente, você pode passar um objeto datastore_rpc.Configuration.

Classe google.appengine.ext.ndb.model.BlobProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Property

Uma propriedade com valor que é uma string de bytes. Ela pode ser compactada.

Classe google.appengine.ext.ndb.model.JsonProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.BlobProperty

Uma propriedade com o valor que é um objeto Python codificável em Json.

Classe google.appengine.ext.ndb.model.StringProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.TextProperty

Uma propriedade indexada com o valor que é uma string de texto de comprimento limitado.

Classe google.appengine.ext.ndb.model.FloatProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Property

Uma propriedade com o valor que é um flutuante Python.

Observação: int, long e bool também são permitidos.

google.appengine.ext.ndb.model.BadProjectionError

alias de InvalidPropertyError

Classe google.appengine.ext.ndb.model.LocalStructuredProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model._StructuredGetForDictMixin, google.appengine.ext.ndb.model.BlobProperty

Subestrutura serializada para um blob opaco.

Ela é parecida com StructuredProperty no Python, mas é escrita como uma BlobProperty em Cloud Datastore. Ela não é indexada e não é possível consultar subpropriedades. Por outro lado, a representação em disco é mais eficiente e pode melhorar ainda mais passando-se compressed=True, que compacta os dados blob que usam gzip.

Classe google.appengine.ext.ndb.model.TimeProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.DateTimeProperty

Uma propriedade com o valor que é um objeto de tempo.

Classe google.appengine.ext.ndb.model.UserProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Property

Uma propriedade com o valor que é um objeto User.

Observação: ela existe para compatibilidade com versões anteriores apenas com esquemas do Cloud Datastore existentes. Não recomendamos armazenar objetos User diretamente no Cloud Datastore, mas recomendamos armazenar o valor user.user_id().

Exceçãogoogle.appengine.ext.ndb.model.InvalidPropertyErrorFonte

Bases: google.appengine.api.datastore_errors.Error

Gerado quando uma propriedade não é aplicável a um determinado uso.

Por exemplo, uma propriedade precisa existir e ser indexada para ser usada na projeção ou no grupo por cláusula da consulta.

Exceçãogoogle.appengine.ext.ndb.model.KindErrorFonte

Bases: google.appengine.api.datastore_errors.BadValueError

Gerado quando uma implementação para um tipo não pode ser encontrada.

Também gerado quando Kind não é uma string de oito bits.

Classe google.appengine.ext.ndb.model.ComputedProperty(func, name=None, indexed=None, repeated=None, verbose_name=None)Fonte

Bases: google.appengine.ext.ndb.model.GenericProperty

Uma propriedade com o valor que é determinado por uma função fornecida pelo usuário.

As propriedades computadas não podem ser definidas diretamente, mas são geradas por uma função quando obrigatório. Elas são úteis para fornecer campos no Cloud Datastore que podem ser usados para filtrar ou classificar sem precisar definir manualmente o valor no código. Por exemplo, classificar o comprimento de um BlobProperty ou usar um filtro de igualdade para verificar se outro campo não está vazio.

ComputedProperty pode ser declarado como uma propriedade regular, passando uma função como o primeiro argumento, ou pode ser usado como um decorador para a função que faz o cálculo.

Exemplo:

>>> class DatastoreFile(Model): ... name = StringProperty() ... name_lower = ComputedProperty(lambda self: self.name.lower()) ... ... data = BlobProperty() ... ... @ComputedProperty ... def size(self): ... return len(self.data) ... ... def _compute_hash(self): ... return hashlib.sha1(self.data).hexdigest() ... hash = ComputedProperty(_compute_hash, name='sha1')

Classe google.appengine.ext.ndb.model.KeyProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Property

Uma propriedade com o valor que é um objeto Key.

Argumento de palavra-chave opcional: kind=<kind>, para exigir que chaves atribuídas a essa propriedade sempre tenham o tipo indicado. Pode ser uma string ou uma subclasse Model.

Classe google.appengine.ext.ndb.model.BooleanProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Property

Uma propriedade com o valor que é um bool do Python.

Classe google.appengine.ext.ndb.model.PickleProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.BlobProperty

Uma propriedade com o valor que é um objeto Python selecionável.

Classe google.appengine.ext.ndb.model.IntegerProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Property

Uma propriedade com o valor que é um int ou long (ou bool) Python.

Classe google.appengine.ext.ndb.model.Property(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.ModelAttribute

Uma classe que descreve um atributo tipado, persistente, de uma entidade do Cloud Datastore.

Não confunda com a "property" interna do Python.

Trata-se apenas de uma classe base. Há subclasses específicas que descrevem propriedades de diversos tipos (e GenericProperty que descreve uma propriedade tipada dinamicamente).

Todos os atributos Property especiais, mesmo os considerados "public", têm nomes que começam com um sublinhado, porque StructuredProperty usa o namespace de atributo sem sublinhado para se referir a nomes Property aninhados. Isso é essencial para especificar consultas em subpropriedades (consulte o docstring do módulo).

A classe Property e as subclasses predefinidas dela permitem subclasses fáceis que usam APIs de validação e conversão para composição (ou empilhamento). Elas exigem algumas definições de terminologia:

• "user value" é um valor como seria definido e acessado pelo código de aplicativo usando atributos padrão na entidade.

• "base value" é um valor como seria serializado e desserializado no Cloud Datastore.

Os valores armazenados em ent._values[name] e acessados por _store_value() e _retrieve_value() podem ser valores de usuário ou base. Para recuperar valores de usuário, use _get_user_value(). Para recuperar valores de base, use _get_base_value(). Em particular, _get_value() calls _get_user_value(), e _serialize() effectively calls _get_base_value().

Para armazenar um valor de usuário, basta chamar _store_value(). Para armazenar um valor de base, encapsule o valor em um _BaseValue() e chame _store_value().

Uma subclasse Property que quer implementar uma transformação específica entre valores do usuário e serializáveis precisa implementar dois métodos, _to_base_type() e _from_base_type(). Eles NÃO devem chamar o método super(). As superchamadas são administradas por _call_to_base_type() e _call_from_base_type(). É isso que significa as APIs serem compostas (ou empilháveis).

A API é compatível com classes "stacking" com conversões usuário<–>base mais sofisticadas: a conversão usuário–>base vai da mais sofisticada à menos sofisticada, enquanto a conversão base–>usuário vai da menos sofisticada à mais sofisticada. Por exemplo, consulte a relação entre BlobProperty, TextProperty e StringProperty.

Além de _to_base_type() e _from_base_type(), o método _validate() também é uma API para composição.

A API de validação diferencia os valores de usuário "lax" de "strict". O conjunto de valores lax é um superconjunto do conjunto de valores rígidos. O método _validate() utiliza um valor lax e, caso necessário, converte-o em um valor rígido. Isso significa que, durante a definição do valor da propriedade, os valores lax são aceitos e, durante a especificação do valor da propriedade, somente valores rígidos serão retornados. Caso nenhuma conversão seja necessária, _validate() pode retornar None. Se o argumento estiver fora do conjunto de valores lax aceitos, _validate() provavelmente gerará uma exceção, preferencialmente TypeError ou datastore_errors.BadValueError.

Exemplo/boilerplate:

def _validate(self, value):

"Valor de usuário lax para valor de usuário strict ". se não for isinstance(value, <top type>):

aumentar TypeError(…) # Ou datastore_errors.BadValueError(…).

def _to_base_type(self, value):

"valor de usuário (Strict) para valor base." se isinstance(value, <user type>):

return <base type>(value)

def _from_base_type(self, value):

"valor base para valor de usuário (strict)." se não for isinstance(value, <base type>):

return <user type>(value)

Itens que _validate(), _to_base_type() e _from_base_type() não precisam processar:

• None: eles não serão chamados com None, e se retornarem None, isso significará que o valor não precisa de conversão.

• Valores repetidos: a infraestrutura (_get_user_value() e _get_base_value()) processa a chamada de _from_base_type() ou _to_base_type() para cada item da lista em um valor repetido.

• Encapsulamento de valores em _BaseValue(): o encapsulamento e o desencapsulamento são processados pela infraestrutura que chama as APIs para composição.

• Comparações: as operações de comparação chamam _to_base_type () no operando delas.

• Diferenciação de valores de usuário e base: a infraestrutura garante que _from_base_type() será chamado com valor base (desencapsulado) e que _to_base_type() será chamado com um valor usuário.

• Retorno do valor original: se algum deles retornar None, o valor original será mantido. Retornar um valor diferente de None substituirá o valor diferente.

IN(value)Fonte

Operador de comparação para o operador "in" de comparação.

O Python no operador "in" não pode ser sobrecarregado da maneira que queremos. Dessa forma, definimos um método. Exemplo:

Employee.query(Employee.rank.IN([4, 5, 6]))

Observe que o método é chamado ._IN(), mas normalmente pode ser invocado como .IN(). ._IN() é fornecido para o caso em que uma StructuredProperty tem um modelo com uma Property chamada IN.

Classe google.appengine.ext.ndb.model.DateProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.DateTimeProperty

Uma propriedade com o valor que é um objeto de data.

Classe google.appengine.ext.ndb.model.TextProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.BlobProperty

Uma propriedade não indexada com o valor que é uma string de texto de comprimento ilimitado.

Classe google.appengine.ext.ndb.model.DateTimeProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Property

Uma propriedade com o valor que é um objeto de data e hora.

Observação: diferentemente do Django, auto_now_add pode ser modificado definindo-se o valor antes de gravar a entidade. E, diferentemente do db clássico, auto_now não fornece um valor padrão. Além disso, diferentemente do db clássico, quando a entidade é gravada, os valores de propriedade são atualizados de acordo com o que foi gravado. Por fim, lembre-se de que isso também atualiza o valor no cache em processo e que auto_now_add pode interagir de maneira estranha com repetições de transação: uma repetição de uma propriedade com auto_now_add definido utilizará o valor que foi definido na primeira tentativa.

Classe google.appengine.ext.ndb.model.GenericProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Property

Uma propriedade com o valor que pode ser (praticamente) qualquer tipo básico.

Ela é usada principalmente em Expando e órfãos (valores presentes no Cloud Datastore, mas não representados na subclasse Model), mas também pode ser usada explicitamente para propriedades com valores tipados dinamicamente.

Ele é compatível com compressed=True, que só entra em vigor para valores str (e não unicode) e implica indexed=False.

Exceção google.appengine.ext.ndb.model.UnprojectedPropertyErrorFonte

Bases: google.appengine.api.datastore_errors.Error

Gerado durante o recebimento de um valor de propriedade que não está na projeção.

Classe google.appengine.ext.ndb.model.StructuredProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model._StructuredGetForDictMixin

Uma propriedade com o valor que é uma entidade propriamente dita.

Os valores da subentidade são indexados e podem ser consultados.

Consulte o docstring do módulo para detalhes.

IN(value)Fonte

Classe google.appengine.ext.ndb.model.GeoPtProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Property

Uma propriedade com o valor que é um GeoPt.

Exceção google.appengine.ext.ndb.model.ComputedPropertyErrorFonte

Bases: google.appengine.ext.ndb.model.ReadonlyPropertyError

Gerado durante a tentativa de definir um valor ou excluir uma propriedade computada.

Classe google.appengine.ext.ndb.model.BlobKeyProperty(*args, **kwds)Fonte

Bases: google.appengine.ext.ndb.model.Property

Uma propriedade com o valor que é um objeto BlobKey.

Exceção google.appengine.ext.ndb.model.ReadonlyPropertyErrorFonte

Bases: google.appengine.api.datastore_errors.Error

Gerado durante a tentativa de definir um valor de propriedade somente leitura.