Classe modello NDB

Una classe che eredita dalla classe Model rappresenta la struttura delle entità archiviate nel datastore. Le applicazioni definiscono le classi del modello per indicare della struttura delle loro entità, quindi crea un'istanza per le classi di modelli per creare entità. Tutte le classi devono ereditare (direttamente o indirettamente) dal modello.

In questa pagina è disponibile la documentazione di riferimento dell'API. Per una panoramica, consulta Entità e chiavi NDB.

Introduzione

Una classe che eredita da Model descrive le entità Datastore.

Tutte le classi di modelli devono ereditare (direttamente o indirettamente) da Model. È possibile utilizzare assegnazioni semplici nella definizione della classe del modello per dichiararne la struttura:

from google.appengine.ext import ndb

class Person(ndb.Model):
  name = ndb.StringProperty()
  age = ndb.IntegerProperty()

Ora possiamo creare un'entità Person e scriverla in Datastore:

p = Person(name='Arthur Dent', age=42)
k = p.put()

Il valore restituito da put() è un Chiave, che può essere utilizzata per recuperare in seguito: 

p2 = k.get()
p2 == p  # Returns True

Per aggiornare un'entità, è sufficiente modificarne gli attributi e riscriverla Tieni presente che la chiave rimane invariata:

p2.name = 'Arthur Philip Dent'
p2.put()

Possiamo anche eliminare un'entità (utilizzando la chiave):

k.delete()

Le definizioni delle proprietà nel corpo della classe indicano al sistema i nomi e i tipi di campi da archiviare in Datastore, sia devono essere indicizzati, il loro valore predefinito e altro ancora. Esistono molti tipi di proprietà diversi.

kind è in genere uguale al nome della classe (escluso il nome del modulo o di qualsiasi altro ambito principale). Per eseguire l'override del tipo (utile per le modifiche dello schema), definisci un metodo di classe denominato _get_kind(), come segue: 

  class MyModel(ndb.Model):
    @classmethod
    def _get_kind(cls):
      return 'AnotherKind'

Un'applicazione non deve definire due classi di modelli dello stesso tipo, anche se si trovano in moduli diversi. I tipi di applicazione sono considerata uno "spazio dei nomi" globale.

Model le sottoclassi possono definire pre-chiamata e post-chiamata hook per la maggior parte delle operazioni (get, put, delete, allo allo_id).

Costruttore

In genere, un'applicazione non chiama Model(), ma è probabile che chiamI il costruttore di una classe che eredita da Model. In questo modo viene creata una nuova istanza del modello, nota anche come entità.

L'entità appena creata non viene scritta automaticamente in Datastore. A tale scopo, deve essere scritto in Datastore utilizzando un modello chiamata a put().

Argomenti:

Le sottoclassi di Model supportano questi argomenti delle parole chiave:

chiave
Istanza chiave per questo modello. Se viene utilizzato il parametro key, id e parent devono essere None (il valore predefinito).
id
ID chiave per questo modello. Se viene utilizzato id, la chiave deve essere None (il valore predefinito).
padre
Istanza chiave per il modello padre o None per uno di primo livello. Se viene utilizzato parent, key deve essere None.
spazio dei nomi
Spazio dei nomi da utilizzare per questa entità oppure None (predefinito) per utilizzare lo spazio dei nomi corrente. Se viene utilizzato namespace, il valore di key deve essere None.

Un'applicazione può anche utilizzare argomenti delle parole chiave mappati agli proprietà. Ad esempio, funziona quanto segue:

class Person(ndb.Model):
  name = StringProperty()
  age = IntegerProperty()

p = Person(name='Arthur Dent', age=42)

Non puoi definire facilmente una proprietà denominata "key", "id", "parent" o "namespace". Se passi, ad esempio, key="foo" in un costruttore o populate(), imposta la chiave dell'entità, non una attributo di proprietà denominato "key".

Nota: Se esegui l'override del costruttore in una sottoclasse del modello, tieni presente che viene chiamato anche implicitamente, in alcuni casi, e assicurati che supporta queste chiamate. Quando un'entità viene letta da Datastore, viene creata innanzitutto un'entità vuota chiamando il costruttore argomenti, dopo i quali i valori della chiave e della proprietà vengono impostati uno per uno. Quando get_or_insert() o get_or_insert_async() crea una nuova istanza, passa **constructor_args al costruttore e imposta la chiave in seguito.

Metodi di classe

allocate_ids(size=None, max=None, parent=None, **ctx_options)

Alloca un intervallo di ID chiave per questa classe di modello.

Argomenti

