Funções do NDB

Funções

ndb.add_flow_exception(exc)
Especifique que uma exceção não seja registrada, mas apenas faça parte do fluxo normal do programa. Em geral, criar uma exceção grava uma mensagem de aviso nos registros do aplicativo.

Argumentos

exc
Classe de exceção que não é registrada.

Por padrão, as seguintes exceções não são registradas:

  • webob.exc.HTTPException e as respectivas subclasses
  • ndb.Rollback
ndb.delete_multi(keys, **ctx_options)
Exclui entidades identificadas pela sequência de chaves aprovada.

Argumentos

keys
Sequência de keys
**ctx_options
Opções de contexto
ndb.delete_multi_async(keys, **ctx_options)
Exclui de forma assíncrona entidades identificadas pela sequência de chaves aprovada.

Argumentos

keys
Sequência de keys
**ctx_options
Opções de contexto

Retorna uma lista de objetos Future. O resultado de cada "future" será None.

ndb.get_multi(keys, **ctx_options)
Busca entidades identificadas pela sequência de chaves aprovada.

Argumentos

keys
Sequência de keys
**ctx_options
Opções de contexto

Retorna uma lista. Cada item da lista será uma instância de Model ou None se a chave não tiver sido encontrada.

ndb.get_multi_async(keys, **ctx_options)
Busca de forma assíncrona entidades identificadas pela sequência de "keys" aprovada.

Argumentos

keys
Sequência de keys
**ctx_options
Opções de contexto

Retorna uma lista de objetos Future. Cada item da lista será uma instância de Model ou None se a chave não tiver sido encontrada.

ndb.in_transaction()
Retorna um booleano indicando se uma transação está ativa no momento.
@ndb.non_transactional
@ndb.non_transactional(allow_existing=True)
Decorador para garantir que uma função seja executada fora de uma transação.

Argumentos:

allow_existing
Para True, que é o padrão e quando a função decorada é chamada por código em uma transação, esta função é executada independentemente da transação. Para False e quando a função decorada é chamada por código em uma transação, ela gera uma exceção.
ndb.put_multi(entities, **ctx_options)
Armazena uma sequência de instâncias de Model.

Argumentos

entities
Sequência de instâncias de Model
**ctx_options
Opções de contexto

Retorna uma lista com as keys armazenadas.

ndb.put_multi_async(entities, **ctx_options)
Armazena de forma assíncrona uma sequência de instâncias de Model.

Argumentos

entities
Sequência de instâncias de Model
**ctx_options
Opções de contexto

Retorna uma lista de objetos Future. O resultado de cada "future" será uma key armazenada.

ndb.transaction(callback, **ctx_options)
Execute um callback em uma transação.

Argumentos

callback
Função ou "tasklet" a ser chamado
**ctx_options
Opções de transação

Retorna qualquer retorno de chamada. Gera qualquer callback ou uma exceção TransactionFailedError em caso de falha da transação.

Para transferir 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))
ndb.transaction_async(callback, **ctx_options)
Executar de forma assíncrona um retorno de chamada em uma transação.

Argumentos

callback
Função ou "tasklet" a ser chamado
**ctx_options
Opções de transação

Retorna um Future. O "future" retorna qualquer callback, gera qualquer callback ou um TransactionFailedError em caso de falha na transação.

Para transferir 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))
@ndb.transactional
@ndb.transactional(**ctx_options)
Decorador para fazer com que uma função seja executada automaticamente em uma transação.

Argumentos:

Este decorador tem opções de transação.

Opções de contexto, opções de transação

As opções de contexto permitem executar determinadas operações de armazenamento de dados com diferentes configurações. Por exemplo, talvez você queira variar a política de leitura ou o prazo da RPC para solicitações individuais. É possível fazer isso transferindo as opções de contexto para praticamente qualquer operação. Algumas funções relacionadas a transações aceitam as opções de transação, que incluem outras opções com base em um conjunto de opções de contexto.

Veja aqui alguns exemplos que usam opções de contexto. Ao ler uma entidade, para configurar o prazo da RPC para 1 segundo, use o seguinte:

key.get(deadline=1)

Ao gravar uma entidade, para configurar o tempo limite do memcache para 30 segundos, use o seguinte:

ent.put(ndb_memcache_timeout=30)

Para excluir um item armazenado em cache e forçar o recarregamento, use o seguinte:

key.delete(use_datastore=False)

Os argumentos especiais de palavras-chave options e config, que por razões históricas têm significados idênticos, permitem especificar diversas opções como objeto "Configuration". Isso pode ser um objeto ndb.ContextOptions ou (para as funções transacionais e decorador), um objeto ndb.TransactionOptions. Por exemplo, key.get(options=ndb.ContextOptions(use_cache=True)) é equivalente a key.get(use_cache=True). As opções configuradas em tal objeto de opções são substituídas por parâmetros de palavras-chave.

