Classe del modello

Nota: gli sviluppatori che creano nuove applicazioni sono vivamente incoraggiati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, come la memorizzazione nella cache automatica delle entità tramite l'API Memcache. Se attualmente utilizzi la libreria client DB precedente, leggi la Guida alla migrazione dal database a NDB

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

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

Introduzione

Un'applicazione definisce un modello dei dati definendo una classe che sottoclasse Model. Le proprietà del modello vengono definite utilizzando attributi di classe e 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à dati creando un'istanza di una sottoclasse della classe Model. Le proprietà di un'entità possono essere assegnate utilizzando gli attributi dell'istanza o come argomenti di parola chiave per il 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 prenota tutti i nomi di tipo che iniziano con due trattini bassi (__). Le sottoclassi dei modelli non devono utilizzare questi nomi.

I nomi degli attributi vengono utilizzati come nomi delle proprietà corrispondenti di un'entità. Gli attributi delle istanze del modello i cui nomi iniziano con un trattino basso (_) vengono ignorati, pertanto l'applicazione può utilizzare questi attributi per archiviare i dati su un'istanza del modello che non viene salvata nel datastore.

Datastore e l'API della classe del modello impongono diverse restrizioni sui nomi delle proprietà e sugli attributi delle istanze modello. Per una descrizione completa, consulta la sezione Nomi delle proprietà non consentite.

Ogni entità ha una chiave,un identificatore univoco che rappresenta l'entità. La chiave può includere un nome chiave facoltativo,ovvero una stringa univoca tra 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à parent facoltativa. Le relazioni padre-figlio formano gruppi di entità,che vengono utilizzati per controllare la transazione e la località dei dati nel datastore. Un'applicazione crea una relazione padre-figlio tra due entità passando l'entità padre al costruttore dell'entità figlio come argomento parent.

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

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

Nota: un'istanza di modello non ha un'entità corrispondente in Datastore fino a quando 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 viene definito come segue:

class Modello (parent=Nessuno, parent=Nessuno, parent)

La superclasse per le definizioni modello dei dati.

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

Argomenti

parent

L'istanza o la chiave del modello per l'entità padre 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 nel formato __*__.

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

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

kwd

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

Argomento aggiuntivo della parola chiave

chiave

L'istanza Key esplicita per l'entità. Non possono essere utilizzati con key_name o parent. Se None, applica il comportamento di key_name e parent. Utile quando si utilizza allocate_ids() per prenotare ID numerici per le nuove entità.

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

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

Metodi delle classi

La classe Model prevede i seguenti metodi:

Model.get (keys)

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

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

Argomenti

chiavi

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

read_policy

Leggi il criterio che specifica il livello desiderato di coerenza dei dati:

STRONG_CONSISTENCY

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

EVENTUAL_CONSISTENCY

Può includere più gruppi di entità, ma a volte può restituire risultati obsoleti. In generale, le query a coerenza finale vengono eseguite più velocemente delle query a coerenza elevata, ma non vi è alcuna garanzia.

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

scadenza

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

Se keys è costituito da una singola chiave (o da una sua rappresentazione stringa), questo metodo restituisce l'istanza del modello associata alla chiave se la chiave esiste nel 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, ids=Nessuno)

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

Argomenti

ids

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

parent

L'entità padre per le entità richieste, come modello o chiave, oppure None (impostazione predefinita) se le entità richieste non hanno un elemento padre. Più entità richieste da una chiamata devono avere tutte lo stesso elemento padre.

read_policy

Leggi il criterio che specifica il livello desiderato di coerenza dei dati:

STRONG_CONSISTENCY

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

EVENTUAL_CONSISTENCY

Può includere più gruppi di entità, ma a volte può restituire risultati obsoleti. In generale, le query a coerenza finale vengono eseguite più velocemente delle query a coerenza elevata, ma non vi è alcuna garanzia.

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

scadenza

Tempo massimo, in secondi, di attesa affinché Datastore restituisca un risultato prima di interrompere con un errore. Accetta un numero intero o un valore con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere regolato verso il basso per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio, per restituire una risposta più rapida all'utente, ritentare 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 nel 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, key_names=Nessuno)

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

Argomenti

