Funzioni NDB

Funzioni

ndb.add_flow_exception(exc)
Specifica che un'eccezione non deve essere registrata, ma fa parte del normale flusso del programma. (Normalmente, la generazione di un'eccezione scrive un messaggio di avviso nei log dell'applicazione.)

Argomenti

exc
Classe di eccezione che non deve essere registrata.

Per impostazione predefinita, le seguenti eccezioni non vengono registrate:

  • webob.exc.HTTPException (e le relative sottoclassi)
  • ndb.Rollback
ndb.delete_multi(keys, **ctx_options)
Elimina le entità identificate dalla sequenza di chiavi trasmessa.

Argomenti

chiavi
Sequenza di tasti
**ctx_options
Opzioni contestuali
ndb.delete_multi_async(keys, **ctx_options)
Elimina in modo asincrono le entità identificate dalla sequenza di chiavi trasmessa.

Argomenti

chiavi
Sequenza di tasti
**ctx_options
Opzioni di contesto

Restituisce un elenco di oggetti Future. Il risultato di ogni futuro sarà None.

ndb.get_multi(keys, **ctx_options)
Recupera le entità identificate dalla sequenza di chiavi trasmessa.

Argomenti

chiavi
Sequenza di tasti
**ctx_options
Opzioni di contesto

Restituisce un elenco. Ogni elemento dell'elenco è un'istanza di Model o None se la chiave non è stata trovata.

ndb.get_multi_async(keys, **ctx_options)
Recupera in modo asincrono le entità identificate dalla sequenza di chiavi trasmessa.

Argomenti

chiavi
Sequenza di tasti
**ctx_options
Opzioni di contesto

Restituisce un elenco di oggetti Future. Il risultato di ogni futuro è un'istanza di Model o None se la chiave non è stata trovata.

ndb.in_transaction()
Restituisce un valore booleano che indica se una transazione è attualmente attiva.
@ndb.non_transactional
@ndb.non_transactional(allow_existing=True)
Decorator per garantire che una funzione venga eseguita al di fuori di una transazione.

Argomenti:

allow_existing
Se True (il valore predefinito) e se la funzione decorata viene chiamata dal codice in una transazione, la funzione viene eseguita indipendentemente dalla transazione. Se False e se la funzione decorata viene chiamata dal codice in una transazione, viene generata un'eccezione.
ndb.put_multi(entities, **ctx_options)
Memorizza una sequenza di istanze Model.

Argomenti

entità
Sequenza di istanze di modello
**ctx_options
Opzioni di contesto

Restituisce un elenco con le chiavi memorizzate.

ndb.put_multi_async(entities, **ctx_options)
Archivia in modo asincrono una sequenza di istanze Model.

Argomenti

entità
Sequenza di istanze di modello
**ctx_options
Opzioni di contesto

Restituisce un elenco di oggetti Future. Il risultato di ogni futuro sarà una chiave memorizzata.

ndb.transaction(callback, **ctx_options)
Esegui un callback in una transazione.

Argomenti

callback
Funzione o tasklet da chiamare
**ctx_options
Opzioni di transazione

Restituisce ciò che restituisce callback. Genera qualsiasi callback generato o un'eccezione TransactionFailedError se la transazione non va a buon fine.

Per passare argomenti a una funzione di callback, utilizza una funzione lambda. Ad esempio, 

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
ndb.transaction_async(callback, **ctx_options)
Esegui in modo asincrono un callback in una transazione.

Argomenti

callback
Funzione o tasklet da chiamare
**ctx_options
Opzioni di transazione

Restituisce un Future. Il futuro restituisce ciò che restituisce il callback o genera ciò che genera il callback o un TransactionFailedError se la transazione non va a buon fine.

Per passare argomenti a una funzione di callback, utilizza una funzione lambda. Ad esempio, 

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))
@ndb.transactional
@ndb.transactional(**ctx_options)
Decorator per eseguire automaticamente una funzione in una transazione.

Argomenti:

Questo decoratore può avere opzioni di transazione.

Opzioni di contesto, Opzioni transazione

Le opzioni di contesto ti consentono di eseguire operazioni specifiche del datastore con configurazioni diverse. Ad esempio, potresti voler variare la norma di lettura o il termine RPC per le singole richieste. Puoi farlo passando le opzioni di contesto a quasi tutte le operazioni. Alcune funzioni correlate alle transazioni accettano opzioni di transazione, che includono opzioni aggiuntive oltre a un insieme di opzioni di contesto.

Ecco alcuni esempi che utilizzano le opzioni di contesto. Per impostare il termine RPC su 1 secondo durante la lettura di un'entità, puoi utilizzare: 

key.get(deadline=1)

Per impostare il timeout di memcache su 30 secondi durante la scrittura di un'entità, puoi utilizzare: 

ent.put(ndb_memcache_timeout=30)

Per eliminare un elemento memorizzato nella cache e forzarne il ricaricamento, puoi utilizzare: 

key.delete(use_datastore=False)

Gli argomenti speciali delle parole chiave options e config (che hanno significati identici per motivi storici) consentono di specificare diverse opzioni come oggetto di configurazione. Può trattarsi di un oggetto ndb.ContextOptions o (per le funzioni transazionali e il decoratore) di un oggetto ndb.TransactionOptions. Ad esempio, key.get(options=ndb.ContextOptions(use_cache=True)) è equivalente a key.get(use_cache=True). Le opzioni impostate in un oggetto di questo tipo possono essere sostituite dai parametri delle parole chiave.

