La classe Model

Nota: Gli sviluppatori che creano nuove applicazioni sono vivamente incoraggiati a utilizzare il Libreria client NDB, che offre numerosi vantaggi rispetto a questa libreria client, come la memorizzazione automatica nella cache delle entità tramite tramite Google Cloud CLI o tramite l'API Compute Engine. Se al momento utilizzi la libreria client DB precedente, leggi il Guida alla migrazione da DB a NDB

La classe Model è la superclasse per le definizioni 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 Model. Le proprietà del modello vengono definite utilizzando attributi di classe e Property di Compute Engine. 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 di Model . Le proprietà di un'entità possono essere assegnate utilizzando gli attributi dell'istanza, o come argomenti delle parole 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 dei tipi che iniziano con due trattini bassi (__). Le sottoclassi del modello non devono utilizzare questi nomi.

I nomi degli attributi vengono utilizzati come nomi dei su un'entità. Attributi di istanza di modello i cui nomi iniziano con un il trattino basso (_) viene ignorato, pertanto la tua applicazione può utilizzare per archiviare dati su un'istanza del modello che non viene salvata Datastore.

Datastore e l'API della classe del modello impongono diverse restrizioni alla proprietà i nomi degli utenti e gli attributi delle istanze del modello. Consulta: Nomi di proprietà non consentiti per una descrizione completa.

Ogni entità ha una chiave, un identificatore univoco che la rappresenta. La chiave può includere un campo facoltativo nome chiave,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 recuperarla.

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

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 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 di dati.

Durante la compilazione, viene chiamato il metodo validate() di ogni proprietà. Le eccezioni di queste chiamate vengono propagate agli utenti che chiamano questo costruttore.

Argomenti

padre

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

key_name

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

Il valore di key_name non deve essere nel formato __*__.

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

Chiamata in corso put() su questo oggetto sovrascriverà qualsiasi entità Datastore esistente con la stessa chiave.

kwds

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

Argomento aggiuntivo parola chiave

chiave

L'esplicita Key per l'entità. Non può essere utilizzato con key_name o parent. Se None, utilizza di nuovo il comportamento per key_name e parent. Utile quando utilizzi allocate_ids() per riservare ID numerici per le nuove entità.

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

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

Metodi della classe

La classe Model prevede i seguenti metodi:

Model.get (chiavi)

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

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

Argomenti

tasti

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 limitati a un singolo gruppo di entità.

EVENTUAL_CONSISTENCY

Può abbracciare più gruppi di entità, ma occasionalmente può ritornare i risultati obsoleti. In genere, le query eventualmente coerenti vengono eseguite più velocemente delle query fortemente coerenti, ma non c'è alcuna garanzia.

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

deadline

Tempo massimo, in secondi, di attesa che Datastore restituisca un risultato prima di interrompere con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere modificato 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, riprovare a eseguire l'operazione, provare un'operazione diversa o aggiungerla a una coda di attività).

Se keys è composto da una singola chiave (o dalla relativa stringa) ), questo metodo restituisce l'istanza del modello associata se la chiave esiste nel Datastore, altrimenti None. Se keys è un elenco, il valore restituito è un elenco corrispondente di di istanze di modello, con valori None in cui non esiste alcuna entità per una data 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 specificato (o ID).

Argomenti

id

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

padre

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

read_policy

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

STRONG_CONSISTENCY

Garantisce i risultati più recenti, ma limitati a una singola gruppo di entità.

EVENTUAL_CONSISTENCY

Può abbracciare più gruppi di entità, ma occasionalmente può ritornare i risultati obsoleti. In genere, le query eventualmente coerenti vengono eseguite più velocemente delle query fortemente coerenti, ma non c'è alcuna garanzia.

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

deadline

Tempo massimo, in secondi, di attesa che Datastore restituisca un risultato prima di interrompere con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere modificato 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, riprovare l'operazione, provare un'altra operazione 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 quest'ultimo 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 specificato.

Argomenti

key_names

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

parent

