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

Módulo google.appengine.api.datastore

Resumo

A Python Datastore API usada por desenvolvedores de apps.

Define classes Entity, Query e Iterator, bem como métodos para todas as chamadas do armazenamento de dados. Também define conversões entre as classes Python e as contrapartes PB delas.

Os erros do armazenamento de dados são definidos no módulo datastore_errors. Esse módulo só é obrigatório para evitar importações circulares. O armazenamento de dados importa datastore_types, que precisa de BadValueError. Dessa maneira, ele não pode ser definido no armazenamento de dados.

Índice

google.appengine.api.datastore.AllocateIds(model_key, size=None, **kwargs)source

Aloca um intervalo de códigos de tamanho ou com o máximo para a chave indicada.

Aloca um intervalo de códigos no armazenamento de dados. Dessa maneira, esses códigos não serão atribuídos automaticamente a novas entidades. Só é possível alocar IDs para chaves de modelo do seu aplicativo. Caso haja um erro, gera uma subclasse de datastore_errors.Error.

O tamanho ou o máximo precisa ser fornecido, mas não ambos. Se o tamanho for fornecido, um intervalo do tamanho indicado será retornado. Se o máximo for fornecido, o maior intervalo de códigos que são seguros para usar com um limite máximo será retornado (pode ser um intervalo vazio).

O máximo só precisará ser fornecido se você tiver um intervalo de códigos numéricos existente que queira reservar. Por exemplo, entidades de carregamento em massa que já tenham códigos. Se você não se importar com quais códigos recebe, use o tamanho.

Parâmetros

model_key: chave ou string a ser veiculada como um modelo que especifica a sequência em que se alocam códigos.
size: inteiro, número de códigos a serem alocados.
max: inteiro, limite máximo do intervalo de códigos a serem alocados.
config: configuração opcional a ser usada nesta solicitação.

Retorna

(start, end) do intervalo alocado, inclusive.

google.appengine.api.datastore.AllocateIdsAsync(model_key, size=None, **kwargs)source

Aloca de maneira assíncrona um intervalo de códigos.

Idêntico ao datastore.AllocationIds(), exceto por retornar um objeto assíncrono. Chame get_result() no valor de retorno a ser bloqueado na chamada e receba os resultados.

google.appengine.api.datastore.CreateConfig(**kwds)source

Crie um objeto Configuration a ser usado na configuração de chamadas do armazenamento de dados.

Essa configuração pode ser passada para a maioria das chamadas do armazenamento de dados usando o argumento "config =…".

Parâmetros

deadline: prazo opcional. O padrão é None (o que significa que o prazo padrão do sistema será usado, geralmente cinco segundos).
on_completion: função de retorno de chamada opcional. O padrão é None. Se especificado, ele será chamado com um objeto UserRPC como argumento quando um RPC for concluído.
read_policy: política de leitura opcional, definida como EVENTUAL_CONSISTENCY, para acabar ativando leituras consistentes (ou seja, leituras que passam a ser atendidas de uma versão anterior do armazenamento de dados em alguns casos). A política de leitura padrão pode precisar esperar até que as transações em andamento sejam confirmadas.
**kwds: outros argumentos de palavra-chave, desde que eles sejam compatíveis com datastore_rpc.Configuration().

Retorna

Uma instância de datastore_rpc.Configuration.

google.appengine.api.datastore.CreateRPC(service='datastore_v3', deadline=None, callback=None, read_policy=None)source

Crie uma RPC a ser usada na configuração de chamadas do armazenamento de dados.

OBSERVAÇÃO: esta função existe para compatibilidade com versões anteriores. Use CreateConfig(), em vez disso. OBSERVAÇÃO: este último usa "on_completion", uma função que utiliza um argumento, e CreateRPC usa "callback", que é uma função sem argumentos.

Parâmetros

service: string opcional. Para compatibilidade com versões anteriores, precisa ser "datastore_v3".
deadline: int ou flutuante opcional, prazo para chamadas em segundos.
callback: chamável opcional, um callback acionado quando esta RPC é concluída. Não aceita argumentos.
read_policy: política de leitura opcional, definida como EVENTUAL_CONSISTENCY, para acabar ativando leituras consistentes (ou seja, leituras que passam a ser atendidas de uma versão anterior do armazenamento de dados em alguns casos). A política de leitura padrão pode precisar esperar até que as transações em andamento sejam confirmadas.

Retorna

Uma instância de UserRPC.

google.appengine.api.datastore.CreateTransactionOptions(**kwds)source

Crie um objeto Configuration a ser usado na configuração de transações.

Essa configuração pode ser passada como o primeiro argumento de run_in_transaction_option.

Parâmetros

