Funções do NDB

Funções

ndb.add_flow_exception(exc)
Especifique que uma exceção não deve ser registrada, apenas fazer 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 subclasses)
  • ndb.Rollback
ndb.delete_multi(keys, **ctx_options)
Exclui entidades identificadas pela sequência de "keys" 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 "keys" aprovada.

Argumentos

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

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

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

Argumentos

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

Retorna uma lista. Cada item da lista é uma instância de Model ou None se a chave não foi 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. Todos os resultados do futuro são uma instância de Model ou None, caso a chave não tenha sido encontrada.

ndb.in_transaction()
Retorna um booleano que indica 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
Se True (o padrão) e se a função decorada for chamada por código em uma transação, a função será executada independentemente da transação. Se False e se a função decorada for chamada por código em uma transação, ela gerará uma exceção.
ndb.put_multi(entities, **ctx_options)
Armazena uma sequência de instâncias de Modelo.

Argumentos

entidades
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

entidades
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 retorno de chamada gerado ou uma exceção TransactionFailedError se a transação falhar.

Para transferir argumentos para uma função de callback, 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 ou gera qualquer callback ou um TransactionFailedError se a transação falhar.

Para transferir argumentos para uma função de callback, 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 de palavra-chave especiais options e config (que têm significados idênticos por motivos históricos) permitem especificar várias opções como um objeto de configuração. 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)) equivale 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 Duração máxima da chamada ao armazenamento de dados, 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 Defina isso como ndb.EVENTUAL_CONSISTENCY se, em vez de esperar que o Datastore termine de aplicar as alterações a todos os resultados retornados, você queira receber resultados possivelmente não mais atuais.
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 conjunto do Memcache serão combinadas 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). False por padrão.
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 é padronizada como ALLOWED.

A política de propagação para ndb.transaction() é padronizada como NESTED. A política NESTED não é compatível com o NDB, então seu código emitirá 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 confirmaria todas as alterações nas transações internas e externas quando a política externa executasse uma confirmação. 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. Se você usar essa política, seu código gerará uma exceção BadRequestError.
ndb.TransactionOptions.MANDATORY
Sempre propague uma transação existente. Lance uma exceção icaso 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 atual, 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 atuais. 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 fazem com que TypeError seja gerado.

Operações com diferentes opções são agrupadas quando envio em lote automático é aplicado. Por exemplo, se você usar put_async() para gravar algumas entidades com deadline = 5 e outras sem especificar um prazo, e todas estiverem qualificadas para o lote automático, o lote automático fará duas chamadas RPC separadas, uma para o grupo de entidades com deadline = 5 e uma para o outro grupo, mesmo que o prazo padrão da RPC também seja 5. Isso se aplica mesmo se a opção especificada for irrelevante para a operação RPC (por exemplo, ndb_should_cache).