Sono disponibili le seguenti opzioni contestuali:

Opzione Tipo Descrizione
deadline float Scadenza chiamata datastore, specificata come numero di secondi. (Per impostazione predefinita, la chiamata viene interrotta solo dalla scadenza del gestore delle richieste.)
read_policy ndb.EVENTUAL_CONSISTENCY Imposta questo valore su ndb.EVENTUAL_CONSISTENCY se, anziché attendere che Datastore finisca di applicare le modifiche a tutti i risultati restituiti, vuoi ottenere risultati potenzialmente non aggiornati più rapidamente.
force_writes bool Specifica se una richiesta di scrittura deve andare a buon fine anche se l'app è di sola lettura. Ciò vale solo per i periodi di sola lettura controllati dall'utente.
use_cache bool Specifica se archiviare le entità nella cache in-process; esegue l'override della policy della cache in-process per questa operazione.
use_memcache bool Specifica se archiviare le entità in memcache; sostituisce il criterio memcache per questa operazione.
use_datastore bool Specifica se archiviare le entità in Datastore; esegue l'override del criterio Datastore per questa operazione.
memcache_timeout int Durata massima delle entità in memcache; sostituisce il criterio di timeout di memcache per questa operazione.
max_memcache_items int Dimensione massima del batch per la funzionalità di batch automatico dei metodi memcache Context. Ad esempio, con la dimensione predefinita di max_memcache_items (100), fino a 100 operazioni di impostazione di memcache verranno combinate in una singola operazione set_multi.

Per alcune funzioni correlate alle transazioni, sono disponibili le seguenti opzioni di transazione (insieme alle opzioni di contesto ereditate elencate sopra):

Opzione Tipo Descrizione
xg bool Consenti transazioni tra gruppi (XG). False per impostazione predefinita.
propagation int

NDB fornisce un supporto limitato per le transazioni all'interno delle transazioni, che sono note come "transazioni nidificate".

Il parametro di propagazione controlla cosa succede se il codice tenta di avviare una transazione nidificata.

Il criterio di propagazione per @ndb.transactional è impostato su ALLOWED per impostazione predefinita.

Il criterio di propagazione per ndb.transaction() è impostato su NESTED per impostazione predefinita. La policy NESTED non è supportata da NDB, quindi il codice genererà un'eccezione BadRequestError. NDB imposta un valore predefinito non supportato, in questo caso, in modo che i programmatori siano esplicitamente consapevoli dei limiti delle transazioni nidificate.

Il parametro di propagazione può avere uno dei seguenti valori:

ndb.TransactionOptions.NESTED
Il criterio di propagazione NESTED eseguirà il commit di tutte le modifiche nelle transazioni esterne e interne insieme quando viene eseguito il commit del criterio esterno. Tuttavia, se viene generata un'eccezione nella transazione interna, tutte le modifiche apportate verranno eliminate, ma la transazione esterna potrà facoltativamente essere recuperata e continuare. La norma NESTED non è supportata. Se utilizzi questo criterio, il codice genererà un'eccezione BadRequestError.
ndb.TransactionOptions.MANDATORY
Propaga sempre una transazione esistente; genera un'eccezione se non esiste alcuna transazione. Se una funzione che utilizza questo criterio genera un'eccezione, probabilmente non è sicuro intercettare l'eccezione ed eseguire il commit della transazione esterna; la funzione potrebbe aver lasciato la transazione esterna in uno stato errato.
ndb.TransactionOptions.ALLOWED
Se esiste una transazione, propagala. Se una funzione che utilizza questo criterio genera un'eccezione, probabilmente non è sicuro intercettare l'eccezione ed eseguire il commit della transazione esterna; la funzione potrebbe aver lasciato la transazione esterna in uno stato errato.
ndb.TransactionOptions.INDEPENDENT
Utilizza sempre una nuova transazione, "mettendo in pausa" le transazioni esistenti. Una funzione che utilizza questo criterio non deve restituire entità lette nella nuova transazione, in quanto le entità non sono coerenti a livello transazionale con la transazione del chiamante.
retries int Numero di tentativi automatici in caso di errori di transazione. Zero significa provare una volta, ma non riprovare.

In alcuni casi, le opzioni vengono ignorate a causa della memorizzazione nella cache. Ad esempio, se specifichi una scadenza RPC per un'operazione di lettura soddisfatta dalla cache in contesto, la scadenza viene ignorata. D'altra parte, le opzioni non riconosciute causano l'aumento di TypeError.

Le operazioni con opzioni diverse vengono raggruppate quando viene applicato il batch automatico. Ad esempio, se utilizzi put_async() per scrivere alcune entità con deadline = 5 e alcune senza specificare una scadenza e tutte sono idonee per il batch automatico, il batch automatico effettuerà due chiamate RPC separate: una per il gruppo di entità con deadline = 5 e una per l'altro gruppo, anche se la scadenza RPC predefinita è 5. Ciò vale anche se l'opzione specificata non è pertinente all'operazione RPC (ad esempio, ndb_should_cache).