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.

Funções do NDB

Functions

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 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 ou gera qualquer callback ou um TransactionFailedError se a transação falhar.

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 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`	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`	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).