La classe Model

Nota:gli sviluppatori che creano nuove applicazioni sono fortemente incoraggiati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, ad esempio la memorizzazione automatica nella cache delle entità tramite l'API Memcache. Se al momento utilizzi la libreria client DB precedente, leggi la guida alla migrazione da DB a NDB.

La classe Model è la superclasse per le definizioni del modello dei dati.

Model è definito nel modulo google.appengine.ext.db.

Introduzione

Un'applicazione definisce un modello dei dati definendo una classe che crea sottoclassi di Model. Le proprietà del modello vengono definite utilizzando gli attributi di classe e le istanze di classe Property. Ad esempio:

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

Un'applicazione crea una nuova entità di dati istanziando una sottoclasse della classe Model. Le proprietà di un'entità possono essere assegnate utilizzando gli attributi dell'istanza o come argomenti parola chiave del costruttore.

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

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

Il nome della sottoclasse del modello viene utilizzato come nome del tipo di entità Datastore. Datastore riserva tutti i nomi di tipo che iniziano con due trattini bassi (__). Le sottoclassi del modello non devono utilizzare questi nomi.

I nomi degli attributi vengono utilizzati come nomi delle proprietà corrispondenti di un'entità. Gli attributi dell'istanza del modello i cui nomi iniziano con un trattino basso (_) vengono ignorati, quindi la tua applicazione può utilizzare questi attributi per archiviare dati in un'istanza del modello che non viene salvata in Datastore.

L'API Datastore e della classe modello impongono diverse limitazioni ai nomi delle proprietà e agli attributi delle istanze del modello. Per una descrizione completa, vedi Nomi delle proprietà non consentiti.

Ogni entità ha una chiave, un identificatore univoco che rappresenta l'entità. La chiave può includere un nome della chiave facoltativo,una stringa univoca per le entità del tipo specificato. Il tipo e il nome della chiave dell'entità possono essere utilizzati con i metodi Key.from_path() e Model.get_by_key_name() per recuperare l'entità.

Un'entità può anche avere un'entità principale facoltativa. Le relazioni padre-figlio formano gruppi di entità, che vengono utilizzati per controllare la transazionalità e la località dei dati in Datastore. Un'applicazione crea una relazione principale-secondario tra due entità passando l'entità padre al costruttore dell'entità secondaria come argomento parent.

Il metodo Model.get_or_insert() può essere utilizzato per recuperare un'entità che potrebbe non esistere, creandola in Datastore se necessario:

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

Nota:un'istanza del modello non ha un'entità corrispondente in Datastore finché non viene scritta (put) per la prima volta, in modo esplicito o tramite Model.get_or_insert().

Per creare un dict che sia una copia dei dati di un'istanza del modello, utilizza la funzione db.to_dict.

Costruttore

Il costruttore della classe Model è definito come segue:

class Model (parent=None, key_name=None, **kwds)

La superclasse per le definizioni del modello dei dati.

Durante la costruzione, viene chiamato il metodo validate() di ogni proprietà. Le eccezioni di queste chiamate vengono propagate ai chiamanti di questo costruttore.

Argomenti

genitore

L'istanza o la chiave del modello per l'entità che è l'entità principale della nuova entità.

key_name

Il nome della chiave per l'entità. Il nome diventa parte della chiave primaria. Se None, viene utilizzato un ID numerico generato dal sistema per la chiave.

Il valore di key_name non deve essere della forma __*__.

Il nome della chiave viene memorizzato come stringa Unicode, con i valori str convertiti come testo ASCII.

La chiamata di put() su questo oggetto sovrascriverà qualsiasi entità Datastore esistente con la stessa chiave.

kwds

Valori iniziali per le proprietà dell'istanza, come argomenti di parole chiave. Ogni nome corrisponde a un attributo definito nella classe Model.

Argomento di parola chiave aggiuntivo

chiave

L'istanza Key esplicita per l'entità. Non può essere utilizzato con key_name o parent. Se None, viene eseguito il fallback sul comportamento per key_name e parent. Utile quando si utilizza allocate_ids() per riservare ID numerici per nuove entità.

