Attributklasse

Hinweis: Entwicklern von neuen Anwendungen wird dringend empfohlen, die NDB-Clientbibliothek zu verwenden. Diese bietet im Vergleich zur vorliegenden Clientbibliothek verschiedene Vorteile, z. B. das automatische Caching von Entitäten über die Memcache API. Wenn Sie derzeit die ältere DB-Clientbibliothek verwenden, finden Sie weitere Informationen im Leitfaden zur Migration von DB- zu NDB-Clientbibliotheken.

Bei der Property-Klasse handelt es sich um die übergeordnete Klasse von Property-Definitionen für Datenmodelle. Die Property-Klasse definiert den Typ eines Property-Werts, d. h., wie Werte validiert und im Datenspeicher gespeichert werden.

Property wird vom Modul google.appengine.ext.db bereitgestellt.

Einführung

Eine Property-Kasse beschreibt den Werttyp, den Standardwert, die Validierungslogik und andere Merkmale einer Property eines Modells. Jede Property-Klasse ist eine Unterklasse der Property-Klasse. Das Datenspeicher-API umfasst Property-Klassen für alle Datenspeicherwerttypen sowie verschiedene weitere Property-Klassen, die neben den Datenspeichertypen zusätzliche Funktionen bereitstellen. Weitere Informationen finden Sie unter Typen und Attributklassen.

Property-Klassen können die Konfiguration von Argumenten übernehmen, die an den Konstruktor übergeben werden. Vom Basisklassenkonstruktor werden verschiedene Argumente unterstützt, die in der Regel in allen Property-Klassen unterstützt werden. Dazu zählen alle jene, die in der Datastore API bereitgestellt werden. Eine solche Konfiguration kann Folgendes umfassen: einen Standardwert, ob ein ausdrücklicher Wert erforderlich ist, eine Liste mit zulässigen Werten und benutzerdefinierte Validierungslogik. Weitere Informationen zum Konfigurieren der Property finden Sie in der Dokumentation für einen bestimmten Property-Typ.

Mit einer Property-Klasse wird das Modell für eine Datenspeicher-Property definiert. Der Property-Wert für eine Modellinstanz ist nicht enthalten. Instanzen der Property-Klasse zählen zur Modellklasse, nicht zu den Instanzen der Klasse. In Verbindung mit Python sind Instanzen von Property-Klassen "Deskriptoren", die das Verhalten der Attribute von Modellinstanzen anpassen. Weitere Informationen zu Deskriptoren finden Sie in der Python-Dokumentation.

Konstruktor

Der Konstruktor der Property-Basisklasse ist wie folgt definiert:

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

Die übergeordnete Klasse der Modell-Property-Definitionen.

Argumente

verbose_name

Ein nutzerfreundlicher Name des Attributs. Es muss sich immer um das erste Argument für einen Property-Konstruktor handeln. In der djangoforms-Bibliothek wird dieser Wert zum Erstellen von Bezeichnungen für Formularfelder verwendet.

name

Der Speichername für das Attribut, der in Anfragen verwendet wird. Standardmäßig wird der Attributname verwendet, der für die Property verwendet wird. Modellklassen können Attribute haben, die keine Properties sind und nicht als solche verwendet werden können. Aus diesem Grund kann für eine Property mithilfe von name im Datenspeicher ein reservierter Attributname als Property-Name verwendet werden. Für das Property-Attribut ist in diesem Fall ein anderer Name wählbar. Weitere Informationen finden Sie unter Nicht zulässige Attributamen.

Standardeinstellung

Ein Standardwert für die Property. Wenn dem Attributswert kein Wert oder der Wert None zugewiesen wird, wird der Wert als Standardwert betrachtet.

Hinweis: Modellklassendefinitionen werden zusammen mit dem restlichen Anwendungscode im Cache gespeichert. Auch Standardwerte für Properties werden im Cache gespeichert. Legen Sie in der Modelldefinition keinen Standardwert mit spezifischen Daten für die Anfrage fest (z. B. users.get_current_user()). Definieren Sie stattdessen eine __init__()-Methode für die Klasse "Model", die die Attributwerte initialisiert.

required

Bei True kann das Attribut nicht den Wert None haben. Mit einer Modellinstanz müssen alle erforderlichen Properties in deren Konstruktor initialisiert werden, damit die Instanz nicht mit fehlenden Werten erstellt wird. Der Versuch, eine Instanz zu erstellen, ohne ein erforderliches Attribut zu initialisieren, oder der Versuch, einem erforderlichen Attribut None zuzuweisen, führt zu einem BadValueError.

Bei Properties, die sowohl erforderlich sind, als auch einen Standardwert aufweisen, wird der Standardwert verwendet, sofern keiner im Konstruktor angegeben ist. Dem Attribut kann allerdings nicht der Wert None zugeordnet werden. Außerdem gibt es keine Standardlösung zum Wiederherstellen des Standardwerts, nachdem ein anderer Wert zugeordnet wurde. Sie können jederzeit auf das default-Attribut der Property zugreifen, um diesen Wert abzurufen und diesen ausdrücklich zuzuordnen.

Validator

