Die Modellklasse

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.

Die Klasse Model ist die Basisklasse für Datenmodelldefinitionen.

Model ist im Modul google.appengine.ext.db definiert.

Einführung

Für eine Anwendung werden Datenmodelle durch Festlegung von Klassen definiert, die aus den Klassen von Model abgeleitet werden. Die Attribute des Modells werden mithilfe von Klassenattributen und von Instanzen der Property-Klasse definiert. Beispiel:

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

Zum Erstellen einer neuen Datenentität wird in einer Anwendung eine abgeleitete Klasse der Model-Klasse instanziiert. Die Properties einer Entität können mit Attributen der Instanz zugewiesen oder dem Konstruktor als Schlüsselwortargumente zugeordnet werden.

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

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

Der Name der abgeleiteten Klasse des Modells wird als Name der Art der Entität für den Datenspeicher verwendet. Für den Datenspeicher sind alle Namen von Arten reserviert, die mit zwei Unterstrichen beginnen (__). Für abgeleitete Klassen von Modellen dürfen solche Namen nicht verwendet werden.

Die Namen der Attribute werden als Namen der entsprechenden Properties einer Entität verwendet. Modellinstanzattribute, deren Namen mit einem Unterstrich (_) beginnen, werden ignoriert. Dadurch können diese Attribute in Ihrer Anwendung zum Speichern von Daten einer Modellinstanz verwendet werden, die nicht im Datenspeicher gespeichert werden.

Beim Datenspeicher und bei der Modellklassen-API gelten für Property-Namen und Modellinstanzattribute bestimmte Einschränkungen. Eine vollständige Beschreibung finden Sie unter Nicht zulässige Property-Namen.

Jede Entität enthält einen key. Dabei handelt es sich um eine eindeutige ID, die die Entität darstellt. Der Schlüssel kann einen optionalen Schlüsselnamen enthalten. Das ist ein String, der für alle Entitäten der angegebenen Art eindeutig ist. Die Art und der Schlüssel der Entität können mit den Methoden Key.from_path() und Model.get_by_key_name() für den Abruf der Entität verwendet werden.

Für eine Entität kann auch eine übergeordnete Entität vorhanden sein. Beziehungen zwischen über- und untergeordneten Elementen bilden Entitätengruppen, die zur Steuerung der Transaktionsfähigkeit und des Orts von Daten im Datenspeicher verwendet werden. In Anwendungen werden Beziehungen zwischen zwei über- und untergeordneten Entitäten dadurch erstellt, dass die übergeordnete Entität als parent-Argument an den Konstruktor der untergeordneten Entität übergeben wird.

Die Methode Model.get_or_insert() kann auch zum Abrufen einer Entität verwendet werden, die noch nicht vorhanden ist. Falls erforderlich, wird sie im Datenspeicher erstellt:

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

Hinweis: Für eine Modellinstanz gibt es keine entsprechende Entität im Datenspeicher, bis sie explizit oder mithilfe von Model.get_or_insert() zum ersten Mal geschrieben wird (put-Vorgang).

Mit der Funktion db.to_dict können Sie dict als Kopie der Daten einer Modellinstanz erstellen.

Konstruktor

Der Konstruktor für die Klasse Model ist so definiert:

Klasse Modell (parent=None, key_name=None, **kwds)

Die Basisklasse für Datenmodelldefinitionen.

Bei der Erstellung wird die Methode validate() jedes Attributs aufgerufen. Ausnahmen von solchen Aufrufen werden an Aufrufer dieses Konstruktors weitergegeben.

Argumente

parent

Die Modell- oder Schlüsselinstanz der Entität, bei der es sich um das übergeordnete Element der neuen Entität handelt.

key_name

Der Schlüsselname für die Entität. Der Name wird Teil des primären Schlüssels. Falls der Wert None lautet, wird für den Schlüssel eine vom System generierte numerische ID verwendet.

Der Wert für key_name darf nicht das Format __*__ haben.

Der Schlüsselname wird als Unicode-String gespeichert, wobei str-Werte in ASCII-Text konvertiert werden.