Il valore di key deve essere un'istanza Key valida.

La chiamata di put() su questo oggetto sovrascriverà qualsiasi entità Datastore esistente con la stessa chiave.

Metodi della classe

La classe Model ha i seguenti metodi di classe:

Model.get (keys)

Recupera l'istanza o le istanze del modello per la chiave o le chiavi specificate. Le chiavi devono rappresentare le entità del tipo di modello. Se una chiave fornita non è del tipo corretto, viene generata un'eccezione KindError.

Questo metodo è simile alla funzione db.get(), con un controllo aggiuntivo del tipo.

Argomenti

chiavi

Key Chiave dell'entità da recuperare, una rappresentazione di stringa della chiave o un elenco di chiavi o delle relative rappresentazioni di stringa.

read_policy

Leggi le norme che specificano il livello di coerenza dei dati desiderato:

STRONG_CONSISTENCY

Garantisce i risultati più recenti, ma è limitato a un singolo gruppo di entità.

EVENTUAL_CONSISTENCY

Può estendersi a più gruppi di entità, ma occasionalmente potrebbe restituire risultati non aggiornati. In generale, le query con coerenza finale vengono eseguite più rapidamente rispetto alle query con coerenza forte, ma non è garantito.

Nota:le query globali (non di antenati) ignorano questo argomento.

deadline

Tempo massimo, in secondi, di attesa prima che Datastore restituisca un risultato prima di interrompere l'operazione con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore a quello predefinito (60 secondi), ma può essere ridotto per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio, per restituire una risposta più rapida all'utente, riprovare l'operazione, provare un'operazione diversa o aggiungere l'operazione a una coda di attività).

Se keys è costituito da una singola chiave (o dalla relativa rappresentazione di stringa), questo metodo restituisce l'istanza del modello associata alla chiave se la chiave esiste in Datastore, altrimenti None. Se keys è un elenco, il valore restituito è un elenco corrispondente di istanze del modello, con valori None in cui non esiste alcuna entità per una determinata chiave.

Vedi anche la funzione db.get().

Model.get_by_id (ids, parent=None)

Recupera l'istanza (o le istanze) del modello per l'ID numerico (o gli ID) specificato.

Argomenti

ids

Un ID entità numerico o un elenco di ID numerici.

genitore

L'entità padre per le entità richieste, come modello o chiave, oppure None (il valore predefinito) se le entità richieste non hanno un'entità padre. Le più entità richieste da una chiamata devono avere tutte lo stesso genitore.

read_policy

Leggi le norme che specificano il livello di coerenza dei dati desiderato:

STRONG_CONSISTENCY

Garantisce i risultati più recenti, ma è limitato a un singolo gruppo di entità.

EVENTUAL_CONSISTENCY

Può estendersi a più gruppi di entità, ma occasionalmente potrebbe restituire risultati non aggiornati. In generale, le query con coerenza finale vengono eseguite più rapidamente rispetto alle query con coerenza forte, ma non è garantito.

Nota:le query globali (non di antenati) ignorano questo argomento.

deadline

Tempo massimo, in secondi, di attesa prima che Datastore restituisca un risultato prima di interrompere l'operazione con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore a quello predefinito (60 secondi), ma può essere ridotto per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio, per restituire una risposta più rapida all'utente, riprovare l'operazione, provare un'operazione diversa o aggiungere l'operazione a una coda di attività).

Se ids è costituito da un singolo ID numerico, questo metodo restituisce l'istanza del modello associata all'ID se l'ID esiste in Datastore, altrimenti None. Se ids è un elenco, il valore restituito è un elenco corrispondente di istanze del modello, con valori None in cui non esiste alcuna entità per un determinato ID numerico.

Model.get_by_key_name (key_names, parent=None)

Recupera l'istanza o le istanze del modello per il nome o i nomi della chiave specificati.

Argomenti

key_names

Un nome di chiave o un elenco di nomi di chiavi.

genitore

