Nota: Python 2.7 ha raggiunto la fine del supporto il 31 gennaio 2024. Le applicazioni Python 2.7 esistenti continueranno a essere eseguite e a ricevere traffico. Tuttavia, App Engine potrebbe bloccare il ri deployment di applicazioni che utilizzano runtime dopo la data di fine del supporto. Ti consigliamo di eseguire la migrazione all'ultima versione supportata di Python.

Funzioni NDB

Funzioni

ndb.add_flow_exception(exc)

Specifica che un'eccezione non deve essere registrata, ma fa solo parte del normale flusso del programma. In genere, la generazione di un'eccezione comporta la scrittura di 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 relative sottoclassi)
ndb.Rollback

ndb.delete_multi(chiavi, **ctx_options)

Elimina le entità identificate dalla sequenza di chiavi trasmessa.

Argomenti

chiavi: Sequenza di chiavi
**ctx_options: Opzioni di contesto

ndb.delete_multi_async(keys, **ctx_options)

Elimina in modo asincrono le entità identificate dalla sequenza di chiavi trasmessa.

Argomenti

chiavi: Sequenza di chiavi
**ctx_options: Opzioni di contesto

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

ndb.get_multi(chiavi, **ctx_options)

Recupera le entità identificate dalla sequenza passata di chiavi.

Argomenti

chiavi: Sequenza di chiavi
**ctx_options: Opzioni di contesto

Restituisce un elenco. Ogni elemento dell'elenco è un'istanza 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 passata.

Argomenti

chiavi: Sequenza di chiavi
**ctx_options: Opzioni di contesto

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

ndb.in_transaction()

Restituisci un valore booleano che indica se una transazione è attualmente attiva.

@ndb.non_transactional @ndb.non_transactional

Decoratore per assicurare che una funzione venga eseguita all'esterno di una transazione.

Argomenti:

allow_existing: Se True (valore predefinito) e se la funzione decorata viene chiamata dal codice in una transazione, la funzione viene eseguita indipendentemente dalla transazione. Se False e la funzione decorata viene chiamata dal codice in una transazione, genera un'eccezione.

ndb.put_multi(entità, **ctx_options)

Archivia una sequenza di istanze Modello.

Argomenti

entità: Sequenza di istanze Model
**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 Model
**ctx_options: Opzioni di contesto

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

ndb.transaction(callback, **ctx_options)

Eseguire un callback in una transazione.

Argomenti

richiamata: Funzione o tasklet da chiamare
**ctx_options: Opzioni per le transazioni

Restituisce i valori restituiti dal callback. Aumenta qualsiasi elemento di callback generato o un'eccezione TransactionFailedError se la transazione non va a buon fine.

Per passare gli 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

richiamata: Funzione o tasklet da chiamare
**ctx_options: Opzioni di transazione

Restituisce un valore Future. Il futuro restituisce qualsiasi valore di callback restituito oppure aumenta qualsiasi elemento di callback generato o un valore TransactionFailedError se la transazione non va a buon fine.

Per passare gli 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

Decoratore per eseguire automaticamente una funzione in una transazione.

Argomenti:

Questo decorator può disporre di opzioni per le transazioni.

Opzioni di contesto, opzioni di transazione

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

Ecco alcuni esempi di utilizzo delle opzioni di contesto. Per impostare la scadenza RPC su 1 secondo durante la lettura di un'entità, puoi utilizzare:

key.get(deadline=1)

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

ent.put(ndb_memcache_timeout=30)

Per eliminare un elemento che è stato 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ò essere un oggetto ndb.ContextOptions o (per le funzioni transazionali e il decorator) 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 opzioni possono essere sostituite dai parametri delle parole chiave.

Sono disponibili le seguenti opzioni di contesto:

Opzione	Tipo	Descrizione
`deadline`	`float`	Scadenza della chiamata Datastore, specificata con un numero di secondi. Per impostazione predefinita, la chiamata viene interrotta solo in base alla scadenza prevista per il gestore delle richieste.
`read_policy`	`ndb.EVENTUAL_CONSISTENCY`	Imposta questo valore su `ndb.EVENTUAL_CONSISTENCY` se, invece di attendere che Datastore completi l'applicazione delle modifiche a tutti i risultati restituiti, vuoi ottenere più velocemente risultati potenzialmente non attuali.
`force_writes`	`bool`	Specifica se una richiesta di scrittura deve andare a buon fine anche se l'app è di sola lettura. Questo vale solo per i periodi di sola lettura controllati dall'utente.
`use_cache`	`bool`	Specifica se archiviare le entità nella cache in-process; sostituisce il criterio della cache in-process per questa operazione.
`use_memcache`	`bool`	Specifica se archiviare le entità in memcache; sostituisce i criteri memcache per questa operazione.
`use_datastore`	`bool`	Specifica se archiviare le entità in Datastore; sostituisce il criterio Datastore per questa operazione.
`memcache_timeout`	`int`	Durata massima per le entità in memcache; sostituisce il criterio di timeout memcache per questa operazione.
`max_memcache_items`	`int`	Dimensione massima del batch per la funzionalità di batch automatico dei metodi memcache di Contesto. Ad esempio, con la dimensione predefinita di `max_memcache_items` (100), fino a 100 operazioni di set memcache verranno combinate in una singola operazione `set_multi`.
Per alcune funzioni relative alle transazioni, sono disponibili le seguenti opzioni di transazione (oltre 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, 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 in modo predefinito su `ALLOWED`. Il criterio di propagazione per `ndb.transaction()` è impostato in modo predefinito su `NESTED`. Il criterio `NESTED` non è supportato da NDB, quindi il tuo codice genererà un'eccezione `BadRequestError`. NDB imposta un valore predefinito non supportato, in questo caso, in modo che i programmatori siano consapevoli delle limitazioni delle transazioni nidificate. Il parametro di propagazione può avere uno dei seguenti valori: `ndb.TransactionOptions.NESTED` Il criterio di propagazione `NESTED` esegue 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 verranno eliminate, ma la transazione esterna potrà eventualmente essere ripristinata e continuare. Il criterio `NESTED` non è supportato. Se utilizzi questo criterio, il codice genererà un'eccezione `BadRequestError`. `ndb.TransactionOptions.MANDATORY` Propaga sempre una transazione esistente; genera un'eccezione se non c'è alcuna transazione esistente. Se una funzione che utilizza questo criterio genera un'eccezione, probabilmente non è sicuro rilevare l'eccezione ed eseguire il commit della transazione esterna; la funzione potrebbe aver lasciato la transazione esterna in uno stato non valido. `ndb.TransactionOptions.ALLOWED` Se esiste già una transazione, propagala. Se una funzione che utilizza questo criterio genera un'eccezione, probabilmente non è sicuro rilevare l'eccezione ed eseguire il commit della transazione esterna; la funzione potrebbe aver lasciato la transazione esterna in uno stato non valido. `ndb.TransactionOptions.INDEPENDENT` Utilizza sempre una nuova transazione, "mettendo in pausa" quelle esistenti. Una funzione che utilizza questo criterio non dovrebbe restituire alcuna entità letta nella nuova transazione, poiché le entità non sono coerenti dal punto di vista transazionale con la transazione del chiamante.
`retries`	`int`	Numero di tentativi automatici in caso di errori della transazione. Zero mezzi per fare una prova, 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 nel contesto, la scadenza viene ignorata. Se invece non vengono riconosciute, le opzioni non riconosciute comportano l'attivazione di TypeError.

Le operazioni con opzioni diverse vengono raggruppate insieme quando si applica il batch automatico. Ad esempio, se utilizzi put_async() per scrivere alcune entità con deadline = 5 e altre senza specificare una scadenza e tutte sono idonee per il batch automatico, il batcher 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 predefinita è 5. Ciò si applica anche se l'opzione specificata non è pertinente all'operazione RPC (ad esempio ndb_should_cache).