Durch Aufrufen von put() für dieses Objekt werden alle vorhandenen Datenspeicherentitäten mit dem gleichen Schlüssel überschrieben.

kwds

Anfängliche Werte für die Attribute der Instanz als Keyword-Argumente. Jeder Name entspricht einem Attribut, das für die Modellklasse definiert wurde.

Zusätzliches Schlüsselwortargument

key

Die explizite Key-Instanz für die Entität. Kann nicht mit key_name oder parent verwendet werden. Wenn der Wert None ist, wird das Verhalten für key_name und parent angewendet. Dies ist hilfreich, wenn mit allocate_ids() numerische IDs für neue Entitäten reserviert werden.

Der Wert für key muss eine gültige Key-Instanz sein.

Durch Aufrufen von put() für dieses Objekt werden alle vorhandenen Datenspeicherentitäten mit dem gleichen Schlüssel überschrieben.

Klassenmethoden

Die Klasse Model hat die folgenden Klassenmethoden:

Model.get (keys)

Ruft die Modellinstanz (oder -instanzen) für den (oder die) angegebenen Schlüssel ab. Die Schlüssel müssen Entitäten der Art des Modells darstellen. Wenn die Art des angegebenen Schlüssels nicht die richtige ist, wird die Ausnahme KindError ausgelöst.

Diese Methode entspricht der Funktion db.get(), beinhaltet jedoch eine zusätzliche Artüberprüfung.

Argumente

Schlüssel

Schlüssel der abzurufenden Entität, eine Stringdarstellung des Schlüssels oder eine Liste von Schlüsseln oder ihrer Stringdarstellungen

read_policy

Leserichtlinie, die das gewünschte Maß an Datenkonsistenz angibt:

STRONG_CONSISTENCY

Garantiert aktuelle Ergebnisse, ist jedoch auf nur eine Entitätengruppe beschränkt

EVENTUAL_CONSISTENCY

Kann für mehrere Entitätengruppen gelten, gibt aber teilweise veraltete Ergebnisse zurück. Abfragen mit Eventual Consistency werden in der Regel schneller ausgeführt als Abfragen mit Strong Consistency. Es gibt jedoch keine Garantie hierfür.

Hinweis: Globale Nicht-Ancestor-Abfragen ignorieren dieses Argument.

deadline

Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Der Wert kann nicht höher als der Standardwert (60 Sekunden) sein. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise hilfreich sein, wenn eine schnellere Antwort an den Nutzer gesendet, der Vorgang wiederholt, ein anderer Vorgang ausgeführt oder der Vorgang einer Aufgabenwarteschlange hinzugefügt werden soll.

Wenn keys aus einem einzelnen Schlüssel oder dessen Stringdarstellung besteht, gibt diese Methode die mit dem Schlüssel verknüpfte Modellinstanz zurück, wenn der Schlüssel im Datenspeicher vorhanden ist. Andernfalls wird None zurückgegeben. Wenn keys eine Liste ist, wird die entsprechende Liste der Modellinstanzen zurückgegeben. Schlüssel, für die keine Entität vorhanden ist, erhalten den Wert None.

Weitere Informationen finden Sie unter der Funktion db.get().

Model.get_by_id (ids, parent=None)

Ruft die Modellinstanz (oder -instanzen) für die angegebene numerische ID (oder die angegebenen numerischen IDs) ab.

Argumente

ids

Eine numerische Entitäts-ID oder eine Liste numerischer IDs

parent

Die übergeordnete Entität für die angeforderten Entitäten als Modell oder Schlüssel oder None (Standardeinstellung), wenn die angeforderten Entitäten keine übergeordnete Entität haben. Mehrere von einem Aufruf angeforderte Entitäten müssen das gleiche übergeordnete Element haben.

read_policy

Leserichtlinie, die das gewünschte Maß an Datenkonsistenz angibt:

STRONG_CONSISTENCY

Garantiert aktuelle Ergebnisse, ist jedoch auf nur eine Entitätengruppe beschränkt