L'entità principale per le entità richieste, come istanza o chiave del modello oppure None (il valore predefinito) se le entità richieste non hanno un elemento principale. 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 limitati a una singola gruppo di entità.

EVENTUAL_CONSISTENCY

Può abbracciare più gruppi di entità, ma occasionalmente può ritornare i risultati obsoleti. In genere, le query eventualmente coerenti vengono eseguite più velocemente delle query fortemente coerenti, ma non c'è alcuna garanzia.

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

deadline

Tempo massimo, in secondi, di attesa che Datastore restituisca un risultato prima di interrompere con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere modificato 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, riprovare a eseguire l'operazione, provare un'operazione diversa o aggiungerla a una coda di attività).

Se key_names è costituito da un singolo nome chiave, questo metodo restituisce l'istanza del modello associata al nome se il nome esiste nel Datastore, altrimenti None. Se key_names è un , il valore restituito corrisponde a un elenco corrispondente di istanze del modello, 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() lo restituisce semplicemente. In caso contrario esiste, una nuova entità con il tipo, il nome e i parametri specificati kwds viene creato, archiviato e restituito.

Le operazioni get e put successive (possibili) sono aggregate in un 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 nessuna entità con il tipo e il nome specificati. In altre parole, get_or_insert() è equivalente 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 parola chiave da passare al costruttore della classe del modello se con il nome della chiave specificato, non esiste. La L'argomento parent è necessario se l'entità desiderata ha un 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, indipendentemente dal fatto che esista o sia stata creata dal metodo. Come per tutte le operazioni di Datastore, questo metodo può generare un TransactionFailedError se la transazione non è stata completata.

Model.all (keys_only=False)

Restituisce un Query che rappresenta tutte le entità del tipo corrispondente un modello di machine learning. I metodi dell'oggetto query possono applicare filtri e ordini di ordinamento alla query prima che venga eseguita. Per ulteriori informazioni, consulta la pagina della classe Query.

Argomenti

keys_only

Indica se la query deve restituire entità complete o solo chiavi. Query che le chiavi restituite vengono più veloce e 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 (che è implicita nell'utilizzo di questo metodo di classe).

args

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

kwds

Associazioni di parametri di parole 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 ()

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 modelli.

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 del modello include il tipo di entità dell'istanza insieme a 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. Chiamata a key() prima che l'istanza sia stata a un identificatore genera NotSavedError un'eccezione.

metti ()

Memorizza l'istanza del modello in Datastore. Se l'istanza del modello è appena creato e non è mai stato archiviato, questo metodo crea un nuovo nel datastore. In caso contrario, aggiorna l'entità di dati con i valori correnti delle proprietà.

Il metodo restituisce la chiave dell'entità memorizzata.

Se non è possibile eseguire il commit dei dati, genera una TransactionFailedError un'eccezione.

Argomenti

scadenza

Tempo massimo, in secondi, di attesa che Datastore restituisca un risultato prima di interrompere con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere modificato 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, riprovare l'operazione, provare un'altra operazione o aggiungere l'operazione a una coda di attività).

delete ()

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

Argomenti

scadenza

Tempo massimo, in secondi, di attesa che Datastore restituisca un risultato prima di interrompere con un errore. Accetta un valore intero o con virgola mobile. Non può essere impostato su un valore superiore al valore predefinito (60 secondi), ma può essere modificato 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, riprovare a eseguire l'operazione, provare un'operazione diversa o aggiungerla a una coda di attività).

is_saved ()

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

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

proprietà_dinamiche ()

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

parent ()

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

parent_key ()

Restituisce il Key dell'entità principale 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 Atom e Dati specifiche.

Nomi proprietà non consentiti

Datastore e la relativa API impongono diverse restrizioni sui nomi delle entità di Compute Engine e gli attributi di istanza del modello.

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

L'API del modello Python ignora tutti gli attributi su un elemento Model o Expando che iniziano con un trattino basso (_). La tua applicazione può utilizzare questi attributi per associare i dati agli oggetti del modello che non vengono salvati per il datastore.

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

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

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

I seguenti nomi di attributi sono riservati alla classe Model in l'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