Classe Property

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 à 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 Property est la super-classe des définitions de propriétés pour les modèles de données. Une classe Property définit le type de valeur d'une propriété, le mode de validation des valeurs et leur mode de stockage dans le datastore.

La classe Property est fournie par le module google.appengine.ext.db.

Présentation

Une classe de propriété décrit le type de valeur, la valeur par défaut, la logique de validation et d'autres fonctionnalités d'une propriété d'un modèle. Chaque classe de propriété est une sous-classe de la classe Property. L'API Datastore comprend des classes de propriétés pour chacun des types de valeurs du datastore, et plusieurs autres qui fournissent des fonctionnalités supplémentaires s'ajoutant aux types du datastore. Consultez la page Types et classes de propriétés.

Une classe de propriété peut accepter la configuration à partir d'arguments transmis au constructeur. Le constructeur de classe de base prend en charge plusieurs arguments généralement acceptés dans toutes les classes de propriétés, y compris toutes celles fournies dans l'API Datastore. Cette configuration peut inclure une valeur par défaut, qu'une valeur explicite soit requise ou non, une liste de valeurs acceptables et une logique de validation personnalisée. Pour plus d'informations sur la configuration de la propriété, consultez la documentation relative à un type de propriété spécifique.

Une classe de propriété définit le modèle d'une propriété de datastore. Elle ne contient pas la valeur de la propriété pour une instance de modèle. Les instances de la classe Property appartiennent à la classe Model, et non à des instances de la classe. En langage Python, les instances d'une classe de propriété sont des "descripteurs" permettant de personnaliser le comportement des attributs des instances de modèle. Pour plus d'informations sur les descripteurs, consultez la documentation Python.

Constructeur

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

class Property(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None, indexed=True)

Super-classe des définitions de propriétés de modèle.

Arguments

verbose_name
Nom convivial de la propriété. Il doit toujours correspondre au premier argument d'un constructeur de propriété. La bibliothèque djangoforms s'en sert pour créer des libellés de champs de formulaire, et d'autres bibliothèques peuvent l'utiliser à des fins similaires.
nom
Nom de stockage de la propriété, utilisé dans les requêtes. La valeur par défaut est le nom d'attribut utilisé pour la propriété. Dans la mesure où les classes Model possèdent des attributs autres que des propriétés (qui ne sont pas utilisables pour les propriétés), une propriété peut se servir de l'argument name pour utiliser un nom d'attribut réservé comme nom de la propriété dans le datastore et un nom différent pour l'attribut de propriété. Pour en savoir plus, consultez la section Noms de propriétés interdits.
default

Valeur par défaut de la propriété. Si aucune valeur n'est jamais attribuée à la propriété, ou si celle-ci se voit attribuer la valeur None, la valeur est considérée comme la valeur par défaut.

Remarque : Les définitions de classes Model sont mises en cache avec le reste du code de l'application. Cela inclut la mise en cache des valeurs par défaut des propriétés. Ne définissez pas d'argument default (par défaut) dans la définition du modèle avec des données propres à la requête (par exemple, users.get_current_user()). À la place, définissez une méthode __init__() pour la classe Model qui initialise les valeurs de propriétés.

required

Si la valeur est True, la propriété ne peut pas comporter de valeur None. Une instance de modèle doit initialiser toutes les propriétés obligatoires dans son constructeur, pour éviter que l'instance ne soit créée avec des valeurs manquantes. Si vous tentez de créer une instance sans initialiser une propriété requise, ou si vous essayez d'attribuer la valeur None à une propriété requise, cela génère une erreur BadValueError.

Une propriété requise qui possède une valeur par défaut utilise celle-ci si aucune valeur n'est indiquée dans le constructeur. Cependant, il est impossible d'attribuer la valeur None à la propriété, et il n'y a aucun moyen de rétablir automatiquement la valeur par défaut après qu'une autre valeur a été définie. Vous pouvez toujours accéder à l'attribut default de la propriété pour obtenir cette valeur et l'attribuer explicitement.