L'entità padre per le entità richieste, come istanza del modello o chiave, o None (il valore predefinito) se le entità richieste non hanno un elemento principale. Le più entità richieste da una chiamata devono avere tutte lo stesso genitore.

read_policy

Leggi le norme che specificano il livello di coerenza dei dati desiderato:

STRONG_CONSISTENCY

Garantisce i risultati più recenti, ma è limitato a un singolo gruppo di entità.

EVENTUAL_CONSISTENCY

Può estendersi a più gruppi di entità, ma occasionalmente potrebbe restituire risultati non aggiornati. In generale, le query con coerenza finale vengono eseguite più rapidamente rispetto alle query con coerenza forte, ma non è garantito.

Nota:le query globali (non di antenati) ignorano questo argomento.

deadline

Tempo massimo, in secondi, di attesa prima che Datastore restituisca un risultato prima di interrompere l'operazione con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore a quello predefinito (60 secondi), ma può essere ridotto per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio, per restituire una risposta più rapida all'utente, riprovare l'operazione, provare un'operazione diversa o aggiungere l'operazione a una coda di attività).

Se key_names è costituito da un singolo nome di chiave, questo metodo restituisce l'istanza del modello associata al nome se il nome esiste in Datastore, altrimenti None. Se key_names è un elenco, il valore restituito è un elenco corrispondente di istanze del modello, con valori None in cui non esiste alcuna entità per un determinato nome chiave.

Model.get_or_insert (key_name, **kwds)

Tenta di ottenere l'entità del tipo di modello con il nome della chiave specificato. Se esiste, get_or_insert() lo restituisce. Se non esiste, viene creata, archiviata e restituita una nuova entità con il tipo, il nome e i parametri specificati in kwds.

Le operazioni get e put successive (eventuali) sono racchiuse in una transazione per garantire l'atomicità. Ciò significa che get_or_insert() non sovrascriverà mai un'entità esistente e inserirà una nuova entità se e solo se non esiste un'entità con il tipo e il nome specificati. In altre parole, get_or_insert() equivale al seguente codice Python:

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

Argomenti

key_name

Il nome della chiave dell'entità

kwds

Argomenti di parole chiave da passare al costruttore della classe del modello se non esiste un'istanza con il nome della chiave specificato. L'argomento parent è obbligatorio se l'entità desiderata ha un'entità principale.

Nota:get_or_insert() non accetta un argomento read_policy o deadline.

Il metodo restituisce un'istanza della classe del modello che rappresenta l'entità richiesta, che esistesse o sia stata creata dal metodo. Come per tutte le operazioni Datastore, questo metodo può generare un'eccezione TransactionFailedError se la transazione non è stata completata.

Model.all (keys_only=False)

Restituisce un oggetto Query che rappresenta tutte le entità del tipo corrispondente a questo modello. I metodi dell'oggetto query possono applicare filtri e ordinamenti alla query prima dell'esecuzione. Per ulteriori informazioni, consulta la pagina della classe Query.

Argomenti

keys_only

Indica se la query deve restituire entità complete o solo chiavi. Le query che restituiscono chiavi sono più veloci e utilizzano meno tempo della CPU rispetto alle query che restituiscono entità complete.

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

Esegue una query GQL sulle istanze di questo modello.

Argomenti

query_string

