Classe Model

Remarque : Les développeurs qui créent des applications sont vivement encouragés à utiliser la bibliothèque cliente NDB, qui présente plusieurs avantages par rapport à la bibliothèque cliente DB, tels que la mise en cache automatique des entités via l'API Memcache. Si vous utilisez actuellement l'ancienne bibliothèque cliente DB, consultez le guide de migration de la bibliothèque cliente DB vers NDB.

La classe Model est la super-classe des définitions de modèles de données.

Cette classe Model est définie dans le module google.appengine.ext.db.

Présentation

Pour définir un modèle de données, une application définit une classe dérivée de la classe Model. Les propriétés du modèle sont définies à l'aide d'attributs de classe et d'instances de classe Property. Exemple :

class Story(db.Model):
  title = db.StringProperty()
  body = db.TextProperty()
  created = db.DateTimeProperty(auto_now_add=True)

Une application crée une entité de données en instanciant une sous-classe de la classe Model. Vous pouvez affecter des propriétés à une entité en utilisant des attributs de l'instance, ou sous forme d'arguments de mot clé pour le constructeur.

s = Story()
s.title = "The Three Little Pigs"

s = Story(title="The Three Little Pigs")

Le nom de la sous-classe est utilisé comme nom de genre de l'entité Datastore. Le datastore réserve tous les noms de genres commençant par deux traits de soulignement (__). Les sous-classes de modèle ne doivent pas utiliser ce type de nom.

Les noms des attributs sont utilisés comme noms des propriétés correspondantes d'une entité. Les attributs de l'instance de modèle dont les noms commencent par un trait de soulignement (_) ne sont pas pris en compte. Par conséquent, votre application peut les exploiter pour stocker des données dans une instance de modèle qui n'est pas enregistrée dans le datastore.

Le datastore et l'API de la classe Model imposent plusieurs restrictions pour les noms de propriétés et les attributs d'instance de modèle. Consultez la section Noms de propriétés non autorisés pour en savoir plus.

Chaque entité possède une clé, qui est un identifiant unique la représentant. La clé peut inclure un nom de clé facultatif, constituant une chaîne unique parmi les entités du genre donné. Vous pouvez spécifier le genre et le nom de la clé dans les méthodes Key.from_path() et Model.get_by_key_name() pour récupérer l'entité.

Une entité peut également posséder une entité parente facultative. Les relations parent-enfant forment des groupes d'entités, qui permettent de contrôler la transactionnalité et la localisation des données dans le datastore. Une application crée une relation parent-enfant entre deux entités en transmettant l'entité parente au constructeur de l'entité enfant, en tant qu'argument parent.

La méthode Model.get_or_insert() permet de récupérer une entité qui peut ne pas exister, en la créant si nécessaire dans le datastore :

keyname = "some_key"
s = Story.get_or_insert(keyname, title="The Three Little Pigs")

Remarque : Une instance de modèle ne possède pas d'entité correspondante dans le datastore avant d'être écrite pour la première fois (à l'aide de la méthode put), que ce soit explicitement ou via la méthode Model.get_or_insert().

Pour créer un objet dict, qui est une copie des données d'une instance de modèle, utilisez la fonction db.to_dict.

Constructeur

Le constructeur de la classe Model est défini comme suit :

class Model (parent=None, key_name=None, **kwds)

Superclasse des définitions de modèles de données.

Lors de la construction, la méthode validate() de chaque propriété est appelée. Les exceptions de ces appels se propagent aux appelants du constructeur.

Arguments

parent
Instance de modèle ou instance Key de l'entité parente de la nouvelle entité.
key_name

Nom de clé de l'entité. Le nom fait partie de la clé primaire. Si la valeur est None, un ID généré par le système est employé pour la clé.

La valeur de key_name ne doit pas être au format __*__.

Le nom de clé est stocké en tant que chaîne Unicode, avec les valeurs str converties en texte ASCII.

L'appel de la méthode put() sur cet objet écrase toute entité Datastore existante possédant la même clé.

kwds
Valeurs initiales des propriétés de l'instance, sous forme d'arguments de mot clé. Chaque nom correspond à un attribut défini sur la classe Model.

Argument de mot clé supplémentaire

key

Instance Key explicite pour l'entité. Cet argument ne peut pas être utilisé avec key_name ou parent. Si la valeur None est spécifiée, le comportement défini dans key_name et parent est appliqué. Cet argument s'avère utile lorsque vous réservez des ID numériques pour de nouvelles identités à l'aide de allocate_ids().

La valeur de key doit être une instance Key valide.

L'appel de la méthode put() sur cet objet écrase toute entité Datastore existante possédant la même clé.

Méthodes des classes

La classe Model dispose des méthodes de classe suivantes :

Model.get (keys)

Récupère la ou les instances de modèle associées aux clés fournies. Les clés doivent représenter des entités correspondant au genre du modèle. Si une clé fournie ne possède pas le genre approprié, une exception KindError est générée.

Cette méthode est comparable à la fonction db.get(), avec une vérification de type supplémentaire.

Arguments

keys
Objet Key de l'entité à récupérer, représentation de la clé sous forme de chaîne, ou liste de clés ou de leurs représentations sous forme de chaîne.
read_policy
Règles de lecture indiquant le niveau de cohérence des données souhaité :
STRONG_CONSISTENCY
Garantit l'obtention des résultats les plus récents, mais se limite à un seul groupe d'entités.
EVENTUAL_CONSISTENCY
Peut s'étendre à plusieurs groupes d'entités, mais peut parfois renvoyer des résultats obsolètes. En général, les requêtes cohérentes à terme s'exécutent plus rapidement que les requêtes à cohérence forte, mais cela n'est pas garanti.

Remarque : Les requêtes globales (non ascendantes) ignorent cet argument.

deadline
Délai d'attente maximal exprimé en secondes au terme duquel Datastore renvoie un résultat avant d'abandonner en signalant une erreur. Accepte un entier ou une valeur à virgule flottante. Ne doit pas être défini sur une valeur supérieure à la valeur par défaut (60 secondes). Toutefois, il est possible de définir une durée plus courte pour garantir qu'une opération particulière échoue rapidement (par exemple, pour renvoyer une réponse plus rapide à l'utilisateur, retenter une opération, lancer une autre opération ou ajouter l'opération à une file d'attente).