validator
Fonction qui doit être appelée pour valider la valeur de la propriété lors de l'attribution de cette valeur. La fonction utilise la valeur comme argument unique et génère une exception si la valeur est incorrecte. Le validateur donné est appelé après l'exécution d'autres validations, comme celle consistant à vérifier qu'une propriété requise a bien une valeur. Lorsqu'aucune valeur n'est attribuée à une propriété non requise, le validateur est appelé avec l'argument None.
choices
Liste de valeurs acceptables pour la propriété. Si cette liste est définie, la propriété ne peut pas prendre une valeur qui ne figure pas dans la liste. Comme pour l'argument required et d'autres validations, une instance de modèle doit initialiser toutes les propriétés avec "choices" pour éviter que l'instance ne soit créée avec des valeurs non valides. Si le champ choices est défini sur None, toutes les valeurs qui, sinon seraient validées, sont acceptables.
indexed

Indique si cette propriété doit être incluse dans les index intégrés et définis par le développeur. Si la valeur est False, les entités écrites dans le datastore ne sont jamais renvoyées par des requêtes qui effectuent un tri ou un filtrage sur cette propriété, semblable aux propriétés Blob et Text.

Remarque : Chaque propriété indexée entraîne une légère augmentation de la surcharge, du coût du processeur, et de la latence pour les appels put() et delete(). Si vous n'avez jamais besoin d'effectuer de filtrage ou de tri sur une propriété, envisagez de définir indexed=False pour éviter cette surcharge. Soyez toutefois vigilant ! Si vous décidez ultérieurement que vous voulez tout de même indexer la propriété, le fait de la redéfinir sur indexed=True n'affectera que les écritures réalisées à partir de ce moment. Les entités écrites à l'origine avec indexed=False ne seront pas réindexées.

Attributs de classe

Les sous-classes de la classe Property définissent l'attribut de classe suivant :

data_type
Type ou classe de données Python que la propriété accepte en tant que valeur native Python.

Méthodes des instances

Les méthodes des instances des classes Property sont les suivantes :

default_value()

Renvoie la valeur par défaut de la propriété. La mise en œuvre de base utilise la valeur de l'argument default transmis au constructeur. Une classe de propriété peut remplacer cette valeur pour fournir un comportement spécial de valeur par défaut, tel que la fonctionnalité de définition automatique sur la date actuelle de DateTimeProperty.

validate(value)

Routine de validation complète de la propriété. Si la valeur indiquée pour l'élément value est valide, la méthode renvoie la valeur soit inchangée, soit adaptée au type requis. Sinon, elle génère une exception appropriée.

La mise en œuvre de base vérifie que l'élément value n'est pas défini sur None si "required" possède la valeur "True" (argument required pour le constructeur de propriétés de base), que la valeur est l'un des choix valides si la propriété a été configurée avec "choices" (argument choices), et que la valeur transmet le validateur personnalisé le cas échéant (argument validator).

La routine de validation est appelée lors de l'instanciation d'un modèle utilisant le type de propriété (avec les valeurs par défaut ou initialisées), et lors de l'affectation d'une valeur à une propriété de ce type. La routine ne doit pas avoir d'effets secondaires.

empty(value)

Renvoie True si l'élément value est considéré comme une valeur vide pour ce type de propriété. La mise en œuvre de base équivaut à not value, ce qui est suffisant pour la plupart des types. D'autres types, par exemple un type booléen, peuvent remplacer cette méthode par un test plus approprié.

get_value_for_datastore(model_instance)

Renvoie la valeur à stocker dans le datastore pour cette propriété de l'instance de modèle donnée. L'implémentation de base renvoie simplement la valeur native Python de la propriété dans l'instance de modèle. Une classe Property peut remplacer cette méthode si vous souhaitez utiliser un type de données différent pour le datastore et pour l'instance de modèle, respectivement, ou pour effectuer une autre conversion de données juste avant le stockage de l'instance de modèle.

make_value_from_datastore(value)

Renvoie la représentation native Python de la valeur donnée issue du datastore. L'implémentation de base renvoie simplement la valeur. Une classe Property peut remplacer cette méthode si vous souhaitez utiliser un type de données différent pour l'instance de modèle et pour le datastore, respectivement.

make_value_from_datastore_index_value(value)

Renvoie la représentation native Python de la valeur donnée issue de l'index du datastore. L'implémentation de base renvoie simplement la valeur. Une classe Property peut remplacer cette méthode si vous souhaitez utiliser un type de données différent pour l'instance de modèle et pour le datastore, respectivement.

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

Envoyer des commentaires concernant…

Environnement standard App Engine pour Python 2