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.

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 supplémentaires par rapport à cette bibliothèque cliente, 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 DB vers NDB.

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

La 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 Model ne doivent pas utiliser ce type de noms.

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é. Pour récupérer l'entité, vous pouvez spécifier son genre et le nom de clé avec les méthodes Key.from_path() et Model.get_by_key_name().

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

Clé ou instance de modèle 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 numérique 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é. Cela s'avère utile lorsque vous réservez des ID numériques pour de nouvelles entité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 semblable à la fonction db.get(), avec une vérification de type supplémentaire.

Arguments

keys

Classe 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 fortement cohérentes, 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 peut 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 de tâches).

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 celle-ci 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 sur la 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 ou d'une clé, ou de None (valeur 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 fortement cohérentes, mais cela n'est pas garanti.

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

deadline

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 ou d'une clé, ou de None (valeur 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 fortement cohérentes, mais cela n'est pas garanti.

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

deadline

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 elle existe, get_or_insert() la renvoie simplement. 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'écrase jamais une entité existante et n'insère 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 s'il n'existe pas d'instance portant 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. Pour en savoir plus, consultez la page Classe Query.

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 située après SELECT * FROM model (et qu'implique l'utilisation de 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 à 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 faire l'objet d'un commit, 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 peut 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 de tâches).

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 peut 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 de tâches).

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 correspondant à l'entité parente de cette instance, ou None si celle-ci n'a pas de parent.

parent_key ()

Renvoie la classe 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 finissant par deux traits de soulignement (__*__). Une entité Datastore ne peut pas inclure de propriété ayant ce format de nom.

L'API du modèle Python ignore tous les attributs des classes Model et Expando commençant 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 propriétés. 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'attributs 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