deadline: prazo opcional. O padrão é None (o que significa que o prazo padrão do sistema será usado, geralmente cinco segundos).
on_completion: função de retorno de chamada opcional. O padrão é None. Se especificado, ele será chamado com um objeto UserRPC como argumento quando um RPC for concluído.
xg: definido como verdadeiro para permitir transações entre grupos (somente armazenamento de dados de alta replicação).
retries: defina o número de novas tentativas de uma transação.
**kwds: outros argumentos de palavra-chave, desde que sejam compatíveis com datastore_rpc.TransactionOptions().

Retorna

Uma instância datastore_rpc.TransactionOptions.

class google.appengine.api.datastore.DatastoreAdapter(_id_resolver=None)source

Bases: google.appengine.datastore.datastore_rpc.AbstractAdapter

Adaptador entre tipos de dados definidos aqui (Entity etc.) e protobufs.

Consulte a classe base em datastore_rpc.py para mais documentos.

entity_to_pb(entity)source

index_direction_mappings = {1: 1, 2: 2}

index_state_mappings = {1: 0, 2: 1, 3: 2, 4: 3}

key_to_pb(key)source

pb_to_entity(pb)Fonte

pb_to_index(pb)Fonte

pb_to_key(pb)Fonte

google.appengine.api.datastore.Delete(keys, **kwargs)source

Exclui uma ou mais entidades do armazenamento de dados. Use com cuidado.

Exclui a(s) entidade(s) indicada(s) do armazenamento de dados. Só é possível excluir entidades do seu app. Caso haja um erro, gera uma subclasse de datastore_errors.Error.

Parâmetros