EVENTUAL_CONSISTENCY

Kann für mehrere Entitätengruppen gelten, gibt aber teilweise veraltete Ergebnisse zurück. Abfragen mit Eventual Consistency werden in der Regel schneller ausgeführt als Abfragen mit Strong Consistency. Es gibt jedoch keine Garantie hierfür.

Hinweis: Globale Nicht-Ancestor-Abfragen ignorieren dieses Argument.

deadline

Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Der Wert kann nicht höher als der Standardwert (60 Sekunden) sein. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise hilfreich sein, wenn eine schnellere Antwort an den Nutzer gesendet, der Vorgang wiederholt, ein anderer Vorgang ausgeführt oder der Vorgang einer Aufgabenwarteschlange hinzugefügt werden soll.

Wenn ids aus einer einzelnen numerischen ID besteht, gibt diese Methode die mit der ID verknüpfte Modellinstanz zurück, sofern die ID im Datenspeicher vorhanden ist. Andernfalls wird None zurückgegeben. Wenn ids eine Liste ist, wird die entsprechende Liste der Modellinstanzen zurückgegeben. Numerische IDs, für die keine Entität vorhanden ist, erhalten den Wert None.

Model.get_by_key_name (key_names, parent=None)

Ruft die Modellinstanz (oder -instanzen) für den (oder die) angegebenen Schlüsselnamen ab.

Argumente

key_names

Ein Schlüsselname oder eine Liste mit Schlüsselnamen

parent

Die übergeordnete Entität für die angeforderten Entitäten als Modellinstanz oder Schlüssel oder None (Standardeinstellung), wenn die angeforderten Entitäten keine übergeordnete Entität haben. Mehrere von einem Aufruf angeforderte Entitäten müssen das gleiche übergeordnete Element haben.

read_policy

Leserichtlinie, die das gewünschte Maß an Datenkonsistenz angibt:

STRONG_CONSISTENCY

Garantiert aktuelle Ergebnisse, ist jedoch auf nur eine Entitätengruppe beschränkt

EVENTUAL_CONSISTENCY

Kann für mehrere Entitätengruppen gelten, gibt aber teilweise veraltete Ergebnisse zurück. Abfragen mit Eventual Consistency werden in der Regel schneller ausgeführt als Abfragen mit Strong Consistency. Es gibt jedoch keine Garantie hierfür.

Hinweis: Globale Nicht-Ancestor-Abfragen ignorieren dieses Argument.

deadline

Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Der Wert kann nicht höher als der Standardwert (60 Sekunden) sein. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise hilfreich sein, wenn eine schnellere Antwort an den Nutzer gesendet, der Vorgang wiederholt, ein anderer Vorgang ausgeführt oder der Vorgang einer Aufgabenwarteschlange hinzugefügt werden soll.

Wenn key_names aus einem einzelnen Schlüsselnamen besteht, gibt diese Methode die mit dem Namen verknüpfte Modellinstanz zurück, wenn der Name im Datenspeicher vorhanden ist. Andernfalls wird None zurückgegeben. Wenn key_names eine Liste ist, wird die entsprechende Liste der Modellinstanzen zurückgegeben. Schlüsselnamen, für die keine Entität vorhanden ist, erhalten den Wert None.

Model.get_or_insert (key_name, **kwds)

Versucht, die Entität der Art des Modells mit dem angegebenen Schlüsselnamen abzurufen. Sofern die Entität vorhanden ist, wird diese mit get_or_insert() einfach zurückgegeben. Wenn sie nicht vorhanden ist, wird eine neue Entität mit der angegebenen Art, dem angegebenen Namen und den angegebenen Parametern in kwds erstellt, gespeichert und zurückgegeben.

Die get- und (möglichen) nachfolgenden put-Vorgänge sind in eine Transaktion eingeschlossen, um für Atomizität zu sorgen. Das bedeutet, dass mit get_or_insert() keine vorhandene Entität überschrieben wird. Eine neue Entität wird nur dann eingefügt, wenn keine Entität der angegebenen Art mit dem angegebenen Namen vorhanden ist. Anders ausgedrückt: get_or_insert() entspricht dem folgenden Python-Code:

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")

