Fonctions NDB

Fonctions

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 est une instance de la classe Model ou None si la clé n'a pas été trouvée.

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 est une instance de la classe Model ou None si la clé n'a pas été trouvée.

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
Si la valeur est True (valeur par défaut) et si la fonction décorée est appelée par du code dans une transaction, la fonction est exécutée indépendamment de la transaction. Si la valeur est False et si la fonction décorée est appelée par du code dans une transaction, une exception est déclenchée.
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

rappel
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

rappel
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 au jeu 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 Configuration. Cela peut être un objet ndb.ContextOptions ou (pour les fonctions liées aux transactions et les décorateurs) un objet ndb.TransactionOptions. Par exemple, key.get(options=ndb.ContextOptions(use_cache=True)) est équivalent à 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 cette valeur sur ndb.EVENTUAL_CONSISTENCY si, au lieu d'attendre que le datastore ait fini d'appliquer les modifications à tous les résultats renvoyés, vous souhaitez obtenir plus rapidement des résultats qui ne sont pas nécessairement à jour.
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), vous pouvez combiner jusqu'à 100 opérations Memcache par lots 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). Par défaut, False.
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 compatible avec NDB, votre code renverra 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 externe et interne 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 renverra 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 -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é. D'autre part, des options non reconnues provoquent le déclenchement 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 d'autres sans spécifier de délai, et si toutes ces opérations sont éligibles à la mise en lots automatique, le gestionnaire de mise en lots effectuera deux appels RPC distincts, un pour le groupe d'entités ayant pour délai deadline = 5 et un pour l'autre groupe, même si le délai RPC par défaut a également pour valeur 5 ! Ce fonctionnement s'applique même si l'option spécifiée n'a aucune importance pour l'opération RPC (par exemple, ndb_should_cache).

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Environnement standard App Engine pour Python 2