Si l'argument keys consiste en une seule clé (ou sa représentation sous forme de chaîne), cette méthode renvoie l'instance de modèle associée à la clé si la clé existe dans le datastore. Sinon, elle renvoie None. Si keys est une liste, la valeur renvoyée est une liste correspondante d'instances de modèle, et la valeur None s'affiche lorsqu'aucune entité n'existe pour une clé donnée.

Consultez également la section relative à fonction db.get().

Model.get_by_id (ids, parent=None)

Récupère la ou les instances de modèle associées aux ID numériques fournis.

Arguments

ids
ID d'entité numérique ou liste d'ID numériques.
parent
Entité parente des entités demandées. Il s'agit d'un modèle, d'une clé, ou de None (par défaut) si les entités demandées n'ont pas de parent. Si plusieurs entités sont demandées par un même appel, elles doivent toutes avoir le même parent.
read_policy
Règles de lecture indiquant le niveau de cohérence des données souhaité :
STRONG_CONSISTENCY
Garantit l'obtention des résultats les plus récents, mais se limite à un seul groupe d'entités.
EVENTUAL_CONSISTENCY
Peut s'étendre à plusieurs groupes d'entités, mais peut parfois renvoyer des résultats obsolètes. En général, les requêtes cohérentes à terme s'exécutent plus rapidement que les requêtes à cohérence forte, mais cela n'est pas garanti.

Remarque : Les requêtes globales (non ascendantes) ignorent cet argument.

deadline
Délai d'attente maximal exprimé en secondes au terme duquel Datastore renvoie un résultat avant d'abandonner en signalant une erreur. Accepte un entier ou une valeur à virgule flottante. Ne doit pas être défini sur une valeur supérieure à la valeur par défaut (60 secondes). Toutefois, il est possible de définir une durée plus courte pour garantir qu'une opération particulière échoue rapidement (par exemple, pour renvoyer une réponse plus rapide à l'utilisateur, retenter une opération, lancer une autre opération ou ajouter l'opération à une file d'attente).

Si l'argument ids consiste en un seul ID numérique, cette méthode renvoie l'instance de modèle associée à l'ID si celui-ci existe dans le datastore. Sinon, elle renvoie None. Si ids est une liste, la valeur renvoyée est une liste correspondante d'instances de modèle, et la valeur None s'affiche lorsqu'aucune entité n'existe pour un ID numérique donné.

Model.get_by_key_name (key_names, parent=None)

Récupère la ou les instances de modèle associées aux noms de clé fournis.

Arguments

key_names
Nom de clé, ou liste de noms de clé
parent
Entité parente des entités demandées. Il s'agit d'une instance de modèle, d'une clé, ou de None (par défaut) si les entités demandées n'ont pas de parent. Si plusieurs entités sont demandées par un même appel, elles doivent toutes avoir le même parent.
read_policy
Règles de lecture indiquant le niveau de cohérence des données souhaité :
STRONG_CONSISTENCY
Garantit l'obtention des résultats les plus récents, mais se limite à un seul groupe d'entités.
EVENTUAL_CONSISTENCY
Peut s'étendre à plusieurs groupes d'entités, mais peut parfois renvoyer des résultats obsolètes. En général, les requêtes cohérentes à terme s'exécutent plus rapidement que les requêtes à cohérence forte, mais cela n'est pas garanti.

