Tipi e classi di proprietà

Nota:gli sviluppatori che creano nuove applicazioni sono fortemente incoraggiati a utilizzare la libreria client NDB, che offre diversi vantaggi rispetto a questa libreria client, ad esempio la memorizzazione automatica nella cache 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 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 nei tipi di valori sottostanti e viceversa. I tipi di valori possono essere utilizzati direttamente con le proprietà dinamiche Expando e i modelli di proprietà aggregati ListProperty.

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

Tipi di valori Datastore

I valori delle proprietà delle entità Datastore possono essere di uno dei seguenti tipi. Consulta l'elenco riportato sopra per visualizzare le classi Property corrispondenti da utilizzare con le definizioni Model.

A parte i tipi standard di Python e users.User, tutte le classi descritte in questa sezione sono fornite dal modulo google.appengine.ext.db.

str o unicode

Una stringa breve (massimo 1500 byte).

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

Le stringhe brevi vengono indicizzate dal datastore e possono essere utilizzate nei filtri e negli ordinamenti. Per le stringhe di testo più lunghe di 1500 byte (che non sono indicizzate), utilizza un'istanza Text. Per le stringhe di byte non codificate più lunghe di 1500 byte (non indicizzate), utilizza un'istanza Blob. Per le stringhe di byte non codificate non testuali 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 memorizzato 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 rappresentazione in 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 datastore come UTC, con un tzinfo di None. Un'applicazione che richiede che i valori di data e ora si trovino in un determinato fuso orario deve impostare correttamente tzinfo 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 di data e 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 di data e ora, perché 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 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 (inclusa datetime.tzinfo). Consulta anche il modulo di terze parti pytz, anche se la distribuzione pytz contiene molti file.

La classe di proprietà del modello DateTimeProperty include funzionalità come la possibilità di utilizzare automaticamente la data e l'ora in cui viene memorizzata un'istanza del modello. Queste sono caratteristiche del modello e non sono disponibili sul valore del datastore non elaborato (ad esempio in una Expando proprietà dinamica).

Proprietà del modello: DateTimeProperty, DateProperty, TimeProperty

list

Un elenco di valori, ognuno 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. Ciò è dovuto al modo in cui vengono archiviati i valori di elenco: quando una proprietà di elenco non ha 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 per un'altra entità Datastore.

Nota:le stringhe chiave 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

La chiave per un valore Blobstore, generata da Blobstore quando il valore viene caricato.

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, ti consigliamo vivamente di evitare di memorizzare un users.User come valore UserProperty, perché include l'indirizzo email insieme all'ID univoco. Se un utente modifica l'indirizzo email e poi confronti il vecchio valore user.User memorizzato con il nuovo valore user.User, 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 integrato str.

Le proprietà dei blob non vengono indicizzate e non possono essere utilizzate nei filtri o negli ordinamenti.

Blob è per i dati binari, come le immagini. Accetta un valore str, ma questo valore viene memorizzato come stringa di byte e non è codificato come testo. Utilizza un'istanza Text per grandi quantità di dati di testo.

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

class ByteString(arg)

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

Le stringhe di byte sono indicizzate dal datastore e possono essere utilizzate nei filtri e negli ordinamenti. Per le 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 integrato unicode.

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

A differenza di una proprietà dell'entità il cui valore è un semplice str o unicode, una proprietà di testo può contenere più di 1500 byte. Tuttavia, le proprietà di testo non vengono indicizzate e non possono essere utilizzate nei filtri o negli 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". Si tratta di una sottoclasse del tipo integrato unicode.

Proprietà del modello: CategoryProperty

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

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

In XML, questo è un elemento Category Atom.

class Email(email)

Un indirizzo email. Si tratta di una sottoclasse del tipo integrato unicode.

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

In XML, questo è 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, questo è 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, questo è un elemento gd:im.

class Link(link)

Un URL completo. Si tratta di una sottoclasse del tipo integrato unicode.

Proprietà del modello: LinkProperty

class MyModel(db.Model):
    link = db.LinkProperty()

m = MyModel()
m.link = db.Link("http://www.google.com/")

In XML, questo è un elemento Link Atom.

class PhoneNumber(phone)

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

Proprietà del modello: PhoneNumberProperty

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

m = MyModel()
m.phone = db.PhoneNumber("1 (206) 555-1212")

In XML, questo è un elemento gd.phoneNumber.

class PostalAddress(address)

Un indirizzo postale. Si tratta di una sottoclasse del tipo integrato unicode.

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, questo è un elemento gd:postalAddress.

class Rating(rating)