Argumente

key_name

Der Name für den Schlüssel der Entität

kwds

Schlüsselwortargumente, die an den Konstruktor der Modellklasse gesendet werden, wenn keine Instanz mit dem angegebenen Schlüsselnamen vorhanden ist. Das parent-Argument ist erforderlich, wenn die gewünschte Entität ein übergeordnetes Element hat.

Hinweis: get_or_insert() akzeptiert kein read_policy- oder deadline-Argument.

Die Methode gibt eine Instanz der Modellklasse zurück, die die angeforderte Entität darstellt. Dies gilt unabhängig davon, ob sie vorhanden war oder durch die Methode erstellt wurde. Wie bei allen Datenspeichervorgängen löst diese Methode die Ausnahme TransactionFailedError aus, wenn die Transaktion nicht abgeschlossen werden kann.

Model.all (keys_only=False)

Gibt ein Query-Objekt zurück, das alle Entitäten der entsprechenden Modellart darstellt. Mit Methoden für das Abfrageobjekt können Filter und Sortierungen für die Abfrage festgelegt werden, bevor sie ausgeführt wird. Weitere Informationen finden Sie auf der Seite der Klasse Query.

Argumente

keys_only

Gibt an, ob die Abfrage vollständige Entitäten oder nur Schlüssel zurückgeben soll. Abfragen, die Schlüssel zurückgeben, sind schneller und benötigen weniger CPU-Zeit als Abfragen, die vollständige Entitäten zurückgeben.

Model.gql (query_string, *args, **kwds)

Führt eine GQL-Abfrage über die Instanzen dieses Modells durch.

Argumente

query_string

Der Teil der GQL-Abfrage, der auf SELECT * FROM model folgt. Dies wird durch die Verwendung dieser Klassenmethode impliziert.

args

Bindungen für Positionsparameter, ähnlich dem GqlQuery()-Konstruktor

kwds

Bindungen für Schlüsselwortparameter, ähnlich dem GqlQuery()-Konstruktor.

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

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

Der Rückgabewert ist ein GqlQuery-Objekt, mit dem auf die Ergebnisse zugegriffen werden kann.

Model.kind ()

Gibt die Art des Modells zurück. Dabei handelt es sich in der Regel um den Namen der abgeleiteten Klasse des Modells.

Model.properties ()

Gibt ein Dictionary aller für dieses Modell definierten Properties zurück

Instanzmethoden

Modellinstanzen haben die folgenden Methoden:

key ()

Gibt den Datenspeicher-Key für diese Modellinstanz zurück.

Der Schlüssel einer Modellinstanz enthält die Art der Entität der Instanz und eine eindeutige Kennzeichnung. Die Kennzeichnung kann entweder ein Schlüsselnamenstring sein, der beim Erstellen der Instanz explizit von der Anwendung zugewiesen wird, oder eine ganzzahlige numerische ID, die automatisch von App Engine zugewiesen wird, wenn die Instanz in den Datenspeicher geschrieben wird (put-Vorgang). Wird key() aufgerufen, bevor der Instanz eine Kennzeichnung zugewiesen wurde, wird die Ausnahme NotSavedError ausgelöst.

put ()

Speichert die Modellinstanz im Datenspeicher. Mit dieser Methode wird im Datenspeicher eine neue Datenentität erstellt, wenn die Modellinstanz neu erstellt und noch nicht gespeichert wurde. Andernfalls wird die Datenentität mit den aktuellen Property-Werten aktualisiert.

Die Methode gibt den Schlüssel der gespeicherten Entität zurück.

Wenn für die Daten kein Commit ausgeführt werden kann, wird die Ausnahme TransactionFailedError ausgelöst.

Argumente

deadline

Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Kann nicht auf einen höheren Wert als den Standardwert (60 Sekunden) festgelegt werden. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise nützlich sein, um eine schnellere Antwort an den Nutzer zu senden, den Vorgang zu wiederholen, einen anderen Vorgang auszuführen oder den Vorgang einer Aufgabenwarteschlange hinzuzufügen.