Eine Funktion, die bei der Zuweisung des Attributswerts aufgerufen werden sollte, um den Wert zu validieren. Bei der Funktion wird der Wert als einziges Argument verwendet. Es wird eine Ausnahme ausgegeben, wenn der Wert ungültig ist. Das jeweilige Validierungselement wird nach dem Durchführen anderer Validierungen abgerufen. Zu diesen Validierungen zählt etwa die Prüfung, ob eine erforderliche Property einen Wert aufweist. Wenn einem nicht erforderlichen Attribut kein Wert zugewiesen wird, erfolgt die Validierung mit dem Argument None.

choices

Eine Liste zulässiger Werte für das Attribut. Der Property kann kein Wert zugeordnet werden, der nicht in der Liste enthalten ist, wenn diese Funktion festgelegt wurde. Ähnlich der required-Validierung und anderer Validierungen müssen bei einer Modellinstanz alle Attribute mit "choices" initialisiert werden, damit die Instanz nicht mit ungültigen Werten erstellt wird. Es sind alle Werte zulässig, die mit der sonstigen Validierung übereinstimmen, wenn choices den Wert None hat.

indexed

Gibt an, ob diese Property in die integrierten und von Entwicklern definierten Indexe einbezogen werden soll. Bei False werden in den Datenspeicher geschriebene Entitäten niemals von Abfragen zurückgegeben, die nach diesem Attribut sortieren oder filtern – ähnlich wie die Attribute Blob und Text.

Hinweis: Bei jedem indizierten Attribut kommt es bei den Aufrufen put() und delete() zu Mehraufwand, zu erhöhter Prozessorauslastung und zu Latenz. Ziehen Sie die Verwendung von indexed=False in Betracht, wenn Attribute nicht gefiltert oder sortiert werden müssen, um diesen Mehraufwand zu vermeiden. Gehen Sie jedoch umsichtig vor. Für den Fall, dass Sie später beschließen, dass das Attribut indiziert sein soll, sind von der Änderung zurück in indexed=True nur Schreibvorgänge ab diesem Zeitpunkt betroffen. Entitäten, die ursprünglich mit indexed=False geschrieben wurden, werden nicht neu indiziert.

Klassenattribute

Von abgeleiteten Klassen der Property-Klassen werden die folgenden Klassenattribute definiert:

data_type

Der Python-Datentyp oder die Python-Klasse, der oder die bei der Property als nativer Python-Wert zulässig ist.

Instanzmethoden

Instanzen von Property-Klassen weisen die folgenden Methoden auf:

default_value()

Gibt den Standardwert für die Property zurück. Bei der Basisimplementierung wird der Wert des Arguments default verwendet, das an den Konstruktor gesendet wurde. Dies kann durch eine Attributklasse außer Kraft gesetzt werden, um ein spezielles Verhalten für den Standardwert zu bewirken, beispielsweise mit der Funktion "auto_now" von DateTimeProperty.

validate(value)

Die vollständige Validierungsroutine für die Property. Wenn value gültig ist, wird der Wert unverändert oder an den erforderlichen Typ angepasst zurückgegeben. Anderenfalls wird eine entsprechende Ausnahme ausgegeben.

Bei der Basisimplementierung wird geprüft, ob folgende Voraussetzungen erfüllt sind: value ist nicht None (falls nötig) – dies ist das Argument required für den grundlegenden Attribut-Konstruktor. Der Wert ist eine der gültigen Auswahloptionen, wenn das Attribut mit Auswahloptionen bzw. dem Argument choices konfiguriert wurde. Außerdem muss der Wert in der benutzerdefinierten Validierung mit dem Argument validator akzeptiert werden.

Die Validierungsroutine wird abgerufen, wenn ein Modell mit Standardwerten oder initialisierten Werten instanziiert wird, bei dem der Property-Typ verwendet wird. Darüber hinaus wird sie abgerufen, wenn einer Property des Typs ein Wert zugeordnet wird. Die Routine sollte keine Nebenwirkungen haben.

empty(value)

Gibt True zurück, wenn value als leerer Wert für diesen Attributstypen gewertet wird. Die Basisimplementierung entspricht not value. Dies reicht für die meisten Typen aus. Bei anderen Typen, etwa einem booleschen Typ, kann dieser Typ mit einem geeigneteren Test überschrieben werden.

get_value_for_datastore(model_instance)

Gibt den Wert zurück, der im Datenspeicher für diese Property in der entsprechenden Modellinstanz gespeichert werden sollte. Bei dieser Basisimplementierung wird schlicht der native Python-Wert der Property in der Modellinstanz zurückgegeben. Mit einer Property-Klasse kann diese Funktion so überschrieben werden, dass für den Datenspeicher ein anderer Datentyp als für die Modellinstanz verwendet wird oder dass direkt vor dem Speichern der Modellinstanz eine andere Datenkonvertierung durchgeführt wird.

make_value_from_datastore(value)

Gibt aus dem Datenspeicher die native Python-Darstellung für den gegebenen Wert zurück. Bei der Basisimplementierung wird einfach der Wert zurückgegeben. Mit einer Property-Klasse kann diese Funktion so überschrieben werden, dass für die Modellinstanz ein anderer Datentyp als für den Datenspeicher verwendet wird.

make_value_from_datastore_index_value(value)

Gibt die Python-native Darstellung eines Werts aus dem Datenspeicherindex zurück. Bei der Basisimplementierung wird einfach der Wert zurückgegeben. Mit einer Property-Klasse kann diese Funktion so überschrieben werden, dass für die Modellinstanz ein anderer Datentyp als für den Datenspeicher verwendet wird.