Estão disponíveis as seguintes opções de contexto:

Opção Tipo Descrição
deadline float Prazo de chamada do Datastore, especificado como número de segundos. Por padrão, a chamada é interrompida apenas pelo prazo do gerenciador de solicitações.
read_policy ndb.EVENTUAL_CONSISTENCY Configure isso para ndb.EVENTUAL_CONSISTENCY caso você queira atingir mais rapidamente resultados que talvez não sejam atuais, em vez de esperar que o Datastore conclua a aplicação de alterações a todos os resultados retornados.
force_writes bool Especifica se a solicitação de gravação será bem-sucedida, mesmo que o aplicativo seja de somente leitura. Isso é aplicado somente a períodos de somente leitura controlados pelo usuário.
use_cache bool Especifica se é necessário armazenar entidades no cache em processamento e substitui a política de cache em processamento para esta operação.
use_memcache bool Especifica se é necessário armazenar entidades no memcache e substitui a política do memcache para esta operação.
use_datastore bool Especifica se é necessário armazenar entidades no Datastore e substitui a política do Datastore para esta operação.
memcache_timeout int Tempo de vida máximo para entidades no memcache. Substitui a política de tempo limite do memcache para esta operação.
max_memcache_items int Tamanho máximo do lote para o recurso de envio em lote automático dos métodos de Context do memcache. Por exemplo, com o tamanho padrão de max_memcache_items (100), até 100 operações de conjuntos do memcache serão combinados em uma única operação set_multi.

Para algumas funções relacionadas a transações, as seguintes operações de transações estão disponíveis, junto com as opções de contextos herdadas e listadas acima:

Opção Tipo Descrição
xg bool Permitir transações entre grupos (XG). Por padrão, False.
propagation int

O NDB oferece suporte limitado para transações dentro de transações, conhecidas como "transações aninhadas".

O parâmetro de propagação controla o que acontece quando seu código tenta iniciar uma transação aninhada.

A política de propagação para @ndb.transactional assume ALLOWED como padrão.

A política de propagação para ndb.transaction() assume NESTED como padrão. A política NESTED não é compatível com NDB, por isso seu código lançará uma exceção BadRequestError. O NDB configura um valor padrão não compatível neste caso, assim os programadores estão explicitamente cientes das limitações das transações aninhadas.

O parâmetro de propagação é um dos seguintes valores:

ndb.TransactionOptions.NESTED
A política de propagação NESTED comprometeria todas as alterações nas transações internas e externas quando a política externa executasse um commit. No entanto, caso uma exceção seja lançada na transação interna, todas as alterações serão descartadas, mas permitirão que a transação externa seja opcionalmente recuperada e permaneça. A política NESTED não é compatível. Ao utilizá-la, seu código lançará uma exceção BadRequestError.
ndb.TransactionOptions.MANDATORY
Sempre propague uma transação existente. Lance uma exceção caso não haja uma transação existente. Caso uma função, que use essa política, lance uma exceção, talvez não seja seguro detectar essa exceção e executar o "commit" da transação externa. A função talvez tenha deixado essa transação externa em mau estado.
ndb.TransactionOptions.ALLOWED
No caso de haver transação existente, propague-a. Caso uma função, que use essa política, lance uma exceção, talvez não seja seguro detectar essa exceção e executar o "commit" da transação externa. A função talvez tenha deixado essa transação externa em mau estado.
ndb.TransactionOptions.INDEPENDENT
Sempre use uma nova transação, "pausando" todas as transações existentes. Uma função que usa essa política não retorna entidade alguma lida na nova transação, porque as entidades não são transacionalmente consistentes com a transação do responsável pela chamada.
retries int A quantidade de novas tentativas automáticas, em caso de falhas na transação. Zero significa tentar uma vez, mas não tentar novamente.

Em alguns casos, as opções serão ignoradas devido ao armazenamento em cache. Por exemplo, ao especificar um prazo de RPC para uma operação de leitura que é atendida no cache em contexto, o prazo será ignorado. Por outro lado, as opções não reconhecidas causam a criação de TypeError.

Operações com diferentes opções são agrupadas quando envio em lote automático é aplicado. Por exemplo, quando você usa put_async() para gravar algumas entidades com deadline = 5, algumas sem um prazo específico, e todas são elegíveis para o envio em lote automático, duas chamadas de RPC distintas serão feitas pelo loteador automático: uma para o grupo de entidades com deadline = 5 e uma para o outro grupo, mesmo que o prazo da RPC padrão seja também 5! Isso será aplicado mesmo que a opção especificada seja irrelevante para a operação de RPC. Por exemplo, ndb_should_cache.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente padrão do App Engine para Python 2