Remarque : Les requêtes globales (non ascendantes) ignorent cet argument.

deadline
Délai d'attente maximal exprimé en secondes au terme duquel Datastore renvoie un résultat avant d'abandonner en signalant une erreur. Accepte un entier ou une valeur à virgule flottante. Ne doit pas être défini sur une valeur supérieure à la valeur par défaut (60 secondes). Toutefois, il est possible de définir une durée plus courte pour garantir qu'une opération particulière échoue rapidement (par exemple, pour renvoyer une réponse plus rapide à l'utilisateur, retenter une opération, lancer une autre opération ou ajouter l'opération à une file d'attente).

Si l'argument key_names consiste en un seul nom de clé, cette méthode renvoie l'instance de modèle associée au nom si celui-ci existe dans le datastore. Sinon, elle renvoie None. Si key_names est une liste, la valeur renvoyée est une liste correspondante d'instances de modèle, et la valeur None s'affiche lorsqu'aucune entité n'existe pour un nom de clé donné.

Model.get_or_insert (key_name, **kwds)

Tente d'obtenir l'entité appartenant au genre du modèle et possédant le nom de clé fourni. Si l'entité existe, la méthode get_or_insert() la renvoie. Si elle n'existe pas, une nouvelle entité possédant le genre, le nom et les paramètres fournis dans kwds est créée, stockée et renvoyée.

Les opérations "get" et les éventuelles commandes "put" qui suivent sont encapsulées dans une transaction afin de garantir l'atomicité. Cela signifie que la méthode get_or_insert() n'écrasera jamais une entité existante et n'insérera une nouvelle entité que si aucune entité ne possède le nom et le genre fournis. En d'autres termes, la méthode get_or_insert() est équivalente au code Python suivant :

def txn(key_name, **kwds):
  entity = Story.get_by_key_name(key_name, parent=kwds.get('parent'))
  if entity is None:
    entity = Story(key_name=key_name, **kwds)
    entity.put()
  return entity

def get_or_insert(key_name, **kwargs):
  return db.run_in_transaction(txn, key_name, **kwargs)

get_or_insert('some key', title="The Three Little Pigs")

Arguments

key_name
Nom de la clé de l'entité
kwds
Arguments de mot clé à transmettre au constructeur de la classe Model si aucune instance ne porte le nom de clé indiqué. L'argument parent est obligatoire si l'entité souhaitée a un parent.

Remarque : La méthode get_or_insert() n'accepte pas les arguments read_policy et deadline.

La méthode renvoie une instance de la classe Model qui représente l'entité demandée, que cette entité ait existé au préalable ou qu'elle ait été créée par la méthode. Comme pour toutes les opérations Datastore, cette méthode peut générer une erreur TransactionFailedError si la transaction n'a pas pu être exécutée.

Model.all (keys_only=False)

Renvoie un objet Query qui représente toutes les entités possédant le même genre que ce modèle. Les méthodes utilisées sur l'objet de requête peuvent appliquer des filtres et des ordres de tri à la requête avant son exécution. Consultez la page relative à la classe Query pour en savoir plus.

Arguments

keys_only
Indique si la requête doit renvoyer des entités complètes ou seulement des clés. Les requêtes qui renvoient des clés sont plus rapides et utilisent moins de temps CPU que celles renvoyant des entités complètes.
Model.gql (query_string, *args, **kwds)

Effectue une requête GQL sur les instances de ce modèle.

Arguments

query_string
Partie de la requête GQL suivant SELECT * FROM model (qui est implicite lorsque vous utilisez cette méthode de classe).
args
Liaisons de paramètres positionnels. Cet argument est semblable au constructeur GqlQuery().
kwds
Liaisons de paramètres de mot clé. Cet argument est semblable au constructeur GqlQuery().
s = Story.gql("WHERE title = :1", "Little Red Riding Hood")

s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")

La valeur renvoyée est un objet GqlQuery, qui permet d'accéder aux résultats.

Model.kind ()
Renvoie le genre du modèle, habituellement le nom de la sous-classe Model.
Model.properties ()
Renvoie un dictionnaire de l'ensemble des propriétés définies pour cette classe Model.

Méthodes des instances

Les méthodes des instances de la classe Model sont les suivantes :

key ()

Renvoie l'objet Key Datastore pour cette instance de modèle.