a chave primária (#):
keys: chave ou string ou lista de Keys ou strings
config: configuração opcional a ser usada nesta solicitação, precisa ser especificada como um argumento de palavra-chave.

Gera

TransactionFailedError, caso não seja possível confirmar Delete.

google.appengine.api.datastore.DeleteAsync(keys, **kwargs)source

Exclui de maneira assíncrona uma ou mais entidades do armazenamento de dados.

Idêntica a datastore.Delete(), exceto por retornar um objeto assíncrono. Chame get_result() no valor de retorno a ser bloqueado na chamada.

class google.appengine.api.datastore.Entity(kind, parent=None, _app=None, name=None, id=None, unindexed_properties=[], namespace=None, **kwds)source

Bases: dict

Uma entidade do armazenamento de dados.

Inclui acessadores somente leitura para código do app, tipo e chave primária. Também dá acesso em estilo de dicionário a propriedades.

static FromPb(pb, validate_reserved_properties=True, default_kind='')source

Método de fábrica estática. Retorna a representação de Entity do buffer de protocolo indicado (datastore_pb.Entity).

Parâmetros

pb: datastore_pb.Entity ou codificação de str de um datastore_pb.Entity
validate_reserved_properties: obsoleto
default_kind: str, o tipo a ser usado se o pb não tiver chave.

Retorna

a representação de Entity de pb

Tipo de retorno

Entidade

ToPb()source

Converte este Entity na representação do buffer de protocolo.

Retorna

entity_pb.Entity

ToXml()source

Retorna uma representação XML dessa entidade. As propriedades atom e gd:namespace são convertidas em XML, de acordo com os respectivos esquemas delas. Para mais informações, consulte:

http://www.atomenabled.org/developers/syndication/ https://developers.google.com/gdata/docs/1.0/elements

Isso não é otimizado. Ele não precisa ser usado em qualquer lugar perto do código que seja crítico para o desempenho.

app()source: Retorna o nome do aplicativo que criou essa entidade, uma string ou None, caso não esteja definido.

copy()source: O método de cópia não é compatível.

entity_group()source

Retorna o grupo de entidades dessa entidade como uma Key.

A Key retornada ficará incompleta se essa for uma entidade raiz e a chave estiver incompleta.

is_projection()source

Retorna caso essa entidade seja uma projeção da entidade completa.

Entidades projetadas: - pode não conter todas as propriedades da entidade original; - contêm apenas valores únicos para listas; - pode não conter valores com o mesmo tipo da entidade original.

is_saved()source: Retorna caso esta entidade tenha sido salva no armazenamento de dados.

key()source: Retorna a chave primária dessa entidade, uma instância de Key.

kind()source: Retorna o tipo da entidade, uma string.

namespace()source: Retorna o namespace dessa entidade, uma string ou None.

parent()source: Retorna o pai dessa entidade, como uma Key. Caso essa entidade não tenha pai, retorna None.

set_unindexed_properties(unindexed_properties)source

setdefault(name, value)source

Caso a propriedade exista, retorna o valor dela. Do contrário, é definida como o valor.

Caso o nome da propriedade seja a string vazia ou não seja uma, gera BadPropertyError. Caso o valor não seja compatível, gera BadValueError.

unindexed_properties()source: Retorna as propriedades não indexadas dessa entidade, como um frozenset de strings.

update(other)source

Atualiza as propriedades dessa entidade dos valores em outras.

Caso algum nome de propriedade seja a string vazia ou não seja uma string, gera BadPropertyError. Caso algum valor não seja compatível, gera BadValueError.

google.appengine.api.datastore.Get(keys, **kwargs)source

Recupera uma ou mais entidades do armazenamento de dados.

Recupera a entidade ou as entidades com a(s) chave(s) Indicada(s) do armazenamento de dados e as retorna como objetos Entity totalmente preenchidos, conforme definido abaixo. Caso haja um erro, gera uma subclasse de datastore_errors.Error.

Se as chaves forem uma chave ou uma string única, uma Entity será retornada, ou EntityNotFoundError será gerado se nenhuma entidade existente corresponder à chave.

No entanto, se as chaves forem uma lista ou uma tupla, uma lista de entidades será retornada correspondente à sequência de chaves. Ela incluirá entidades para chaves que foram encontradas e marcadores None para chaves que não foram encontradas.

Parâmetros

keys: chave ou string ou lista de Keys ou strings
config: configuração opcional a ser usada nesta solicitação, precisa ser especificada como um argumento de palavra-chave.

Retorna

Entidade ou lista de objetos Entity

google.appengine.api.datastore.GetAsync(keys, **kwargs)source

Recupera de maneira assíncrona uma ou mais entidades do armazenamento de dados.

Idêntico a datastore.get(), exceto por retornar um objeto assíncrono. Chame get_result() no valor de retorno a ser bloqueado na chamada e receba os resultados.

google.appengine.api.datastore.GetIndexes(**kwargs)source

Retorna os índices de aplicativo e os estados deles.

Parâmetros

config: configuração opcional a ser usada nesta solicitação, precisa ser especificada como um argumento de palavra-chave.

Retorna

Uma lista (Index, Index.[BUILDING|SERVING|DELETING|ERROR]) Um índice pode estar nos seguintes estados:

Index.BUILDING: o índice está sendo criado e, portanto, não pode exibir consultas Index.SERVING: o índice está pronto para exibir consultas Index.DELETING: o índice está sendo excluído Index.ERROR: o índice encontrou um erro no estado BUILDING

google.appengine.api.datastore.GetIndexesAsync(**kwargs)source

Recupera de maneira assíncrona os índices de aplicativo e os estados deles.

Idêntico a GetIndexes(), exceto por retornar um objeto assíncrono. Chame get_result() no valor de retorno a ser bloqueado na chamada e receba os resultados.

google.appengine.api.datastore.GetRpcFromKwargs(kwargs, convert_rpc=False, config_class=google.appengine.datastore.datastore_rpc.Configuration)source

Receba um objeto Configuration dos argumentos de palavra-chave.

Ele é essencialmente um auxiliar interno para as diversas APIs públicas abaixo, como Get().

Parâmetros

kwargs: um dict contendo os argumentos de palavra-chave passados para uma API pública.
convert_rpc: caso uma RPC precise ser convertida ou passada diretamente.
config_class: a classe de configuração que precisa ser gerada.

Retorna

Uma instância de UserRPC, uma instância de Configuration ou None.

Gera

TypeError caso argumentos de palavra-chave inesperados estejam presentes.

class google.appengine.api.datastore.Index(index_id, kind, has_ancestor, properties)source

Bases: google.appengine.api.datastore._BaseIndex

Um índice de armazenamento de dados.

HasAncestor()source: Indica se este é um índice de ancestral, um booleano.

Id()source: Retorna o código do índice, um longo.

Kind()source: Retorna o tipo de índice, uma string. String vazia (''), caso não haja nenhuma.

Properties()source: Retorna as propriedades do índice. uma tupla de (nome do índice como uma string, tuplas [ASCENDING|DESCENDING]).

google.appengine.api.datastore.IsInTransaction()source

Determine se ele já está em execução na transação.

Retorna

True caso já esteja em executando na transação, ou False.

class google.appengine.api.datastore.Iterator(batcher)source

Bases: google.appengine.datastore.datastore_query.ResultsIterator

Wrapper fino do datastore_query.ResultsIterator.

Obsoleto, não use, apenas para compatibilidade com versões anteriores.

GetCompiledCursor(query)source

GetIndexList()source: Retorna a lista de índices usados para realizar a consulta.

index_list()source: Retorna a lista de índices usados para realizar a consulta.

class google.appengine.api.datastore.MultiQuery(bound_queries, orderings)source

Bases: google.appengine.api.datastore.Query

Classe que representa uma consulta que requer várias consultas do armazenamento de dados.

Na verdade, essa classe é uma subclasse de datastore.Query, já que ela pretende atuar como um objeto Query normal (compatível com a mesma interface).

Não aceita consultas somente de chaves, porque precisa de entidades inteiras para mesclá-las. Não será verdadeiro se não houver ordens de classificação, ou se a ordem de classificação for __key__, mas permitindo consultas somente de chaves nesses casos, mas não em outros, porque isso seria confuso.

Count(limit=1000, **kwargs)source

Retorna o número de entidades correspondentes a esta consulta.

Retornará a contagem desduplicada de resultados. Chamará a função Get() mais eficiente se um limite for indicado.

Parâmetros

limite: número máximo de entradas a serem contadas (para qualquer result > limit, return
limit) –
config: configuração opcional a ser usada nesta solicitação.

Retorna

a contagem do número de entradas retornadas.

Get(limit, offset=0, **kwargs)source

Obsoleto, use list(Run(…)) em seu lugar.

Parâmetros

limit: int ou longo que representa o número máximo de entidades a serem retornadas.
offset: int ou longo que representa o número de entidades a serem ignoradas
kwargs: quaisquer argumentos de palavra-chave aceitos por datastore_query.QueryOptions().

Retorna

Uma lista de entidades com o máximo de entradas de “limite” (menos caso a consulta seja concluída antes da leitura dos valores de limite).

GetCompiledCursor()source

GetCompiledQuery()source: Somente interno, não use.

GetCursor()source

GetIndexList()source

Run(**kwargs)source

Retorne uma saída iterável com todos os resultados na ordem.

Mescle a classificação dos resultados. Crie primeiramente uma lista de iteradores, examine-os e produza resultados na ordem.

Parâmetros

kwargs: quaisquer argumentos de palavra-chave aceitos por datastore_query.QueryOptions().

Retorna

Um iterador para o conjunto de resultados.

class SortOrderEntity(entity_iterator, orderings)source

Bases: object

Permita comparações de entidade usando ordens fornecidas.

O iterador passado para o construtor acaba sendo consumido por meio de chamadas para GetNext(), que geram novas SortOrderEntitys com as mesmas ordens.

CmpProperties(that)source

Compare duas entidades e retorne a ordem relativa.

Compara-se com a baseada nas ordens de classificação atuais e as ordens de chave entre elas. Retorna negativo, 0 ou positivo, caso seja menor que, igual a ou maior que. Essa comparação retorna como se todos os valores fossem colocados em ordem crescente (maior valor por último). Usa somente as ordens de classificação para comparar (ignora

chaves).

Parâmetros

that: SortOrderEntity

Retorna

Negativo caso self < that Zero caso self == that Positivo caso self > that

GetEntity()source: Recupera a entidade encapsulada.

GetNext()source

Encapsule e retorne a próxima entidade.

A entidade é recuperada do iterador indicado no momento da construção.

google.appengine.api.datastore.NonTransactional(*args, **kwds)source

Um decorador que garante que uma função seja executada fora de uma transação.

Caso haja uma transação existente (e allow_existing=True), a transação existente é pausada e a função é executada.

Parâmetros

_func: não use
allow_existing: caso falso, lance uma exceção caso chamado dentro de uma transação

Retorna

Um wrapper da função decorada que garante que ela seja executada fora de uma transação.

google.appengine.api.datastore.NormalizeAndTypeCheck(arg, types)source

Normaliza e verifica o argumento indicado.

Parâmetros

arg: uma instância ou um iterável do(s) tipo(s) indicado(s)
types: tipo permitido ou tupla de tipos

Retorna

Uma tupla (list, bool). A lista é uma cópia normalizada e superficial do argumento. O booleano será True se o argumento for uma sequência, False se for um único objeto.

Gera

AssertionError: ente os tipos estão lista ou tupla.
BadArgumentError: arg não é uma instância ou uma sequência de um dos tipos
indicados.

google.appengine.api.datastore.NormalizeAndTypeCheckKeys(keys)source

Normaliza e verifica se o argumento indicado é uma chave válida.

Um wrapper em torno de NormalizeAndTypeCheck() que aceita strings, chaves e entidades e normaliza como chaves.

Parâmetros

keys: uma chave ou uma sequência de chaves

Retorna

Uma tupla (list of Keys, bool). Consulte NormalizeAndTypeCheck.

Gera

BadArgumentError: arg não é uma instância ou uma sequência de um dos tipos
indicados.

google.appengine.api.datastore.Put(entities, **kwargs)source

Armazene uma ou mais entidades no armazenamento de dados.

As entidades podem ser novas ou já existentes. Para novas entidades, Put() preencherá o código do aplicativo e a chave atribuída pelo armazenamento de dados.

Se o argumento for uma entidade única, uma única Key será retornada. Se o argumento for uma lista de entidades, uma lista de chaves será retornada.

Parâmetros

entities: entidade ou lista de entidades
config: configuração opcional a ser usada nesta solicitação, precisa ser especificada como um argumento de palavra-chave.

Retorna

Chave ou lista de chaves

Gera

TransactionFailedError, caso não seja possível confirmar Put.

google.appengine.api.datastore.PutAsync(entities, **kwargs)source

Armazene de maneira assíncrona uma ou mais entidades no armazenamento de dados.

Idêntico a datastore.Put(), exceto por retornar um objeto assíncrono. Chame get_result() no valor de retorno a ser bloqueado na chamada e receba os resultados.

class google.appengine.api.datastore.Query(kind=None, filters={}, _app=None, keys_only=False, compile=True, cursor=None, namespace=None, end_cursor=None, projection=None, distinct=None, _namespace=None)source

Bases: dict

Uma consulta de armazenamento de dados.

Em vez disso, considere o uso de appengine.ext.gql.Query! Ele oferece uma interface de linguagem de consulta na mesma funcionalidade.

As consultas são usadas para recuperar entidades que correspondem a determinados critérios, inclusive o código do aplicativo, o tipo e os filtros de propriedade. Os resultados também podem ser classificados por propriedades.

O código do aplicativo e o tipo são obrigatórios. Somente entidades do aplicativo indicado, do tipo especificado, são retornadas. Caso um ancestral seja definido, com Ancestor(), somente entidades com esse ancestral são retornadas.

Os filtros de propriedade são usados para fornecer critérios com base em valores de propriedade individuais. Um filtro compara uma propriedade específica em cada entidade com um determinado valor ou lista de valores possíveis.

Uma entidade será retornada se os valores de propriedade corresponderem a todos os filtros da consulta. Em outras palavras, os filtros são combinados com AND, e não OR. Se uma entidade não tiver um valor para uma propriedade usada em um filtro, ela não será retornada.

Os filtros de propriedade mapeiam strings de filtro da forma "<nome da propriedade> <operador>" para filtrar valores. Use acessadores de dicionário para definir filtros de propriedade assim:

> query = Query(‘Person’) > query[‘name =’] = ‘Ryan’ > query[‘age >=’] = 21

Esta consulta retorna todas as entidades Person em que a propriedade name seja "Ryan" e a propriedade age seja pelo menos 21.

Outra maneira de criar essa consulta é:

> query = Query(‘Person’) > query.update({‘name =’: ‘Ryan’, ‘age >=’: 21})

Os operadores compatíveis são =, >, <, >= e <=. Só um filtro de desigualdade pode ser usado por consulta. Um número qualquer de filtros de igualdade pode ser usado em uma única consulta.

Um valor de filtro pode ser uma lista ou uma tupla de valores. Isso é interpretado como vários filtros com a mesma string de filtro e valores diferentes, todos com AND. Por exemplo, essa consulta retorna tudo com as tags "google" e "app engine":

> Query(‘Person’, {‘tag =’: (‘google’, ‘app engine’)})

As entidades resultantes podem ser retornadas em ordens diferentes. Use o método Order() para especificar propriedades com resultados que serão classificados e em qual direção.

Os filtros e as ordens podem ser fornecidos a qualquer momento antes da consulta ser executada. Quando a consulta é totalmente especificada, Run() executa a consulta e retorna um iterador. Os resultados da consulta podem ser acessados por meio do iterador.

Um objeto de consulta poderá ser reutilizado depois de ter sido executado. Os filtros e as ordens podem ser alterados para criar uma consulta modificada.

Se souber de quantas entidades de resultado você precisa, use Get() para buscá-las:

> query = Query(‘Person’, {‘age >’: 21}) > para a pessoa na consulta.Get(4): > print "Tenho quatro cervejas restantes. Tome uma por minha conta, %s!" % person['name']

Se não souber de quantos resultados precisa, ou se precisar de todos, você poderá receber um iterador nos resultados chamando Run():

> para pessoa em Query('Person', {'age >': 21}).Run(): > print "Tome uma cerveja por minha conta, %s!" % person['name']

Get() é mais eficiente que Run(). Dessa maneira, use Get() sempre que possível.

Por fim, o método Count() retorna o número de entidades de resultado correspondentes à consulta. A contagem retornada é armazenada em cache. As chamadas Count() sucessivas não verificarão novamente o armazenamento de dados, a menos que a consulta seja alterada.

ANCESTOR_FIRST = 2

ASCENDING = 1

Ancestor(ancestor)source

Define um ancestral para esta consulta.

Isso restringe a consulta para retornar apenas entidades resultantes que sejam descendentes de uma determinada entidade. Em outras palavras, todos os resultados terão o ancestral como pai, como pai do pai e assim por diante.

Gera BadArgumentError ou BadKeyError caso o pai não seja uma entidade ou chave existente no armazenamento de dados.

Parâmetros

a chave precisa estar completa (#) -
ancestor: Entity ou Key

Retorna

# esta consulta

Count(limit=1000, **kwargs)source

Retorna o número de entidades correspondentes a essa consulta.

Parâmetros

um número ou None. Caso haja mais resultados além deste, pare short (limit) -
apenas retorna esse número. Fornecer este argumento deixa a contagem (e) -
mais eficiente. (operação) –
config: configuração opcional a ser usada nesta solicitação.

Retorna

O número de resultados.

DESCENDING = 2

FILTER_FIRST = 3

FILTER_REGEX = <_sre.SRE_Pattern object>

Get(limit, offset=0, **kwargs)source

Obsoleto, use list(Run(…)) em seu lugar.

Parâmetros

limit: int ou longo que representa o número máximo de entidades a serem retornadas.
offset: int ou longo que representa o número de entidades a serem ignoradas
kwargs: quaisquer argumentos de palavra-chave aceitos por datastore_query.QueryOptions().

Retorna

# uma lista de entidades [Entity, …]

GetBatcher(config=None)source

Executa esta consulta e retorna um datastore_query.Batcher.

Ele não precisa ser usado por desenvolvedores de aplicativo. Use Get() em vez disso.

Parâmetros

config: configuração opcional a ser usada nesta solicitação.

Retorna

# um iterador que dá acesso aos resultados da consulta Iterator

GetCompiledCursor()source

Receba o cursor da última execução desta consulta.

A origem deste cursor varia de acordo com a última chamada feita:

Run: um cursor que apontará logo depois do último resultado recebido do iterador retornado.
Get: um cursor que apontará logo depois do último resultado na lista retornada.
Count: um cursor que apontará imediatamente depois do último resultado contado.

Retorna

Um objeto datastore_query.Cursor que pode ser usado em solicitações de consulta subsequentes.

Gera

AssertionError: a consulta ainda não foi executada ou não pode ser compilada.

GetCompiledQuery()source

Retorna a representação pb somente interna da última consulta executada.

Não use.

Gera

AssertionError: consulta não compilada ou ainda não executada.

GetCursor()source

Receba o cursor da última execução desta consulta.

A origem deste cursor varia de acordo com a última chamada feita:

Run: um cursor que apontará logo depois do último resultado recebido do iterador retornado.
Get: um cursor que apontará logo depois do último resultado na lista retornada.
Count: um cursor que apontará imediatamente depois do último resultado contado.

Retorna

Um objeto datastore_query.Cursor que pode ser usado em solicitações de consulta subsequentes.

Gera

AssertionError: a consulta ainda não foi executada ou não pode ser compilada.

GetDistinct()source

Retorna True caso a instância atual seja distinta.

Retorna

Um booleano que indica se a sinalização distinta está definida.

GetFilterPredicate()source

Retorna um datastore_query.FilterPredicate para a instância atual.

Retorna

datastore_query.FilterPredicate ou None se nenhum filtro estiver definido na Query atual.

GetIndexList()source

Receba a lista de índices da última execução desta consulta.

Retorna

Uma lista de índices usados pela última execução desta consulta.

Gera

AssertionError: a consulta ainda não foi executada.

GetOrder()source

Recebe um datastore_query.Order para a instância atual.

Retorna

datastore_query.Order ou None caso não haja ordens de classificação definidas na Query atual.

GetQuery()source: Retorna uma datastore_query.Query para a instância atual.

GetQueryOptions()source: Retorna uma datastore_query.QueryOptions para a instância atual.

Hint(hint)source

Define uma dica de como esta consulta precisa ser executada.

A dica de consulta nos dá informações sobre a melhor maneira de executar a consulta. Atualmente, só podemos fazer uma verificação de índice. Dessa maneira, a dica de consulta precisa ser usada para indicar qual índice precisamos verificar.

Use FILTER_FIRST se o primeiro filtro corresponder apenas a alguns resultados. Neste caso, será mais eficiente verificar o índice dessa propriedade, carregar os resultados na memória e aplicar os filtros e as ordens de classificação restantes.

Da mesma maneira, use ANCESTOR_FIRST caso o ancestral da consulta tenha apenas alguns descendentes. Nesse caso, será mais eficiente verificar todas as entidades abaixo do ancestral e carregá-las na memória primeiro.

Use ORDER_FIRST caso a consulta tenha uma ordem de classificação e o conjunto de resultados seja grande ou caso você queira buscar apenas os primeiros resultados. Neste caso, não precisamos tentar carregar todos os resultados na memória. Em vez disso, precisamos verificar o índice dessa propriedade, que está na ordem classificada.

As dicas são ignoradas no armazenamento de dados v3 no momento.

Arg:: um de datastore.Query.[ORDER_FIRST, ANCESTOR_FIRST, FILTER_FIRST]

Retorna

# esta consulta

INEQUALITY_OPERATORS = frozenset([u'<=', u'>=', u'<', u'>'])

IsKeysOnly()source: Retorna True caso esta consulta seja somente de chaves. Do contrário, False.

OPERATORS = {u'>=': 4, '==': 5, u'<=': 2, u'=': 5, u'<': 1, u'>': 3}

ORDER_FIRST = 1

Order(*orderings)source

Especifica como os resultados da consulta precisam ser classificados.

As entidades de resultado serão classificadas pelo primeiro argumento de propriedade e depois pelo segundo e assim por diante. Por exemplo, este:

> query = Query(‘Person’) > query.Order(‘bday’, (‘age’, Query.DESCENDING))

classifica todos na ordem dos aniversários deles, começando em 1º de janeiro. As pessoas com o mesmo aniversário são classificadas por idade, das mais velhas para as mais novas.

A direção de cada propriedade de classificação pode ser fornecida. Caso omitida, o padrão é crescente.

Order() pode ser chamado várias vezes. Cada chamada redefine a ordem de classificação do zero.

Se existir um filtro de desigualdade nessa Query, ele precisará ser a primeira propriedade passada para Order. Um número qualquer de ordens de classificação poderá ser usado depois da propriedade do filtro de desigualdade. Sem filtros de desigualdade, um número qualquer de filtros com ordens diferentes pode ser especificado.

Entidades com vários valores para uma propriedade de ordem são classificadas pelo valor mais baixo.

Uma ordem de classificação implica um filtro de existência. Em outras palavras, Entities sem a propriedade da ordem de classificação são filtradas e não são incluídas nos resultados da consulta.

Se a propriedade da ordem de classificação tiver tipos diferentes em entidades diferentes, ou seja, se bob['id'] for um int e fred['id'] for uma string, as entidades serão agrupadas primeiro pelo tipo de propriedade e depois classificadas dentro do tipo. Nenhuma tentativa é feita de comparar valores de propriedade entre tipos.

Gera BadArgumentError caso algum argumento seja do formato errado.

Parâmetros

As propriedades para classificação, na ordem. Cada argumento pode ser um (#) -
string ou (#) –

Retorna

# esta consulta

Run(**kwargs)source

Executa esta consulta.

Caso uma string de filtro seja inválida, gera BadFilterError. Caso um valor de filtro seja inválido, gera BadValueError. Caso um filtro IN seja fornecido e uma ordem de classificação em outra propriedade seja fornecida, BadQueryError é gerado.

Se você souber com antecedência quantos resultados quer, use limit=#. É mais eficiente.

Parâmetros

kwargs: quaisquer argumentos de palavra-chave aceitos por datastore_query.QueryOptions().

Retorna

# um iterador que dá acesso aos resultados da consulta Iterator

UPPERBOUND_INEQUALITY_OPERATORS = frozenset(['<=', '<'])

copy()source: O método de cópia não é compatível.

setdefault(filter, value)source

Caso o filtro exista, retorna o valor dele. Do contrário, é definida como o valor.

Caso o nome da propriedade seja a string vazia ou não seja uma, gera BadPropertyError. Caso o valor não seja compatível, gera BadValueError.

update(other)source

Atualiza os filtros dessa consulta para outros.

Caso alguma string de filtro seja inválida, gera BadFilterError. Caso algum valor não seja de tipo compatível, gera BadValueError.

google.appengine.api.datastore.RunInReadOnlyTransaction(function, *args, **kwargs)source

Executa uma função dentro de uma transação de armazenamento de dados somente leitura.

Uma transação somente leitura não pode executar gravações, mas pode ser executada com mais eficiência.

Executa a função fornecida pelo usuário dentro de uma transação somente leitura e tenta novamente o número padrão de vezes.

Parâmetros

function: uma função a ser executada dentro da transação em todos os argumentos restantes
*args: argumentos posicionais para função.
**kwargs: argumentos de palavra-chave para função.

Retorna

o valor de retorno da função, se houver

Gera

TransactionFailedError, caso não seja possível confirmar a transação.

google.appengine.api.datastore.RunInReadOnlyTransactionOptions(options, function, *args, **kwargs)source

Executa uma função dentro de uma transação de armazenamento de dados somente leitura.

Uma transação somente leitura não pode executar gravações, mas pode ser executada com mais eficiência.

Assim como RunInTransactionOptions, mas com uma transação somente leitura.

Parâmetros

options: TransactionOptions que especificam opções (número de novas tentativas etc.) para esta transação
function: uma função a ser executada dentro da transação em todos os argumentos restantes *args: argumentos posicionais para função. **kwargs: argumentos de palavra-chave para função.

Retorna

o valor de retorno da função, se houver

Gera

TransactionFailedError, caso não seja possível confirmar a transação.

google.appengine.api.datastore.RunInTransaction(function, *args, **kwargs)source

Executa uma função dentro de uma transação de armazenamento de dados.

Executa a função fornecida pelo usuário dentro da transação e tenta novamente o número padrão de vezes.

Args:

function: uma função a ser executada dentro da transação em todos os: argumentos restantes

*args: argumentos posicionais para função. **kwargs: argumentos de palavra-chave para função.

Retorna

o valor de retorno da função, se houver

Gera

TransactionFailedError, caso não seja possível confirmar a transação.

google.appengine.api.datastore.RunInTransactionCustomRetries(retries, function, *args, **kwargs)source

Executa uma função dentro de uma transação de armazenamento de dados.

Executa a função fornecida pelo usuário dentro da transação, com um número especificado de novas tentativas.

Args:

retries: número de novas tentativas (sem contar a tentativa inicial) function: uma função a ser executada dentro da transação em todos os

argumentos restantes

*args: argumentos posicionais para função. **kwargs: argumentos de palavra-chave para função.

Retorna

o valor de retorno da função, se houver

Gera

TransactionFailedError, caso não seja possível confirmar a transação.

google.appengine.api.datastore.RunInTransactionOptions(options, function, *args, **kwargs)source

Executa uma função dentro de uma transação de armazenamento de dados.

Executa a função fornecida pelo usuário dentro de uma transação de armazenamento de dados ACID repleta de recursos. Cada Put, Get e Delete chama a função feita dentro da transação. Todas as entidades envolvidas nessas chamadas precisam pertencer ao mesmo grupo de entidades. As consultas são compatíveis, desde que especifiquem um ancestral pertencente ao mesmo grupo de entidades.

Os argumentos à direita são passados para a função como argumentos posicionais. Se a função retornar um valor, esse valor será retornado por RunInTransaction. Do contrário, ele retornará None.

A função pode gerar qualquer exceção para reverter a transação, em vez de confirmá-la. Se isso acontecer, a transação será revertida, e a exceção será regenerada até o autor da chamada de RunInTransaction.

Se quiser reverter intencionalmente, mas não tiver uma exceção apropriada para gerar, você poderá gerar uma instância de datastore_errors.Rollback. Isso causará uma reversão, mas não será regenerado até o autor da chamada.

A função pode ser executada mais de uma vez. Dessa maneira, ela precisa ser idempotente. Ela precisa evitar efeitos colaterais, e não ter nenhum com segurança para ocorrer várias vezes. Isso inclui modificar os argumentos, porque eles se mantêm em invocações da função. No entanto, isso não inclui chamadas Put, Get e Delete, obviamente.

Exemplo de uso:

> def decrement(key, amount=1): > counter = datastore.Get(key) > counter[‘count’] -= amount > se counter[‘count’] < 0: # não deixe o contador negativo > raise datastore_errors.Rollback() > datastore.Put(counter) > > counter = datastore.Query(‘Counter’, {‘name’: ‘foo’}) > datastore.RunInTransaction(decrement, counter.key(), amount=5)

As transações atendem a propriedades ACID tradicionais. Elas são:

Atômicas. Todas as operações de uma transação são executadas ou nenhuma delas é.
Consistentes. O estado do armazenamento de dados é consistente antes e depois de uma

transação, seja ela confirmada ou revertida. Invariantes como "toda entidade tem uma chave primária" são preservadas.

Isoladas. As transações funcionam em um instantâneo do armazenamento de dados. Outras

operações de armazenamento de dados não veem efeitos intermediados da transação. Elas só verão os efeitos depois de confirmadas.

Duráveis. No commit, todas as gravações são mantidas no armazenamento de dados.

As transações aninhadas não são compatíveis.

Parâmetros

options: TransactionOptions que especificam opções (número de novas tentativas etc.) para esta transação
function: uma função a ser executada dentro da transação em todos os argumentos restantes *args: argumentos posicionais para função. **kwargs: argumentos de palavra-chave para função.

Retorna

o valor de retorno da função, se houver

Gera

TransactionFailedError, caso não seja possível confirmar a transação.

google.appengine.api.datastore.Transactional(_func=None, **kwargs)source

Um decorador que garante que uma função é executada em uma transação.

Propagação de padrões para datastore_rpc.TransactionOptions.ALLOWED, o que significa que qualquer transação existente será usada no lugar da criação de uma nova.

AVISO: a leitura do armazenamento de dados durante uma transação não verá nenhuma alteração feita na mesma transação. Se a função decorada depende de ver todas as alterações feitas no escopo de chamada, defina propagation=datastore_rpc.TransactionOptions.NESTED.

Parâmetros

_func: não use.
**kwargs: opções de configuração de TransactionOptions.

Retorna

Um wrapper para a função indicada que cria uma nova transação, se necessário.