Valutazione fornita dall'utente per un contenuto, come numero intero compreso tra 0 e 100. Si tratta di una sottoclasse del tipo integrato long. La classe verifica che il valore sia un numero intero compreso tra 0 e 100 e genera un'eccezione 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, questo è un elemento gd:rating.

Classi di 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. Per informazioni su questi argomenti, consulta la documentazione della classe 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 potrebbero 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 (una "stringa di byte") di massimo 1500 byte.

I valori ByteStringProperty vengono indicizzati e possono essere utilizzati nei filtri e negli ordinamenti.

Come StringProperty, tranne che il valore non è codificato in alcun modo. I byte vengono archiviati letteralmente.

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 ora del giorno; per ulteriori informazioni, vedi 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à. Ciò è 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 datastore, a meno che alla proprietà non sia già stato assegnato un valore. Ciò è utile per memorizzare la data e l'ora di creazione di un'istanza del modello.

I valori di data e ora vengono archiviati e restituiti utilizzando il fuso orario UTC. Consulta datetime.datetime per informazioni 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 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 memorizzato 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à elenco con un valore esegue il test sui membri dell'elenco: list_property = value verifica se il valore è presente in un punto qualsiasi 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 elenco. Non è possibile testare l'uguaglianza di due elenchi senza testare separatamente l'appartenenza di ogni elemento.

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

Il valore di un ListProperty non può essere None. Tuttavia, può essere un elenco vuoto. Quando None è specificato per l'argomento default (o quando l'argomento default non è specificato), il valore predefinito della proprietà è l'elenco vuoto.

Suggerimento:poiché i tipi di aggregazione ListProperty non utilizzano le classi Property, le funzionalità delle classi Property, come i valori automatici e la convalida, non vengono applicate automaticamente ai membri del valore dell'elenco. Se vuoi convalidare un valore membro utilizzando una classe Property, puoi creare un'istanza della classe e chiamare il relativo metodo validate() sul valore.

default è il valore predefinito per la proprietà elenco. Se None, il valore predefinito è un elenco vuoto. Una proprietà elenco può definire un validatore personalizzato per impedire l'elenco vuoto.

Per ulteriori informazioni su proprietà ed elenchi, consulta la pagina Modellazione dei dati.

Tipo di valore:un elenco Python list di valori 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()

Valutazione fornita dall'utente per un contenuto, come 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 del modello a cui viene fatto 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 viene fatto riferimento. Il valore della proprietà è un Query per tutte le entità che fanno riferimento all'entità. Se non è impostato alcun collection_name, viene utilizzato modelname_set (con il nome del modello a cui viene fatto riferimento in lettere minuscole e _set aggiunto).

Nota: collection_name deve essere impostato se all'interno dello 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 automaticamente riferimento alle istanze del modello e le dereferenzia 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 del modello e l'entità del datastore verrà recuperata e l'istanza del modello creata al primo utilizzo 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 un valore della proprietà di riferimento si riferisca a un'entità di dati inesistente. Se un'entità a cui viene fatto riferimento viene eliminata dal datastore, 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à elenco di Python str o unicode (basestring).

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

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

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

I valori StringProperty vengono indicizzati e possono essere utilizzati nei filtri e negli ordinamenti.

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

Se la proprietà stringa è obbligatoria, il suo 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ò superare i 1500 byte. Tuttavia, i valori TextProperty non vengono indicizzati e non possono essere utilizzati nei filtri o negli ordinamenti.

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

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

Tipo di valore: Text

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

Un orario del giorno senza una data. Accetta un valore datetime.time della libreria standard Python. Per saperne di più, 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 valore User memorizzato con il nuovo valore User, non corrisponderanno.

Un utente con un Account Google.

Se auto_current_user è True, il valore della proprietà viene impostato sull'utente attualmente connesso ogni volta che l'istanza del modello viene memorizzata nel datastore, sovrascrivendo il valore precedente della proprietà. È utile per monitorare quale utente modifica un'istanza del modello.

Se auto_current_user_add è True, il valore della proprietà viene impostato sull'utente attualmente connesso la prima volta che l'istanza del modello viene memorizzata nel datastore, a meno che alla proprietà non sia già stato assegnato un valore. Ciò è utile per monitorare l'utente che crea un'istanza del modello, che potrebbe non essere lo stesso utente che la modifica in un secondo momento.

UserProperty non accetta un valore predefinito. I valori predefiniti vengono impostati al primo import della classe del modello e, con la memorizzazione nella cache dell'importazione, potrebbero non corrispondere all'utente attualmente connesso.

Tipo di valore: users.User