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 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 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 concernant 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 se sert de cet argument pour fabriquer des libellés pour les champs de formulaire, et d'autres outils ou services peuvent l'utiliser à des fins similaires.

name

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 la valeur de la propriété n'est jamais indiquée, ou si la valeur indiquée est None, la valeur prise en compte est 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 dans la définition du modèle avec des données propres à la requête (telles que users.get_current_user()). À la place, définissez une méthode __init__() pour la classe Model qui initialise les valeurs de la propriété.

obligatoire

Si l'argument est défini sur True, la propriété ne peut pas prendre la 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. Toutefois, la propriété ne peut pas prendre la valeur None, et il n'existe aucun moyen de restaurer automatiquement la valeur par défaut un fois qu'une autre valeur a été affectée. Vous pouvez toujours accéder à l'attribut default de la propriété pour obtenir la valeur par défaut et l'affecter de manière explicite.

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, notamment 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 l'argument choices est défini sur None, toutes les valeurs qui seraient sinon 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 êtes sûr de ne jamais avoir besoin de filtrer ou de trier à partir d'une propriété, nous vous recommandons d'utiliser indexed=False pour éviter cette charge. Soyez toutefois vigilant ! Si vous décidez ultérieurement d'indexer tout même la propriété, la modification sur indexed=True n'affectera que les écritures postérieures à ce changement de configuration. Les entités écrites initialement avec l'argument défini sur 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.

L'implémentation de base vérifie que l'argument value n'est pas défini sur None si la valeur est requise (argument required transmis au constructeur de base Property), que la valeur correspond à l'un des choix corrects si vous avez configuré la propriété avec des choix (argument choices), et que la valeur passe 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 la valeur Truesi l'argument value est considéré comme une valeur vide pour ce type de propriété. L'implémentation de base équivalente à not value suffit 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.