size
Numero di ID da assegnare. Puoi specificare size o max, non entrambi.
max
ID massimo da allocare. size oppure max, non entrambi.
padre
Chiave padre per la quale verranno assegnati gli ID.
**ctx_options
Opzioni di contesto

Restituisce una tupla con (start, end) per l'intervallo allocato (inclusi).

Un'applicazione non può chiamare allocate_ids() in una transazione.

allocate_ids_async(size=nessuna, max=nessuna, parent=nessuna, **ctx_options)

Versione asincrona di allocate_ids.

Restituisce un oggetto Future il cui risultato è un tupla con (start, end) per l'intervallo allocato, inclusive.

get_by_id(id, parent=None, app=None, namespace=None, **ctx_options)
Restituisce un'entità in base all'ID. Si tratta solo di una rappresentazione abbreviata di Key(cls, id).get().

Argomenti

id
Un ID chiave di tipo stringa o intero.
padre
Chiave padre del modello da ottenere.
app (argomento parola chiave)
ID dell'app. Se non specificato, vengono recuperati i dati per l'app corrente.
namespace (argo parola chiave)
Spazio dei nomi. Se non specificato, vengono recuperati i dati per lo spazio dei nomi predefinito.
**ctx_options
Opzioni di contesto

Restituisce un'istanza di modello o None se non trovata.

get_by_id_async(id, parent=Nessuno, app=Nessuna, namespace=Nessuno, **ctx_options)
Versione asincrona di get_by_id.

Restituisce un oggetto Future il cui risultato è un'istanza del modello o None se non trovato.

get_or_insert(key_name, parent=None, app=None, namespace=None, context_options=None, **constructor_args)
Recupera dal punto di vista transazionale un'entità esistente o ne crea una nuova.

Argomenti

key_name
Un nome chiave (ovvero un ID chiave di stringa) da recuperare o creare.
parent
Chiave dell'entità padre, se presente.
app
ID dell'app. Se non specificato, vengono recuperati i dati per l'app corrente.
namespace
Spazio dei nomi. Se non specificato, vengono recuperati i dati per lo spazio dei nomi predefinito.
context_options
Opzioni di contesto

Questa funzione accetta anche argomenti di parole chiave da passare al costruttore della classe del modello se non esiste già un'istanza per il nome della chiave specificato. Se un'istanza con l'oggetto key_name e l'istanza padre esiste già, questi argomenti verranno ignorati.

Restituisce l'istanza esistente della classe Model con il nome della chiave e il valore parent specificati oppure una nuova appena creata.

Questa funzione utilizza una transazione. Se il codice che chiama questa funzione è già in una transazione, questa funzione tenta di riutilizzare la transazione esistente. Se il gruppo di entità di questa funzione non è compatibile con il modello transazione, questo può causare un errore.

get_or_insert_async(key_name, parent=None, app=None, namespace=None, context_options=None, **constructor_args)

Questa è la versione asincrona di get_or_insert.

Restituisce un oggetto Future il cui risultato è un'istanza esistente della classe Model con il nome della chiave e il valore padre specificati o una nuova appena creata.

query([filter1, filter2, ...,] predecessore=nessuno, app=None, namespace=None, filters=None, orders=None, default_options=None, projection=Nessuna distinct=False group_by=Nessuno)

Crea un oggetto Query per questa classe, come descritto in Query.

L'argomento parola chiave distinct è un'abbreviazione di group_by = come la proiezione del testo. Tutti gli altri argomenti delle parole chiave vengono passati Costruttore di query.

Se vengono forniti argomenti posizionali, vengono utilizzati per impostare i filtri iniziali.

Restituisce un oggetto Query.

Metodi istanza

populate(**constructor_options)

Imposta i valori delle proprietà dell'entità. I relativi argomenti delle parole chiave riconoscere automaticamente i nomi delle proprietà, del costruttore.

put(**ctx_options)

Scrive i dati dell'entità in Datastore. Resi la chiave dell'entità.

Argomenti

**ctx_options
Opzioni di contesto
put_async(**ctx_options)

Scrive i dati dell'entità in modo asincrono nel Datastore. Restituisce un Future oggetto. Il risultato dell'oggetto Future sarà la chiave dell'entità.

Argomenti

**ctx_options
Opzioni contestuali
to_dict(include=all, excluded=None)

Restituisce un dict contenente la proprietà del modello e i relativi valori. Valori della proprietà per StructuredProperty e LocalStructuredProperty sono ricorsivo convertiti in dizionari.

Argomenti:

include
Elenco facoltativo di strutture da includere. Valore predefinito: tutti.
escludi
Elenco facoltativo di proprietà da escludere. In caso di sovrapposizione tra include e escludi, quindi excluded "vittorie".