delete ()

Löscht die Modellinstanz aus dem Datenspeicher. Wenn die Instanz noch nicht in den Datenspeicher geschrieben wurde (put-Vorgang), löst das Löschen die Ausnahme NotSavedError aus.

Argumente

deadline

Maximale Wartezeit in Sekunden, in der ein Ergebnis aus dem Datenspeicher zurückgegeben werden kann, bevor der Vorgang mit einem Fehler abgebrochen wird. Akzeptiert entweder eine Ganzzahl oder einen Gleitkommawert. Kann nicht auf einen höheren Wert als den Standardwert (60 Sekunden) festgelegt werden. Eine Anpassung auf einen niedrigeren Wert ist jedoch möglich, wenn ein bestimmter Vorgang schnell fehlschlagen soll. Dies kann beispielsweise nützlich sein, um eine schnellere Antwort an den Nutzer zu senden, den Vorgang zu wiederholen, einen anderen Vorgang auszuführen oder den Vorgang einer Aufgabenwarteschlange hinzuzufügen.

is_saved ()

Gibt True zurück, wenn die Modellinstanz mindestens einmal in den Datenspeicher geschrieben wurde (put-Vorgang).

Diese Methode überprüft nur, ob die Instanz seit ihrer Erstellung mindestens einmal in den Datenspeicher geschrieben wurde. Sie prüft nicht, ob die Properties der Instanz seit dem letzten Schreibvorgang aktualisiert wurden.

dynamic_properties ()

Gibt eine Liste der Namen aller dynamischen Properties zurück, die für diese Modellinstanz definiert wurden. Dies gilt nur für Instanzen von Expando-Klassen. Bei Modellinstanzen, bei denen es sich nicht um Expando-Modellinstanzen handelt, wird eine leere Liste zurückgegeben.

parent ()

Gibt eine Modellinstanz für die übergeordnete Entität dieser Instanz oder None zurück, wenn diese Instanz kein übergeordnetes Element hat

parent_key ()

Gibt den Key der übergeordneten Entität dieser Instanz oder None zurück, wenn diese Instanz keine übergeordnete Instanz hat

to_xml ()

Gibt eine XML-Darstellung der Modellinstanz zurück.

Attributwerte entsprechen den Atom- und Datenspezifikationen.

Nicht zulässige Property-Namen

Beim Datenspeicher und der zugehörigen API gelten mehrere Einschränkungen zu Namen für Entitäts-Properties und Modellinstanzattribute.

Der Datenspeicher reserviert alle Property-Namen, die mit zwei Unterstrichen (__*__) beginnen und enden. Datenspeicherentitäten können keine Properties mit einem solchen Namen haben.

Die Python-Modell-API ignoriert alle Attribute einer Model- oder Expando-Klasse, die mit einem Unterstrich (_) beginnen. In der Anwendung können mit diesen Attributen den Modellobjekten Daten zugeordnet werden, die nicht im Datenspeicher abgelegt sind.

Außerdem werden in der Python-Modell-API Objektattribute zum Definieren der Properties eines Modells verwendet. Standardmäßig werden die Entitäts-Properties des Datenspeichers nach den Attributen benannt. Da verschiedene Properties und Methoden der Klasse Model für andere Zwecke vorgesehen sind, können diese Attribute nicht für Properties in der Python API verwendet werden. So kann beispielsweise ein Modell keine Property haben, auf das mit dem Attribut key zugegriffen wird.

Mit einer Property lässt sich aber ein anderer Name als der Attributname für die Datastore-Entität festlegen. Dazu geben Sie ein name-Argument für den Property-Konstruktor an. Dadurch kann die Datenspeicherentität einen Attributnamen haben, der einem reservierten Attribut in der Klasse Model ähnelt, und einen anderen Attributnamen in der Klasse verwenden.

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

Folgende Attributnamen sind für die Model-Klasse in der Python API reserviert:

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