key_names

Il nome di una chiave o un elenco di nomi di chiavi.

parent

L'entità padre per le entità richieste, come istanza o chiave del modello, oppure None (impostazione predefinita) se le entità richieste non hanno un elemento padre. Più entità richieste da una singola chiamata devono avere tutte lo stesso elemento padre.

read_policy

Leggi il criterio che specifica il livello desiderato di coerenza dei dati:

STRONG_CONSISTENCY

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

EVENTUAL_CONSISTENCY

Può includere più gruppi di entità, ma a volte può restituire risultati obsoleti. In generale, le query a coerenza finale vengono eseguite più velocemente delle query a coerenza elevata, ma non vi è alcuna garanzia.

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

scadenza

Tempo massimo, in secondi, di attesa affinché Datastore restituisca un risultato prima di interrompere con un errore. Accetta un numero intero o un valore con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere regolato verso il basso per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio, per restituire una risposta più rapida all'utente, ritentare 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 nel 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 di 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() si limita a restituirlo. 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 le successive (possibili) operazioni di put sono aggregate 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à

kwd

Argomenti delle 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 elemento padre.

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, indipendentemente dal fatto che esista o sia stata creata dal metodo. Come per tutte le operazioni Datastore, questo metodo può generare un TransactionFailedError se non è stato possibile completare la transazione.

Model.all (keys_only=False)

Restituisce un oggetto Query che rappresenta tutte le entità del tipo corrispondente a questo modello. I metodi sull'oggetto query possono applicare filtri e ordinamenti alla query prima che venga eseguita. Per saperne di più, 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 di 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 (implicita utilizzando questo metodo delle classi).

args

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

kwd

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

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

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

Model.properties ()

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

Metodi di istanza

Le istanze del modello hanno i seguenti metodi:

chiave ()

Restituisce il datastore Key per questa istanza del modello.

La chiave di un'istanza di modello include il tipo di entità dell'istanza e un identificatore univoco. L'identificatore può essere una stringa nome chiave, assegnata esplicitamente dall'applicazione al momento della creazione dell'istanza, o un ID numerico intero assegnato automaticamente da App Engine quando l'istanza viene scritta (put) in Datastore. La chiamata a 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 appena creata e non è mai stata archiviata, questo metodo crea una nuova entità dati in Datastore. In caso contrario, aggiorna l'entità dati con i valori attuali della proprietà.

Il metodo restituisce la chiave dell'entità archiviata.

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

Argomenti

scadenza

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

elimina ()

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

Argomenti

scadenza

Tempo massimo, in secondi, di attesa affinché Datastore restituisca un risultato prima di interrompere con un errore. Accetta un numero intero o un valore con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere regolato verso il basso per garantire che una determinata operazione non vada a buon fine rapidamente (ad esempio, per restituire una risposta più rapida all'utente, ritentare 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 in cui è stata scritta.

dynamic_properties ()

Restituisce un elenco dei nomi di tutte le proprietà dinamiche definite per questa istanza del modello. Si applica solo alle istanze delle classi Expando. Per le istanze dei modelli non di Espandio, viene restituito un elenco vuoto.

parent ()

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

parent_key ()

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

to_xml ()

Restituisce una rappresentazione XML dell'istanza del modello.

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

Nomi di proprietà non consentiti

Datastore e la relativa API impongono diverse restrizioni sui nomi per le proprietà dell'entità e gli attributi delle istanze del modello.

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

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

Infine, l'API del modello Python utilizza attributi degli oggetti per definire le proprietà di un modello e, per impostazione predefinita, le proprietà dell'entità Datastore vengono denominate dopo gli attributi. Poiché la classe Model ha diversi metodi e proprietà per altri scopi, questi attributi non possono essere utilizzati per le proprietà nell'API Python. Ad esempio, a un modello non è possibile accedere a una proprietà con l'attributo key.

Tuttavia, una proprietà può specificare per Datastore un nome diverso da quello dell'attributo assegnando un argomento name al costruttore della proprietà. Ciò consente all'entità Datastore di avere un nome proprietà simile a un attributo riservato nella classe Model e di utilizzare un nome di attributo diverso nella classe.

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

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

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