Tipi e classi di proprietà

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, ad esempio la memorizzazione nella cache automatica delle entità tramite l'API Memcache. Se al momento utilizzi la libreria client DB precedente, leggi la guida alla migrazione da DB a NDB

Il datastore di App Engine supporta un insieme fisso di tipi di valori per le proprietà delle entità di dati. Le classi Property possono definire nuovi tipi che vengono convertiti ai tipi di valore sottostanti e da questi, mentre i tipi di valore possono essere utilizzati direttamente con le proprietà dinamiche Expando e i modelli di proprietà aggregate ListProperty.

La tabella seguente descrive le classi di proprietà i cui valori corrispondono direttamente ai tipi di dati sottostanti. Qualsiasi di questi tipi di valore può essere utilizzato in una proprietà dinamica Expando o in un tipo aggregato ListProperty.

Classe di proprietà	Tipo di valore	Ordinamento
IntegerProperty	int long (64 bit)	Numerico
FloatProperty	float	Numerico
BooleanProperty	bool	False < True
StringProperty	str unicode	Unicode (str viene trattato come ASCII)
TextProperty	db.Text	Nessuno
ByteStringProperty	ByteString	Ordine dei byte
BlobProperty	db.Blob	Nessuno
DateProperty TimeProperty DateTimeProperty	datetime.date datetime.time datetime.datetime	Cronologica
GeoPtProperty	db.GeoPt	Per latitudine, poi per longitudine
PostalAddressProperty	db.PostalAddress	Unicode
PhoneNumberProperty	db.PhoneNumber	Unicode
EmailProperty	db.Email	Unicode
UserProperty	users.User	Indirizzo email in ordine Unicode. Tieni presente che devi evitare di utilizzare UserProperty, come indicato nella nota in Descrizione della classe UserProperty.
IMProperty	db.IM	Unicode
LinkProperty	db.Link	Unicode
CategoryProperty	db.Category	Unicode
RatingProperty	db.Rating	Numerico
ReferenceProperty SelfReferenceProperty	db.Key	Per elementi del percorso (kind, identifier, kind, identifier...)
blobstore.BlobReferenceProperty	blobstore.BlobInfo	Ordine dei byte
ListProperty StringListProperty	list di un tipo supportato	Se in ordine crescente, per elemento minimo; se in ordine decrescente, per elemento massimo

Tipi di valori di Datastore

I valori delle proprietà delle entità del data store possono essere di uno dei seguenti tipi. Consulta la sezione precedente per un elenco delle classi Property corrispondente da utilizzare con le definizioni Model.

A parte i tipi standard di Python e users.User, tutti i tipi descritti in questa sezione sono forniti dal modulo google.appengine.ext.db.

str o unicode

Una stringa breve (massimo 1500 byte).

Si presume che un valore str sia un testo codificato con il codec ascii e venga convertito in un valore unicode prima di essere memorizzato. Il valore viene restituito dal datastore come valore unicode. Per stringhe brevi che utilizzano altri codec, utilizza un valore unicode.

Le stringhe brevi vengono indicizzate dal data store e possono essere utilizzate nei filtri e negli ordini di ordinamento. Per le stringhe di testo più lunghe di 1500 byte (che non vengono indicizzate), utilizza un'istanza Text. Per stringhe di byte non codificate più lunghe di 1500 byte (anche non indicizzate), utilizza un'istanza Blob. Per le stringhe di byte non codificate non di testo fino a 1500 byte (non caratteri) che devono essere indicizzate, utilizza un'istanza ByteString.

Proprietà del modello: StringProperty

bool

Un valore booleano (True o False).

Proprietà del modello: BooleanProperty

int o long

Un valore intero fino a 64 bit.

I valori di Python int vengono convertiti in valori di Python long prima dell'archiviazione. Un valore archiviato come int verrà restituito come long.

Se viene assegnato un long maggiore di 64 bit, vengono memorizzati solo i 64 bit meno significativi.

Proprietà del modello: IntegerProperty

float

Un numero con virgola mobile.

Proprietà del modello: FloatProperty

datetime.datetime

Una data e un'ora. Consulta la documentazione del modulo datetime.

Se il valore datetime ha un attributo tzinfo, verrà convertito nel fuso orario UTC per l'archiviazione. I valori vengono restituiti dal data store come UTC, con un tzinfo di None. Un'applicazione che ha bisogno che i valori di data e ora si trovino in un determinato fuso orario deve impostare tzinfo correttamente durante l'aggiornamento del valore e convertire i valori nel fuso orario quando 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 cambia il comportamento di alcune funzioni relative a data e ora, perché le modifiche alle variabili di ambiente non sono visibili al di fuori del codice Python.

Se converti i valori solo verso e da un determinato fuso orario, puoi implementare un datetime.tzinfo personalizzato per convertire i valori dal data store:

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 (incluso datetime.tzinfo). Consulta anche il modulo di terze parti pytz, anche se tieni presente che la distribuzione di pytz contiene molti file.

La DateTimeProperty classe della proprietà del modello include funzionalità come la possibilità di utilizzare automaticamente la data e l'ora di archiviazione di un'istanza del modello. Si tratta di funzionalità del modello e non sono disponibili nel valore del datastore non elaborato (ad esempio in una proprietà dinamica Expando ).

Proprietà del modello: DateTimeProperty, DateProperty, TimeProperty

list

Un elenco di valori, ciascuno dei quali è di uno dei tipi di dati supportati.

Quando un list viene utilizzato come valore di una proprietà dinamica Expando non può essere un elenco vuoto. Questo accade a causa del modo in cui vengono archiviati i valori dell'elenco: quando una proprietà elenco non contiene elementi, non ha alcuna rappresentazione nel datastore. Puoi utilizzare una proprietà statica e la classe ListProperty per rappresentare un valore di elenco vuoto per una proprietà.

Proprietà del modello: ListProperty

db.Key

La chiave di un'altra entità del data store.

Nota:le stringhe chiave sono limitate a un massimo di 1500 byte.

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

La chiave di un valore dell'archivio BLOB, generata dall'archivio BLOB al momento del caricamento del valore.

Proprietà del modello: blobstore.BlobReferenceProperty

users.User

Un utente con un Account Google.

Un valore user.User nel data store non viene aggiornato se l'utente cambia il proprio indirizzo email. Per questo motivo, ti consigliamo vivamente di evitare di memorizzare un users.User come valore UserProperty, in quanto include l'indirizzo email insieme all'ID univoco. Se un utente modifica l'indirizzo email e poi confronti il vecchio user.User archiviato con il nuovo valore user.User, i valori non corrisponderanno. Utilizza invece user_id() del valore user.User come identificatore univoco stabile dell'utente.

Proprietà del modello: UserProperty

class Blob(arg=None)

Dati binari, come stringa di byte. Si tratta di una sottoclasse del tipo str integrato.

Le proprietà blob non sono indicizzate e non possono essere utilizzate in filtri o ordini di ordinamento.

Blob è destinato ai 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'istanza Text 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 base 64, indipendentemente dal fatto che contengano o meno dati binari.

class ByteString(arg)

Un valore blob breve ("stringa di byte") di massimo 1500 byte. ByteString è una sottoclasse di str, e accetta un valore str non codificato come argomento del suo costruttore.

I ByteString vengono indicizzati dal datastore e possono essere utilizzati nei filtri e negli ordini di ordinamento. Per stringhe di byte più lunghe di 1500 byte (che non sono indicizzate), utilizza un'istanza Blob. Per i dati di testo codificati, utilizza str (breve, indicizzato) o Text (lungo, non indicizzato).

Proprietà del modello: ByteStringProperty

class Text(arg=None, encoding=None)

Una stringa lunga. Si tratta di una sottoclasse del tipo unicode integrato.

arg un valore unicode o str. Se arg è un str, viene analizzato con la codifica specificata da encoding, oppure ascii se non viene specificata alcuna codifica. Consulta l'elenco delle codificazioni standard per conoscere i possibili valori per encoding.

A differenza di una proprietà entità il cui valore è un semplice str o unicode, una proprietà di testo può avere una lunghezza superiore a 1500 byte. Tuttavia, le proprietà di testo non vengono indicizzate e non possono essere utilizzate nei filtri o negli ordini di ordinamento.

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". Si tratta di una sottoclasse del tipo unicode integrato.

Proprietà del modello: CategoryProperty

class MyModel(db.Model):
    category = db.CategoryProperty()

m = MyModel()
m.category = db.Category("kittens")

In XML, si tratta di un elemento Atom Category.

class Email(email)

Un indirizzo email. Si tratta di 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("[e-mail]")

In XML, si tratta di un elemento gd:email.

class GeoPt(lat, lon=None)

Un punto geografico rappresentato da coordinate di latitudine e longitudine in virgola mobile.

Proprietà del modello: GeoPtProperty

In XML, si tratta di un elemento georss:point.

class IM(protocol, address=None)

Un handle di messaggistica istantanea.

protocol è l'URL canonico del servizio di messaggistica istantanea. Alcuni valori possibili:

Protocollo	Descrizione
sip	SIP/SIMPLE
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")

In XML, si tratta di un elemento gd:im.

class Link(link)

Un URL completo. Si tratta di 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/")

In XML, si tratta di un elemento Atom Link.

class PhoneNumber(phone)

Un numero di telefono leggibile. Si tratta di una sottoclasse del tipo unicode integrato.

Proprietà del modello: PhoneNumberProperty

class MyModel(db.Model):
    phone = db.PhoneNumberProperty()

m = MyModel()
m.phone = db.PhoneNumber("1 [phone]")

In XML, si tratta di un elemento gd.phoneNumber.

class PostalAddress(address)

Un indirizzo postale. Si tratta di 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")

In XML, si tratta di un elemento gd:postalAddress.

class Rating(rating)

Una valutazione fornita dall'utente per un contenuto, sotto forma di numero intero compreso tra 0 e 100. Si tratta di una sottoclasse del tipo long integrato. La classe convalida che il valore sia un numero intero compreso tra 0 e 100 e genera un messaggio di errore BadValueError se il valore non è valido.

Proprietà del modello: RatingProperty

class MyModel(db.Model):
    rating = db.RatingProperty()

m = MyModel()
m.rating = db.Rating(97)

In XML, si tratta di un elemento gd:rating.

Classi di proprietà

Tutte le classi di proprietà del modello fornite da google.appengine.ext.db sono sottoclassi della classe di base Property, e supportano tutti gli argomenti del costruttore di base. Per informazioni su questi argomenti, consulta la documentazione della classe di base.

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 possono comportare la codifica, utilizza TextProperty.

Tipo di valore: Blob

class BooleanProperty(...)

Un valore booleano (True o False).

Tipo di valore: bool

class ByteStringProperty(verbose_name=None, ...)

Un valore blob breve ("stringa di byte") di massimo 1500 byte.

I valori ByteStringProperty sono indicizzati e possono essere utilizzati nei filtri e negli ordini di ordinamento.

Come StringProperty, a differenza che il valore non viene codificato in alcun modo. I byte vengono memorizzati in modo letterale.

Se ByteStringProperty è obbligatorio, 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 un'ora del giorno. Per ulteriori informazioni, consulta DateTimeProperty.

Tipo di valore: datetime.date; convertito internamente in datetime.datetime

class DateTimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

Una data e un'ora.

Se auto_now è True, il valore della proprietà viene impostato sull'ora corrente ogni volta che l'istanza del modello viene memorizzata nel datastore, sovrascrivendo il valore precedente della proprietà. Questo è utile per monitorare la data e l'ora dell'ultima modifica di un'istanza del modello.

Se auto_now_add è True, il valore della proprietà viene impostato sull'ora corrente la prima volta che l'istanza del modello viene memorizzata nel data store, a meno che alla proprietà non sia già stato assegnato un valore. Questo è utile per memorizzare una data e un'ora "create" per un'istanza del modello.

I valori data/ora vengono archiviati e restituiti utilizzando il 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 virgola mobile.

Tipo di valore: float

class GeoPtProperty(...)

Un punto geografico rappresentato da coordinate di latitudine e longitudine in virgola mobile.

Tipo di valore: GeoPt

class IMProperty(...)

Un handle di messaggistica istantanea.

Tipo di valore: IM

class IntegerProperty(...)

Un valore intero fino a 64 bit.

I valori di Python int vengono convertiti in valori di Python long prima dell'archiviazione. Un valore archiviato come int verrà restituito come long.

Se viene assegnato un long maggiore di 64 bit, vengono memorizzati solo i 64 bit meno significativi.

Tipo di valore: int o long

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à dell'elenco con un valore esegue il test sugli elementi dell'elenco: list_property = value verifica se il valore compare in un punto qualsiasi dell'elenco, list_property < value verifica se uno degli elementi dell'elenco è inferiore al valore specificato e così via.

Una query non può confrontare due valori di elenco. Non è possibile verificare l'uguaglianza di due elenchi senza verificare separatamente l'appartenenza di ciascun elemento.

item_type è il tipo di elementi nell'elenco, come tipo o classe Python. Tutti gli elementi del valore dell'elenco devono essere del tipo specificato. tipo_elemento deve essere uno dei tipi di valore del data store e non può essere list.

Il valore di un ListProperty non può essere None. Tuttavia, può essere un elenco vuoto. Quando viene specificato None 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 classi Property, le funzionalità della classe Property, come i valori automatici e la convalida, non vengono applicate automaticamente ai membri del valore dell'elenco. Se vuoi convalidare un valore dell'elemento utilizzando una classe Property, puoi istanziare la classe e chiamare il relativo metodo validate() sul valore.

default è il valore predefinito per la proprietà dell'elenco. Se None, il valore predefinito è un elenco vuoto. Una proprietà di elenco può definire un convalidatore personalizzato per non consentire l'elenco vuoto.

Per ulteriori informazioni su proprietà e valori degli elenchi, consulta la pagina Modellazione dei dati.

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 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 many-to-one tra il modello con la proprietà e il modello a cui fa riferimento la proprietà.

reference_class è la classe del modello dell'istanza di modello a cui si fa riferimento. Se specificato, a questa proprietà possono essere assegnate solo istanze del modello della classe. Se None, qualsiasi istanza del modello può essere il valore di questa proprietà.

collection_name è il nome della proprietà da assegnare alla classe del modello a cui si fa riferimento. Il valore della proprietà è un valore Query per tutte le entità che fanno riferimento all'entità. Se non è impostato collection_name, viene utilizzato modelname_set (con il nome del modello a cui si fa riferimento in lettere minuscole e _set aggiunto).

Nota: collection_name deve essere impostato se nello stesso modello sono presenti più proprietà che fanno riferimento alla stessa classe di modello. In caso contrario, verrà generato un DuplicatePropertyError quando vengono generati i nomi predefiniti.

ReferenceProperty fa riferimento e dereferisce automaticamente le istanze del modello come valori delle proprietà: un'istanza del modello può essere assegnata direttamente a una proprietà di riferimento e verrà utilizzata la relativa chiave. Il valore ReferenceProperty può essere utilizzato come se fosse un'istanza di modello e l'entità del datastore verrà recuperata e l'istanza di modello creata la prima volta che viene utilizzata in questo modo. Le proprietà di riferimento non toccate 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 un valore della proprietà di riferimento faccia riferimento a un'entità di dati inesistente. Se un'entità a cui viene fatto riferimento viene eliminata dal data store, i riferimenti all'entità non vengono aggiornati. L'accesso a un'entità inesistente genera un ReferencePropertyResolveError.

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à di elenco di valori str o unicode (basestring) di Python.

Tipo di valore: un list di valori di Python str o unicode

class StringProperty(verbose_name=None, multiline=False, ...)

Una stringa breve. Accetta un valore str o unicode (basestring) di Python di massimo 1500 byte.

I valori StringProperty sono indicizzati e possono essere utilizzati nei filtri e negli ordini di ordinamento.

Se multiline è False, il valore non può includere caratteri di avanzamento riga. La libreria djangoforms lo utilizza per applicare una differenza tra i campi di testo e i campi textarea nel modello di dati e altri possono utilizzarlo per uno scopo simile.

Se la proprietà stringa è obbligatoria, il relativo valore non può essere una stringa vuota.

Tipo di valore: str o unicode

class TextProperty()

Una stringa lunga.

A differenza di StringProperty, un valore TextProperty può avere una lunghezza superiore a 1500 byte. Tuttavia, i valori TextProperty non sono indicizzati e non possono essere utilizzati nei filtri o negli ordini di ordinamento.

I valori TextProperty memorizzano il testo con una codifica di testo. Per i dati binari, utilizza BlobProperty.

Se la proprietà di testo è obbligatoria, il relativo 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 una data. Accetta un valore datetime.time della libreria standard di Python. Per ulteriori informazioni, consulta DateTimeProperty.

Tipo di valore: datetime.time; convertito internamente in datetime.datetime

class UserProperty(verbose_name=None, auto_current_user=False, auto_current_user_add=False, ...)

Importante: ti consigliamo vivamente di non memorizzare un UserProperty, poiché include l'indirizzo email e l'ID univoco dell'utente. Se un utente cambia il proprio indirizzo email e confronti il vecchio User memorizzato con il nuovo valore User, i valori 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 corrente ogni volta che l'istanza del modello viene memorizzata nel data store, sovrascrivendo il valore precedente della proprietà. Questo è utile per monitorare quale utente modifica un'istanza del modello.

Se auto_current_user_add è True, il valore della proprietà viene impostato sull'utente che ha eseguito l'accesso al momento la prima volta che l'istanza del modello viene memorizzata nel data store, a meno che alla proprietà non sia già stato assegnato un valore. Questo è utile per monitorare l'utente che crea un'istanza del modello, che potrebbe non essere lo stesso che la modifica in un secondo momento.

UserProperty non accetta un valore predefinito. I valori predefiniti vengono impostati alla prima importazione della classe del modello e, con la memorizzazione nella cache dell'importazione, potrebbero non essere quelli dell'utente che ha eseguito l'accesso.

Tipo di valore: users.User