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 automatica nella cache delle entità tramite l'API Memcache. Se attualmente utilizzi la libreria client di DB precedente, leggi la guida alla migrazione da DB a NDB
Il datastore di App Engine supporta un insieme fisso di tipi di valore per le proprietà su entità di dati.
Le classi
Property
possono definire nuovi tipi che vengono convertiti da e verso i tipi di valori sottostanti. I tipi di valori possono essere utilizzati direttamente con le proprietà dinamiche
Expando
e i
ListProperty
modelli di proprietà aggregate.
La seguente tabella descrive le classi di proprietà i cui valori corrispondono direttamente ai tipi di dati sottostanti. Ognuno di questi tipi di valori può essere utilizzato in una proprietà dinamica Espandio o in un tipo aggregato ListProperty.
Tipi di valori Datastore
I valori delle proprietà entità Datastore possono essere di uno dei seguenti tipi. Vedi sopra per un elenco delle classi
Property
corrispondenti da utilizzare con
le definizioni
Model
.
Ad eccezione dei tipi standard Python e users.User
, tutte le classi descritte in questa sezione sono fornite dal modulo google.appengine.ext.db
.
str
ounicode
-
Una stringa breve (massimo 1500 byte).
Si presuppone che un valore
str
sia codificato in testo con il codecascii
e che viene convertito in un valoreunicode
prima di essere archiviato. Il valore viene restituito dal datastore come valoreunicode
. Per le stringhe brevi che utilizzano altri codec, utilizza un valoreunicode
.Le stringhe brevi sono indicizzate dal datastore e possono essere utilizzate in filtri e ordinamenti. Per le stringhe di testo più lunghe di 1500 byte (non indicizzate), utilizza un'istanza
Text
. Per stringhe di byte non codificate più lunghe di 1500 byte (anche non indicizzate), utilizza un'istanzaBlob
. Per le stringhe di byte non testuali non codificati fino a 1500 byte (non caratteri) che devono essere indicizzate, utilizza un'istanzaByteString
.Proprietà del modello:
StringProperty
bool
-
Un valore booleano (
True
oFalse
).Proprietà del modello:
BooleanProperty
int
olong
-
Un valore intero, fino a 64 bit.
I valori
int
in Python vengono convertiti in valorilong
Python prima dello spazio di archiviazione. Un valore archiviato comeint
verrà restituito comelong
.Se viene assegnato un
long
di dimensioni superiori a 64 bit, vengono memorizzati solo i 64 bit meno significativi.Proprietà del modello:
IntegerProperty
float
-
Un numero con rappresentazione in virgola mobile.
Proprietà del modello:
FloatProperty
datetime.datetime
-
Data e ora. Consulta la documentazione del modulo
datetime
.Se il valore
datetime
ha un attributotzinfo
, verrà convertito nel fuso orario UTC per l'archiviazione. I valori provengono dal datastore in formato UTC, con un valoretzinfo
pari aNone
. Un'applicazione che richiede che i valori di data e ora siano in un determinato fuso orario deve impostare correttamentetzinfo
durante l'aggiornamento del valore e convertire i valori nel fuso orario quando si accede al valore.Alcune librerie utilizzano la variabile di ambiente
TZ
per controllare il fuso orario applicato ai valori data-ora. App Engine imposta questa variabile di ambiente su"UTC"
. Tieni presente che la modifica di questa variabile in un'applicazione non cambierà il comportamento di alcune funzioni data/ora, poiché le modifiche alle variabili di ambiente non sono visibili al di fuori del codice Python.Se converti i valori solo da e verso un determinato fuso orario, puoi implementare un valore
datetime.tzinfo
personalizzato per convertire i valori dal datastore:import datetime import time class Pacific_tzinfo(datetime.tzinfo): """Implementation of the Pacific timezone.""" def utcoffset(self, dt): return datetime.timedelta(hours=-8) + self.dst(dt) def _FirstSunday(self, dt): """First Sunday on or after dt.""" return dt + datetime.timedelta(days=(6-dt.weekday())) def dst(self, dt): # 2 am on the second Sunday in March dst_start = self._FirstSunday(datetime.datetime(dt.year, 3, 8, 2)) # 1 am on the first Sunday in November dst_end = self._FirstSunday(datetime.datetime(dt.year, 11, 1, 1)) if dst_start <= dt.replace(tzinfo=None) < dst_end: return datetime.timedelta(hours=1) else: return datetime.timedelta(hours=0) def tzname(self, dt): if self.dst(dt) == datetime.timedelta(hours=0): return "PST" else: return "PDT" pacific_time = datetime.datetime.fromtimestamp(time.mktime(utc_time.timetuple()), Pacific_tzinfo())
Consulta la documentazione del modulo
datetime
(tra cuidatetime.tzinfo
). Vedi anche il modulo di terze partipytz
, anche se tieni presente che la distribuzionepytz
include molti file.La classe delle proprietà del modello
DateTimeProperty
include funzionalità come la possibilità di utilizzare automaticamente la data e l'ora di archiviazione di un'istanza del modello. Queste sono caratteristiche del modello e non sono disponibili sul valore del datastore non elaborato (ad esempio in una proprietà dinamicaExpando
).Proprietà del modello:
DateTimeProperty
,DateProperty
,TimeProperty
list
-
Un elenco di valori, ognuno dei quali appartiene a uno dei tipi di dati supportati.
Quando
list
viene utilizzato come valore di una proprietà dinamicaExpando
, non può essere un elenco vuoto. Ciò è dovuto al modo in cui vengono archiviati i valori dell'elenco: quando una proprietà elenco non ha elementi, non ha alcuna rappresentazione nel datastore. Puoi utilizzare una proprietà statica e la classeListProperty
per rappresentare un valore di elenco vuoto per una proprietà.Proprietà del modello:
ListProperty
-
db.Key
-
La chiave per un'altra entità datastore.
Nota:le stringhe delle chiavi sono limitate a 1500 byte o meno.
m = Employee(name="Susan", key_name="susan5") m.put() e = Employee(name="Bob", manager=m.key()) e.put() m_key = db.Key.from_path("Employee", "susan5") e = Employee(name="Jennifer", manager=m_key)
Proprietà del modello:
ReferenceProperty
,SelfReferenceProperty
-
blobstore.BlobKey
-
Chiave per un valore dell'archivio BLOB generato dall'archivio quando viene caricato il valore.
Proprietà del modello:
blobstore.BlobReferenceProperty
-
users.User
-
Un utente con un Account Google.
Un valore
user.User
nel datastore non viene aggiornato se l'utente cambia il proprio indirizzo email. Per questo motivo, consigliamo vivamente di evitare di memorizzare unusers.User
come valoreUserProperty
, poiché include l'indirizzo email e l'ID univoco. Se un utente cambia l'indirizzo email e poi confronti il valoreuser.User
precedente e archiviato con il nuovo valoreuser.User
, questi dati non corrisponderanno. Utilizza invece il valoreuser_id()
del valoreuser.User
come identificatore univoco stabile dell'utente.Proprietà del modello:
UserProperty
- class Blob(arg=None)
-
Dati binari, come stringa di byte. Questa è una sottoclasse del tipo
str
integrato.Le proprietà BLOB non sono indicizzate e non possono essere utilizzate in filtri o ordinamenti.
Il blob è per i dati binari, come le immagini. Richiede un valore
str
, ma questo valore viene memorizzato come stringa di byte e non è codificato come testo. Utilizza un'istanzaText
per dati di testo di grandi dimensioni.Proprietà del modello:
BlobProperty
class MyModel(db.Model): blob = db.BlobProperty() m = MyModel() m.blob = db.Blob(open("image.png", "rb").read())
In XML, i blob sono codificati in base64 indipendentemente dal fatto che contengano o meno dati binari.
- class ByteString(arg)
-
Un valore blob breve (una "stringa di byte") di massimo 1500 byte. ByteString è una sottoclasse di
str
e prende un valorestr
non codificato come argomento al suo costruttore.Le stringhe di byte sono indicizzate dal datastore e possono essere utilizzate in filtri e ordinamenti. Per le stringhe di byte più lunghi di 1500 byte (che non sono indicizzate), utilizza un'istanza
Blob
. Per i dati di testo codificati, utilizzastr
(breve, indicizzata) oText
(lunga, non indicizzata).Proprietà del modello:
ByteStringProperty
- class Text(arg=None, encoding=None)
-
Una stringa lunga. Questa è una sottoclasse del tipo
unicode
integrato.arg un valore
unicode
ostr
. Se arg è unstr
, viene analizzato con la codifica specificata da encoding oascii
se non viene specificata alcuna codifica. Consulta l'elenco delle codifiche standard per i possibili valori per la codifica.A differenza di una proprietà entità il cui valore è semplice
str
ounicode
, una proprietà Text può contenere più di 1500 byte. Tuttavia, le proprietà del testo non sono indicizzate e non possono essere utilizzate in filtri o ordinamenti.Proprietà del modello:
TextProperty
class MyModel(db.Model): text = db.TextProperty() m = MyModel() m.text = db.Text(u"kittens") m.text = db.Text("kittens", encoding="latin-1")
- class Category(tag)
-
Una categoria o un "tag". Questa è una sottoclasse del tipo
unicode
integrato.Proprietà del modello:
CategoryProperty
class MyModel(db.Model): category = db.CategoryProperty() m = MyModel() m.category = db.Category("kittens")
Nel file XML, si tratta di un elemento Atom
Category
. - class Email(email)
-
Un indirizzo email. Questa è una sottoclasse del tipo
unicode
integrato.Né la classe della proprietà né la classe del valore eseguono la convalida degli indirizzi email, ma memorizzano solo il valore.
Proprietà del modello:
EmailProperty
class MyModel(db.Model): email_address = db.EmailProperty() m = MyModel() m.email_address = db.Email("larry@example.com")
Nel file XML, si tratta di un elemento
gd:email
. - class GeoPt(lat, lon=None)
-
Un punto geografico rappresentato da coordinate di latitudine e longitudine con rappresentazione in virgola mobile.
Proprietà del modello:
GeoPtProperty
Nel file XML, si tratta di un elemento
georss:point
. - class IM(protocollo, indirizzo=Nessuno)
-
Un handle di messaggistica immediata.
protocollo è l'URL canonico del servizio di messaggistica immediata. Alcuni valori possibili:
Protocollo Descrizione sip SIP/SEMPLICE xmpp XMPP/Jabber http://aim.com/ AIM http://icq.com/ ICQ http://messenger.msn.com/ MSN Messenger http://messenger.yahoo.com/ Yahoo Messenger http://sametime.com/ Lotus Sametime http://gadu-gadu.pl/ Gadu-Gadu sconosciuto Sconosciuto o non specificato address è l'indirizzo dell'handle.
Proprietà del modello:
IMProperty
class MyModel(db.Model): im = db.IMProperty() m = MyModel() m.im = db.IM("http://example.com/", "Larry97")
Nel file XML, si tratta di un elemento
gd:im
. - class Link(link)
-
Un URL completo. Questa è una sottoclasse del tipo
unicode
integrato.Proprietà del modello:
LinkProperty
class MyModel(db.Model): link = db.LinkProperty() m = MyModel() m.link = db.Link("http://www.google.com/")
Nel file XML, si tratta di un elemento Atom
Link
. - class PhoneNumber(phone)
-
Un numero di telefono leggibile. Questa è una sottoclasse del tipo
unicode
integrato.Proprietà del modello:
PhoneNumberProperty
class MyModel(db.Model): phone = db.PhoneNumberProperty() m = MyModel() m.phone = db.PhoneNumber("1 (206) 555-1212")
Nel file XML, si tratta di un elemento
gd.phoneNumber
. - class PostalAddress(indirizzo)
-
Un indirizzo postale. Questa è una sottoclasse del tipo
unicode
integrato.Proprietà del modello:
PostalAddressProperty
class MyModel(db.Model): address = db.PostalAddressProperty() m = MyModel() m.address = db.PostalAddress("1600 Ampitheater Pkwy., Mountain View, CA")
Nel file XML, si tratta di un elemento
gd:postalAddress
. - class Rating(rating)
-
Una valutazione fornita dall'utente per un determinato contenuto, sotto forma di numero intero compreso tra 0 e 100. Questa è una sottoclasse del tipo
long
integrato. La classe verifica che il valore sia un numero intero compreso tra 0 e 100 e genera unBadValueError
se il valore non è valido.Proprietà del modello:
RatingProperty
class MyModel(db.Model): rating = db.RatingProperty() m = MyModel() m.rating = db.Rating(97)
Nel file XML, si tratta di un elemento
gd:rating
.
Classi proprietà
Tutte le classi di proprietà del modello fornite da google.appengine.ext.db
sono sottoclassi della classe base Property
e supportano tutti gli argomenti del costruttore di base. Consulta la documentazione della classe base per informazioni su questi argomenti.
Il pacchetto google.appengine.ext.db
fornisce le seguenti classi di proprietà del modello:
- class BlobProperty(...)
-
Una raccolta non interpretata di dati binari.
I dati BLOB sono una stringa di byte. Per i dati di testo, che potrebbero comportare la codifica, utilizza
TextProperty
.Tipo di valore:
Blob
- class BooleanProperty(...)
-
Un valore booleano (
True
oFalse
).Tipo di valore:
bool
- class ByteStringProperty(verbose_name=None, ...)
-
Un valore blob breve (una "stringa di byte") di massimo 1500 byte.
I valori
ByteStringProperty
sono indicizzati e possono essere utilizzati nei filtri e nell'ordinamento.Come
StringProperty
, ma il valore non è codificato in alcun modo. I byte vengono memorizzati letteralmente.Se è richiesto
ByteStringProperty
, il valore non può essere una stringa vuota.Tipo di valore:
ByteString
- class CategoryProperty(...)
-
Una categoria o un "tag", una parola o una frase descrittiva.
Tipo di valore:
Category
- class DateProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)
-
Una data senza ora del giorno; consulta
DateTimeProperty
per ulteriori informazioni.Tipo di valore:
datetime.date
; convertito internamente indatetime.datetime
- class DateTimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)
-
Data e ora.
Se auto_now è
True
, il valore della proprietà viene impostato sull'ora attuale ogni volta che l'istanza del modello è archiviata nel datastore, sovrascrivendo il valore precedente della proprietà. È utile per monitorare la data e l'ora di "ultima modifica" per un'istanza di modello.Se auto_now_add è
True
, il valore della proprietà viene impostato sull'ora attuale la prima volta che l'istanza del modello viene archiviata nel datastore, a meno che alla proprietà non sia già stato assegnato un valore. È utile per archiviare la data e l'ora di "creazione" di un'istanza di modello.I valori di data e ora vengono memorizzati e restituiti nel fuso orario UTC. Consulta
datetime.datetime
per una discussione su come gestire i fusi orari.Tipo di valore:
datetime.datetime
- class EmailProperty(...)
-
Un indirizzo email.
Né la classe della proprietà né la classe del valore eseguono la convalida degli indirizzi email, ma memorizzano solo il valore.
Tipo di valore:
Email
- class FloatProperty(...)
-
Un numero con rappresentazione in virgola mobile.
Tipo di valore:
float
- class GeoPtProperty(...)
-
Un punto geografico rappresentato da coordinate di latitudine e longitudine con rappresentazione in virgola mobile.
Tipo di valore:
GeoPt
- class IMProperty(...)
-
Un handle di messaggistica immediata.
Tipo di valore:
IM
- class IntegerProperty(...)
-
Un valore intero, fino a 64 bit.
I valori
int
in Python vengono convertiti in valorilong
Python prima dello spazio di archiviazione. Un valore archiviato comeint
verrà restituito comelong
.Se viene assegnato un
long
di dimensioni superiori a 64 bit, vengono memorizzati solo i 64 bit meno significativi. - class LinkProperty(...)
-
Un URL completo.
Tipo di valore:
Link
- class ListProperty(item_type, verbose_name=None, default=None, ...)
-
Un elenco di valori del tipo specificato da item_type.
In una query, il confronto di una proprietà elenco con un valore esegue il test rispetto ai membri dell'elenco:
list_property
=
value
verifica se il valore compare in qualsiasi punto dell'elenco,list_property
<
value
verifica se uno dei membri dell'elenco è inferiore al valore specificato e così via.Una query non può confrontare due valori di un elenco. Non è possibile testare l'uguaglianza di due elenchi senza testare separatamente ogni elemento per l'appartenenza.
item_type è il tipo di elementi nell'elenco, come classe o tipo Python. Tutti gli elementi nel valore dell'elenco devono essere del tipo specificato. item_type deve essere uno dei tipi di valori datastore e non può essere
list
.Il valore di
ListProperty
non può essereNone
. Può, tuttavia, essere un elenco vuoto. QuandoNone
è specificato per l'argomento default (o quando l'argomento default non è specificato), il valore predefinito della proprietà è l'elenco vuoto.Suggerimento: poiché i tipi aggregati
ListProperty
non utilizzano le classiProperty
, le funzionalità delle classiProperty
, come i valori automatici e la convalida, non vengono applicate automaticamente ai membri del valore dell'elenco. Se vuoi convalidare il valore di un membro utilizzando una classeProperty
, puoi creare un'istanza della classe e chiamare il relativo metodovalidate()
sul valore.default è il valore predefinito per la proprietà list. Se
None
, l'elenco predefinito è vuoto. Una proprietà list può definire uno validator personalizzato per non consentire l'elenco vuoto.Consulta la pagina Modellazione dati per ulteriori informazioni su proprietà e valori degli elenchi.
Tipo di valore: un
list
di valori Python del tipo specificato - class PhoneNumberProperty(...)
-
Un numero di telefono leggibile.
Tipo di valore:
PhoneNumber
- class PostalAddressProperty(...)
-
Un indirizzo postale.
Tipo di valore:
PostalAddress
- class RatingProperty()
-
Una valutazione fornita dall'utente per un determinato contenuto, sotto forma di numero intero compreso tra 0 e 100.
Tipo di valore:
Rating
- class ReferenceProperty(reference_class=None, verbose_name=None, collection_name=None, ...)
-
Un riferimento a un'altra istanza del modello. Ad esempio, un riferimento può indicare una relazione di molti a uno tra il modello con la proprietà e il modello a cui fa riferimento la proprietà.
reference_class è la classe dell'istanza del modello a cui viene fatto riferimento. Se specificato, a questa proprietà possono essere assegnate solo le istanze del modello della classe. Se
None
, il valore di questa proprietà può essere qualsiasi istanza del modello.collection_name è il nome della proprietà da assegnare alla classe del modello di riferimento. Il valore della proprietà è un
Query
per tutte le entità che fanno riferimento all'entità. Se non è impostato alcun collection_name, viene utilizzatomodelname_set
(con il nome del modello di riferimento in lettere minuscole e l'aggiunta di_set
).Nota:è necessario impostare collection_name se sono presenti più proprietà all'interno dello stesso modello che fanno riferimento alla stessa classe del modello. In caso contrario, viene generato un valore
DuplicatePropertyError
quando vengono generati i nomi predefiniti.ReferenceProperty
fa riferimento e rimuove automaticamente le istanze del modello come valori di proprietà: un'istanza del modello può essere assegnata direttamente a una proprietà di riferimento e verrà utilizzata la sua chiave. Il valoreReferenceProperty
può essere utilizzato come se si trattasse di un'istanza del modello e l'entità datastore verrà recuperata e l'istanza del modello verrà creata quando viene utilizzata per la prima volta in questo modo. Le proprietà di riferimento non modificate non eseguono query per dati non necessari.class Author(db.Model): name = db.StringProperty() class Story(db.Model): author = db.ReferenceProperty(Author) story = db.get(story_key) author_name = story.author.name author = db.get(author_key) stories_by_author = author.story_set.get()
Come per un valore
Key
, è possibile che il valore di una proprietà di riferimento faccia riferimento a un'entità dati che non esiste. Se un'entità a cui viene fatto riferimento viene eliminata dal datastore, i riferimenti all'entità non vengono aggiornati. L'accesso a un'entità che non esiste genera unReferencePropertyResolveError
.L'eliminazione di un'entità non comporta l'eliminazione delle entità a cui fa riferimento una proprietà di riferimento.
Tipo di valore:
db.Key
- class SelfReferenceProperty(verbose_name=None, collection_name=None, ...)
-
Un riferimento a un'altra istanza del modello della stessa classe (vedi
ReferenceProperty
).Tipo di valore:
db.Key
- class StringListProperty(verbose_name=None, default=None, ...)
-
È simile a una proprietà list dei valori Python
str
ounicode
(basestring
). - class StringProperty(verbose_name=None, multiline=False, ...)
-
Una stringa breve. Prende un valore Python
str
ounicode
(basestring
) di massimo 1500 byte.I valori
StringProperty
sono indicizzati e possono essere utilizzati nei filtri e nell'ordinamento.Se multilinea è
False
, il valore non può includere caratteri di avanzamento riga. La libreriadjangoforms
lo utilizza per applicare una differenza tra i campi di testo e quelli dell'area di testo nel modello dei dati. Altri possono utilizzarlo per uno scopo simile.Se la proprietà della stringa è obbligatoria, il valore non può essere una stringa vuota.
- class TextProperty()
-
Una stringa lunga.
A differenza di
StringProperty
, un valoreTextProperty
può contenere più di 1500 byte. Tuttavia, i valoriTextProperty
non sono indicizzati e non possono essere utilizzati in filtri o ordinamenti.I valori
TextProperty
memorizzano il testo con una codifica del testo. Per i dati binari, utilizzaBlobProperty
.Se la proprietà di testo è obbligatoria, il valore non può essere una stringa vuota.
Tipo di valore:
Text
- class TimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)
-
Un'ora del giorno senza data. Prende un valore della libreria standard Python
datetime.time
; consultaDateTimeProperty
per ulteriori informazioni.Tipo di valore:
datetime.time
; convertito internamente indatetime.datetime
- class UserProperty(verbose_name=None, auto_current_user=False, auto_current_user_add=False, ...)
-
Importante: ti consigliamo vivamente di non archiviare un
UserProperty
, poiché include l'indirizzo email e l'ID univoco dell'utente. Se un utente cambia il proprio indirizzo email e confronti il valoreUser
precedente e archiviato con il nuovo valoreUser
, non corrisponderanno.Un utente con un Account Google.
Se auto_current_user è
True
, il valore della proprietà viene impostato sull'utente che ha eseguito l'accesso ogni volta che l'istanza del modello viene archiviata nel datastore, sovrascrivendo il valore precedente della proprietà. È utile per tenere traccia dell'utente che modifica un'istanza del modello.Se auto_current_user_add è
True
, il valore della proprietà viene impostato sull'utente che ha eseguito l'accesso la prima volta che l'istanza del modello viene archiviata nel datastore, a meno che alla proprietà non sia già stato assegnato un valore. È utile per tenere traccia dell'utente che crea un'istanza del modello, che potrebbe non essere lo stesso che la modifica in seguito.UserProperty non accetta un valore predefinito. I valori predefiniti vengono impostati al momento dell'importazione della classe del modello e, con l'importazione della memorizzazione nella cache potrebbe non essere l'utente che ha eseguito l'accesso.
Tipo di valore:
users.User