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, 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 ListPropertymodelli 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.

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

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 o unicode

Una stringa breve (massimo 1500 byte).

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

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'istanza Blob. Per le stringhe di byte non testuali non codificati 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 int in Python vengono convertiti in valori long Python prima dello spazio di archiviazione. Un valore archiviato come int verrà restituito come long.

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 attributo tzinfo, verrà convertito nel fuso orario UTC per l'archiviazione. I valori provengono dal datastore in formato UTC, con un valore tzinfo pari a None. Un'applicazione che richiede che i valori di data e ora siano in un determinato fuso orario deve impostare correttamente tzinfo 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 cui datetime.tzinfo). Vedi anche il modulo di terze parti pytz, anche se tieni presente che la distribuzione pytz 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à dinamica Expando).

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à dinamica Expando, 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 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 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 un users.User come valore UserProperty, poiché include l'indirizzo email e l'ID univoco. Se un utente cambia l'indirizzo email e poi confronti il valore user.User precedente e archiviato con il nuovo valore user.User, questi dati non corrisponderanno. Utilizza invece il valore 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. 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'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 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 valore str 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, utilizza str (breve, indicizzata) o Text (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 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 possibili valori per la codifica.

A differenza di una proprietà entità il cui valore è semplice str o unicode, 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:

ProtocolloDescrizione
sipSIP/SEMPLICE
xmppXMPP/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
sconosciutoSconosciuto 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.

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 un BadValueError 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 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 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 in datetime.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 valori long Python prima dello spazio di archiviazione. Un valore archiviato come int verrà restituito come long.

Se viene assegnato un long di dimensioni superiori a 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 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ò essere None. Può, tuttavia, 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 aggregati 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 il valore di un 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à 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 utilizzato modelname_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 valore ReferenceProperty 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 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à list dei valori Python str o unicode (basestring).

Tipo di valore: un list di str o unicode valori

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

Una stringa breve. Prende un valore Python str o unicode (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 libreria djangoforms 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.

Tipo di valore: str o unicode

class TextProperty()

Una stringa lunga.

A differenza di StringProperty, un valore TextProperty può contenere più di 1500 byte. Tuttavia, i valori TextProperty 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, utilizza BlobProperty.

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; consulta DateTimeProperty per ulteriori informazioni.

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 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 valore User precedente e archiviato 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 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