La parte della query GQL che segue SELECT * FROM model (che è implicita nell'utilizzo di questo metodo della classe).

args

Associazioni di parametri posizionali, simili al GqlQuery() costruttore.

kwds

Associazioni di parametri delle parole chiave, simili al GqlQuery()costruttore.

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

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

Il valore restituito è un oggetto GqlQuery che può essere utilizzato per accedere ai risultati.

Model.kind ()

Restituisce il tipo di modello, in genere il nome della sottoclasse Model.

Model.properties ()

Restituisce un dizionario di tutte le proprietà definite per questa classe di modello.

Metodi dell'istanza

Le istanze del modello hanno i seguenti metodi:

chiave ()

Restituisce l'Key di Datastore per questa istanza del modello.

La chiave di un'istanza del modello include il tipo di entità dell'istanza e un identificatore univoco. L'identificatore può essere una stringa nome chiave, assegnata esplicitamente dall'applicazione quando viene creata l'istanza, o un ID numerico intero,assegnato automaticamente da App Engine quando l'istanza viene scritta (put) nel datastore. La chiamata di key() prima che all'istanza sia stato assegnato un identificatore genera un'eccezione NotSavedError.

put ()

Archivia l'istanza del modello in Datastore. Se l'istanza del modello è stata creata di recente e non è mai stata archiviata, questo metodo crea una nuova entità di dati in Datastore. In caso contrario, aggiorna l'entità dati con i valori delle proprietà correnti.

Il metodo restituisce la chiave dell'entità archiviata.

Se non è stato possibile eseguire il commit dei dati, viene generata un'eccezione TransactionFailedError.

Argomenti

deadline

Tempo massimo, in secondi, di attesa prima che Datastore restituisca un risultato prima di interrompere l'operazione con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore a quello predefinito (60 secondi), ma può essere ridotto per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio, per restituire una risposta più rapida all'utente, riprovare l'operazione, provare un'operazione diversa o aggiungere l'operazione a una coda di attività).

delete ()

Elimina l'istanza del modello da Datastore. Se l'istanza non è mai stata scritta (put) in Datastore, l'eliminazione genera un'eccezione NotSavedError.

Argomenti

deadline

Tempo massimo, in secondi, di attesa prima che Datastore restituisca un risultato prima di interrompere l'operazione con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore a quello predefinito (60 secondi), ma può essere ridotto per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio, per restituire una risposta più rapida all'utente, riprovare l'operazione, provare un'operazione diversa o aggiungere l'operazione a una coda di attività).

is_saved ()

Restituisce True se l'istanza del modello è stata scritta (put) in Datastore almeno una volta.

Questo metodo verifica solo che l'istanza sia stata scritta in Datastore almeno una volta dalla sua creazione. Non controlla se le proprietà dell'istanza sono state aggiornate dall'ultima volta che è stata scritta.

dynamic_properties ()

Restituisce un elenco dei nomi di tutte le proprietà dinamiche definite per questa istanza del modello. Questo vale solo per le istanze delle classi Expando. Per le istanze del modello non espandibile, viene restituito un elenco vuoto.

parent ()

Restituisce un'istanza del modello per l'entità padre di questa istanza oppure None se questa istanza non ha un elemento principale.

parent_key ()

Restituisce l' Key dell'entità padre di questa istanza o None se questa istanza non ha un elemento principale.

to_xml ()

Restituisce una rappresentazione XML dell'istanza del modello.

I valori delle proprietà sono conformi alle specifiche Atom e Data.

Nomi delle proprietà non consentiti

Datastore e la relativa API impongono diverse limitazioni ai nomi delle proprietà delle entità e degli attributi delle istanze del modello.

Datastore riserva tutti i nomi delle proprietà che iniziano e terminano con due trattini bassi (__*__). Un'entità Datastore non può avere una proprietà con un nome di questo tipo.

L'API Python Model ignora tutti gli attributi di una classe Model o Expando che iniziano con un trattino basso (_). La tua applicazione può utilizzare questi attributi per associare dati agli oggetti modello che non vengono salvati in Datastore.

Infine, l'API Python Model utilizza gli attributi degli oggetti per definire le proprietà di un modello e, per impostazione predefinita, le proprietà delle entità Datastore prendono il nome dagli attributi. Poiché la classe Model ha diverse proprietà e metodi per altri scopi, questi attributi non possono essere utilizzati per le proprietà nell'API Python. Ad esempio, un modello non può avere una proprietà a cui si accede con l'attributo key.

Tuttavia, una proprietà può specificare un nome diverso per Datastore rispetto al nome dell'attributo fornendo un argomento name al costruttore della proprietà. In questo modo, l'entità Datastore può avere un nome di proprietà simile a un attributo riservato nella classe Model e utilizzare un nome di attributo diverso nella classe.

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

I seguenti nomi di attributi sono riservati dalla classe Model nell'API Python: