Remarque : Python 2.7 n'est plus compatible à partir du 31 janvier 2024. Vos applications Python 2.7 existantes continueront à fonctionner et à recevoir du trafic. Toutefois, App Engine peut bloquer le redéploiement des applications qui utilisent des environnements d'exécution après leur date de fin de compatibilité. Nous vous recommandons de migrer vers la dernière version compatible de Python.

Fonctions NDB

Functions

ndb.add_flow_exception(exc)

Permet de spécifier si une exception ne doit pas être enregistrée, mais fait simplement partie du flux normal du programme. (En temps normal, une exception génère un message d'avertissement dans les journaux de l'application.)

Arguments

exc

Classe d'exception qui ne doit pas être enregistrée dans les journaux.

Par défaut, les exceptions suivantes ne sont pas consignées :

webob.exc.HTTPException (et ses sous-classes)
ndb.Rollback

ndb.delete_multi(keys, **ctx_options)

Supprime les entités identifiées par la séquence de clés transmise.

Arguments

keys: Séquence de clés
**ctx_options: Options de contexte

ndb.delete_multi_async(keys, **ctx_options)

Supprime de manière asynchrone les entités identifiées par la séquence de clés transmise.

Arguments

keys: Séquence de clés
**ctx_options: Options de contexte

Renvoie une liste d'objets Future. Le résultat de chaque objet Future sera None.

ndb.get_multi(keys, **ctx_options)

Récupère les entités identifiées par la séquence de clés transmise.

Arguments

keys: Séquence de clés
**ctx_options: Options de contexte

Renvoie une liste. Chaque élément de la liste correspond à une instance de la classe Model ou à None si la clé est introuvable.

ndb.get_multi_async(keys, **ctx_options)

Récupère de manière asynchrone les entités identifiées par la séquence de clés transmise.

Arguments

keys: Séquence de clés
**ctx_options: Options de contexte

Renvoie une liste d'objets Future. Le résultat de chaque objet Future correspond à une instance de la classe Model ou à None si la clé est introuvable.

ndb.in_transaction()

Renvoie une valeur booléenne indiquant si une transaction est actuellement active.

@ndb.non_transactional @ndb.non_transactional(allow_existing=True)

Décorateur qui veille à ce qu'une fonction s'exécute en dehors d'une transaction.

Arguments :

allow_existing: La fonction s'exécute indépendamment de la transaction si elle est définie sur True (valeur par défaut) et si la fonction décorée est appelée par le code d'une transaction. Elle génère une exception si elle est définie sur False et si la fonction décorée est appelée par du code dans une transaction.

ndb.put_multi(entities, **ctx_options)

Stocke une séquence d'instances de la classe Model.

Arguments

entities: Séquence d'instances de la classe Model
**ctx_options: Options de contexte

Renvoie une liste correspondant aux clés stockées.

ndb.put_multi_async(entities, **ctx_options)

Stocke de manière asynchrone une séquence d'instances de la classe Model.

Arguments

entities: Séquence d'instances de la classe Model
**ctx_options: Options de contexte

Renvoie une liste d'objets Future. Le résultat de chaque objet Future sera une clé stockée.

ndb.transaction(callback, **ctx_options)

Exécute un rappel dans une transaction.

Arguments

callback: Fonction ou tasklet à appeler
**ctx_options: Options de transaction

Renvoie tout élément renvoyé par le rappel. Déclenche tout élément déclenché par le rappel ou génère une exception TransactionFailedError en cas d'échec de la transaction.

Pour transmettre des arguments à une fonction de rappel, utilisez un lambda. Exemple :

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))

ndb.transaction_async(callback, **ctx_options)

Exécute de manière asynchrone un rappel dans une transaction.

Arguments

callback: Fonction ou tasklet à appeler
**ctx_options: Options de transaction

Renvoie un objet Future. L'objet Future renvoie tout élément renvoyé par le rappel, ou déclenche tout élément déclenché par le rappel ou une exception TransactionFailedError en cas d'échec de la transaction.

Pour transmettre des arguments à une fonction de rappel, utilisez un lambda. Exemple :

def my_callback(key, inc):
  ...

transaction(lambda: my_callback(Key(...), 1))

@ndb.transactional
@ndb.transactional(**ctx_options)

Décorateur permettant d'exécuter automatiquement une fonction dans une transaction.

Arguments :

Ce décorateur peut présenter des options de transaction.

Options de contexte, options de transaction

Les options de contexte vous permettent d'exécuter des opérations spécifiques aux datastores avec différentes configurations. Par exemple, vous pouvez modifier la stratégie de lecture ou le délai RPC pour des requêtes individuelles. Pour ce faire, vous pouvez transmettre des options de contexte à la quasi-totalité des opérations. Certaines fonctions liées aux transactions utilisent des options de transaction, qui incluent des options supplémentaires par rapport à l'ensemble d'options de contexte.

Voici quelques exemples utilisant les options de contexte. Pour définir le délai RPC à 1 seconde lors de la lecture d'une entité, vous pouvez utiliser :

key.get(deadline=1)

Pour définir le délai d'expiration de Memcache à 30 secondes lors de l'écriture d'une entité, vous pouvez utiliser :

ent.put(ndb_memcache_timeout=30)

Pour supprimer un élément mis en cache et forcer son rechargement, vous pouvez utiliser :

key.delete(use_datastore=False)

Les arguments de mots clés spéciaux options et config (qui ont des significations identiques pour des raisons historiques) permettent de spécifier plusieurs options en tant qu'objet de configuration. Il peut s'agir d'un objet ndb.ContextOptions ou (pour les fonctions transactionnelles et le décorateur) d'un objet ndb.TransactionOptions. Par exemple, key.get(options=ndb.ContextOptions(use_cache=True)) correspond à key.get(use_cache=True). Les options définies dans un tel objet options peuvent être remplacées par des paramètres de mot clé.

Les options de contexte suivantes sont disponibles :

Option	Type	Description
`deadline`	`float`	Délai d'appel du datastore, exprimé en secondes. (Par défaut, l'appel n'est interrompu que par le délai du gestionnaire de requêtes.)
`read_policy`	`ndb.EVENTUAL_CONSISTENCY`	Définissez ce paramètre sur `ndb.EVENTUAL_CONSISTENCY` si, au lieu d'attendre que le datastore termine d'appliquer les modifications à tous les résultats renvoyés, vous souhaitez obtenir plus rapidement des résultats qui ne sont pas actuels.
`force_writes`	`bool`	Spécifie si une requête d'écriture doit réussir même si l'application est en lecture seule. (Cette option ne s'applique qu'aux périodes de lecture seule contrôlées par l'utilisateur.)
`use_cache`	`bool`	Spécifie si les entités doivent être stockées dans le cache en cours de traitement. Prend le pas sur la stratégie de mise en cache en cours de traitement pour cette opération.
`use_memcache`	`bool`	Spécifie si les entités doivent être stockées dans Memcache. Prend le pas sur la stratégie Memcache pour cette opération.
`use_datastore`	`bool`	Spécifie si les entités doivent être stockées dans Datastore. Prend le pas sur la stratégie Datastore pour cette opération.
`memcache_timeout`	`int`	Durée de vie maximale des entités dans Memcache. Prend le pas sur la stratégie de délai d'expiration Memcache pour cette opération.
`max_memcache_items`	`int`	Taille de lot maximale pour la fonctionnalité de mise en lots automatique des méthodes de contexte de Memcache. Par exemple, avec la taille par défaut de `max_memcache_items` (100), jusqu'à 100 opérations de définition Memcache seront combinées en une seule opération `set_multi`.
Pour certaines fonctions liées aux transactions, les options de transaction suivantes sont disponibles (ainsi que les options de contexte héritées répertoriées ci-dessus) :
Option	Type	Description
`xg`	`bool`	Autorise les transactions entre groupes (`XG`). `False` par défaut.
`propagation`	`int`	NDB fournit une compatibilité limitée pour les transactions au sein de transactions, appelées "transactions imbriquées". Le paramètre de propagation contrôle ce qui se passe si votre code tente de démarrer une transaction imbriquée. La stratégie de propagation pour `@ndb.transactional` est définie par défaut sur `ALLOWED`. La stratégie de propagation pour `ndb.transaction()` est définie par défaut sur `NESTED`. La stratégie `NESTED` n'est pas prise en charge par NDB. Votre code génère donc une exception `BadRequestError`. Dans ce cas précis, NDB définit une valeur par défaut non compatible afin que les programmeurs prennent explicitement conscience des limites des transactions imbriquées. Le paramètre de propagation peut prendre l'une des valeurs suivantes : `ndb.TransactionOptions.NESTED` La stratégie de propagation `NESTED` valide toutes les modifications des transactions externes et internes lors du commit de la stratégie externe. Toutefois, si une exception est générée dans la transaction interne, toutes les modifications de cette transaction sont rejetées, tandis que la transaction externe est autorisée à éventuellement récupérer et continuer. La stratégie `NESTED` n'est pas compatible. Si vous utilisez cette stratégie, votre code génère une exception `BadRequestError`. `ndb.TransactionOptions.MANDATORY` Propage toujours une transaction existante, et renvoie une exception s'il n'y a pas de transaction existante. Si une fonction utilisant cette stratégie génère une exception, il est probablement risqué de capturer l'exception et de valider la transaction externe, car il se peut que la fonction ait laissé la transaction externe dans un état incorrect. `ndb.TransactionOptions.ALLOWED` S'il y a une transaction existante, elle est propagée. Si une fonction utilisant cette stratégie génère une exception, il est probablement risqué de capturer l'exception et de valider la transaction externe, car il se peut que la fonction ait laissé la transaction externe dans un état incorrect. `ndb.TransactionOptions.INDEPENDENT` Utilise toujours une nouvelle transaction en mettant en pause toute transaction existante. Une fonction utilisant cette stratégie ne doit renvoyer aucune entité lue dans la nouvelle transaction, car ces entités ne sont pas cohérentes, en termes de transactions, avec la transaction appelante.
`retries`	`int`	Nombre de nouvelles tentatives automatiques à effectuer en cas d'échec de la transaction. Zéro signifie essayer une fois, mais ne pas ré-essayer.

Dans certains cas, les options sont ignorées à cause de la mise en cache. Par exemple, si vous spécifiez un délai RPC pour une opération de lecture qui est satisfaite à partir du cache contextuel, ce délai est ignoré. En revanche, les options non reconnues entraînent le renvoi d'une erreur TypeError.

Les opérations ayant des options différentes sont regroupées suivant les options lors de l'application de la mise en lots automatique. Par exemple, si vous utilisez put_async() pour écrire certaines entités avec deadline = 5 et certaines entités sans spécifier de délai, et que toutes sont éligibles pour la mise en lots automatique, le système de mise en lots automatique effectuera deux appels RPC distincts, un pour le groupe d'entités avec deadline = 5 et un pour l'autre groupe, même si le délai RPC par défaut est également de 5. Cela s'applique même si l'option spécifiée n'est pas pertinente pour l'opération RPC (par exemple, ndb_should_cache).