Nota: se il valore di una proprietà è un oggetto modificabile (ad es. un elenco che rappresenta una proprietà ripetuta, oppure un dettato o elenco memorizzato in un JsonProperty), a meno che il valore viene convertito esplicitamente (ad es. nel caso di a StructuredProperty), viene restituito lo stesso oggetto nel ditto memorizzato nell'entità. In questi casi, la mutazione del dizionario comporterà la mutazione dell'entità e viceversa.

Dati istanza

chiave
Proprietà speciale per memorizzare la chiave del modello.

Metodi di hook

La sottoclasse Model di un'applicazione può definire uno o più di questi metodi come "hook" prima o dopo l'operazione di machine learning. Ad esempio, per eseguire del codice prima di ogni "get", definisci il metodo _pre_get_hook() della sottoclasse del modello. Per consigli sulla scrittura di funzioni di hook, consulta Model Hooks.

@classmethod
_pre_allocate_ids_hook(cls, size, max, parent)
Hook eseguito prima allocate_ids()
@classmethod
_post_allocate_ids_hook(cls, size, max, parent, future)
Hook eseguito dopo allocate_ids()
@classmethod
_pre_delete_hook(cls, key)
Hook eseguito prima delete()
@classmethod
_post_delete_hook(cls, key, future)
Hook eseguito dopo delete()
@classmethod
_pre_get_hook(cls, key)
Hook eseguito prima Key.get() durante la ricezione un'entità di questo modello.
@classmethod
_post_get_hook(cls, key, futuro)
Hook che viene eseguito dopo Key.get() quando si ottiene un'entità di questo modello.
_pre_put_hook(self)
Hook eseguito prima put()
_post_put_hook(self, future)
Hook che segue put()

Introspezione

Puoi utilizzare questi metodi per ispezionare le proprietà e la configurazione di un determinato modello. Questo è utile se stai scrivendo una libreria o una funzione che accetta più tipi di modelli.

Ricerca per tipo

Ogni modello ha un kind che corrisponde di solito al nome della classe, a meno che con override. Puoi utilizzare il tipo per trovare la classe del modello associata utilizzando _lookup_model. 

class Animal(ndb.Model):
    type = ndb.StringProperty()

print Animal._get_kind()  # 'Animal'
print ndb.Model._lookup_model('Animal')  # class Animal

Tieni presente che _lookup_model funziona solo per le classi di modelli già importate dall'applicazione.

Proprietà

Puoi ottenere un elenco di tutte le proprietà associate a un modello utilizzando _properties. 

class User(ndb.Model):
    name = ndb.StringProperty()
    email = ndb.StringProperty()

print User._properties
# {'email': StringProperty('email'), 'name': StringProperty('name')}

_properties funziona anche per le istanze Expando. 

class Example(ndb.Expando):
  pass

e = Example()
e.foo = 1
e.bar = 'blah'
e.tags = ['exp', 'and', 'oh']
print e._properties
# {'foo': GenericProperty('foo'), 'bar': GenericProperty('bar'),
# 'tags': GenericProperty('tags', repeated=True)}

Le istanze della proprietà possono essere esaminate. Le opzioni fornite al costruttore sono disponibili come proprietà con prefisso _. 

print User._properties['email']._name  # 'email'
print User._properties['email']._required  # False
print User._properties['email']._default  # None
print User._properties['email']._choices  # None
print User._properties['email']._compressed  # False
print User._properties['email']._indexed  # True
print User._properties['email']._compressed  # False
print User._properties['email']._repeated  # False
print User._properties['email']._verbose_name  # None
print isinstance(User._properties['email'], ndb.StringProperty)  # True

Alias del metodo

Ogni metodo della classe Model ha un alias con prefisso _. Ad esempio: _put() equivale a put(). Ciò significa che puoi avere proprietà con nomi in conflitto con i nomi dei metodi, a condizione che tu utilizzi sempre il prefisso _ di machine learning. Tuttavia, tieni presente che non puoi specificare proprietà denominate key, parent o id nel costruttore. 

class MyModel(ndb.Model):
    put = ndb.StringProperty()
    query = ndb.StringProperty()
    key = ndb.StringProperty()

entity = MyModel()
entity.put = '1'
entity.query = '2'
entity.key = '3'

entity._put()
print entity
# MyModel(key=Key('MyModel', ...), put=u'1', query=u'2', key=u'3')

print MyModel._query().fetch()
# same as above.

Se crei librerie di terze parti che interagiscono con modelli arbitrari, ti consigliamo di utilizzare i metodi con prefisso _.