La clé d'une instance de modèle inclut le genre d'entité de l'instance ainsi qu'un identifiant unique. L'identifiant peut correspondre à une chaîne de nom de clé, attribuée explicitement par l'application lors de la création de l'instance, ou à un ID numérique entier, attribué automatiquement par App Engine lorsque l'instance est écrite (à l'aide de la méthode put) dans le datastore. Si la méthode key() est appelée avant l'attribution d'un identifiant par l'instance, une exception NotSavedError est générée.

put ()

Stocke l'instance de modèle dans le datastore. Si l'instance vient d'être créée et n'a jamais été stockée, cette méthode crée une entité de données dans le datastore. Sinon, elle met à jour l'entité de données avec les valeurs de propriétés actuelles.

La méthode renvoie la clé de l'entité stockée.

Si les données n'ont pas pu être validées, une exception TransactionFailedError est générée.

Arguments

deadline
Délai d'attente maximal exprimé en secondes au terme duquel Datastore renvoie un résultat avant d'abandonner en signalant une erreur. Accepte un entier ou une valeur à virgule flottante. Ne doit pas être défini sur une valeur supérieure à la valeur par défaut (60 secondes). Toutefois, il est possible de définir une durée plus courte pour garantir qu'une opération particulière échoue rapidement (par exemple, pour renvoyer une réponse plus rapide à l'utilisateur, retenter une opération, lancer une autre opération ou ajouter l'opération à une file d'attente).
delete ()

Supprime l'instance de modèle du datastore. Si l'instance n'a jamais été écrite (à l'aide de la méthode put) dans le datastore, la suppression génère une exception NotSavedError.

Arguments

deadline
Délai d'attente maximal exprimé en secondes au terme duquel Datastore renvoie un résultat avant d'abandonner en signalant une erreur. Accepte un entier ou une valeur à virgule flottante. Ne doit pas être défini sur une valeur supérieure à la valeur par défaut (60 secondes). Toutefois, il est possible de définir une durée plus courte pour garantir qu'une opération particulière échoue rapidement (par exemple, pour renvoyer une réponse plus rapide à l'utilisateur, retenter une opération, lancer une autre opération ou ajouter l'opération à une file d'attente).
is_saved ()

Renvoie True si l'instance de modèle a été écrite (à l'aide de la méthode put) dans le datastore au moins une fois.

Cette méthode vérifie uniquement que l'instance a été écrite dans le datastore au moins une fois depuis sa création. Elle ne vérifie pas si les propriétés de l'instance ont été mises à jour depuis sa dernière écriture.

dynamic_properties ()

Renvoie la liste des noms de toutes les propriétés dynamiques définies pour cette instance de modèle. Cette méthode ne s'applique qu'aux instances de classe Expando. Pour les instances de modèle non Expando, la méthode renvoie une liste vide.

parent ()

Renvoie une instance de modèle associée à l'entité parente de cette instance. Renvoie None si l'instance n'a pas de parent.

parent_key ()

Renvoie l'objet Key de l'entité parente de cette instance ou None si celle-ci n'a pas de parent.

to_xml ()

Renvoie une représentation XML de l'instance de modèle.

Les valeurs de propriété sont conformes aux spécifications d'Atom et de Data.

Noms de propriétés non autorisés

Le datastore et son API imposent plusieurs restrictions sur les noms des propriétés d'entité et des attributs d'instances de modèle.

Le datastore réserve tous les noms de propriétés commençant et terminant par deux traits de soulignement (__*__). Une entité Datastore ne peut pas comporter de propriété ayant ce format de nom.

L'API du modèle Python ignore tous les attributs des classes Model et Expando qui commencent par un trait de soulignement (_). Votre application peut exploiter ces attributs pour associer des données aux objets de modèle qui ne sont pas enregistrés dans le datastore.

Enfin, l'API du modèle Python utilise des attributs d'objet pour définir les propriétés d'un modèle, et les propriétés des entités Datastore prennent par défaut les noms de ces attributs. Comme la classe Model dispose de plusieurs propriétés et méthodes destinées à d'autres fins, ces attributs ne peuvent pas être utilisés pour les propriétés de l'API Python. Par exemple, il n'est pas possible d'accéder à une propriété de la classe Model à l'aide de l'attribut key.

Toutefois, vous pouvez indiquer au datastore un nom différent du nom de l'attribut en transmettant un argument name au constructeur de la propriété. Ainsi, l'entité Datastore peut posséder un nom de propriété semblable à celui d'un attribut réservé dans la classe Model et utiliser un nom d'attribut différent dans la classe.

class MyModel(db.Model):
  obj_key = db.StringProperty(name="key")

Les noms d'attribut suivants sont réservés par la classe Model dans l'API Python :

  • all
  • app
  • copy
  • delete
  • entity
  • entity_type
  • fields
  • from_entity
  • get
  • gql
  • instance_properties
  • is_saved
  • key
  • key_name
  • kind
  • parent
  • parent_key
  • properties
  • put
  • setdefault
  • to_xml
  • update
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Environnement standard App Engine pour Python 2