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 nella cache automatica delle entità tramite l'API Memcache. Se attualmente utilizzi la libreria client DB precedente, leggi la Guida alla migrazione dal database a NDB

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

La tabella seguente descrive le classi di proprietà i cui valori corrispondono direttamente ai tipi di dati sottostanti. Tutti questi tipi di valori possono essere utilizzati in una proprietà dinamica espandibile o in un tipo di aggregazione ListProperty.

Classe 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 Nessuna esperienza
ByteStringProperty ByteString
Ordine byte
BlobProperty db.Blob Nessuna esperienza
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 dovresti evitare di utilizzare UserProperty, in base alla nota 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,
kind, identifier...)
blobstore.BlobReferenceProperty blobstore.BlobInfo Ordine byte
ListProperty
StringListProperty
list di un tipo supportato Se crescente, per minimo elemento;
se decrescente, per elemento più grande

Tipi di valori Datastore

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

Oltre ai tipi di 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 presume che un valore str sia codificato in testo 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 con altri codec, utilizza un valore unicode.

Le stringhe brevi vengono indicizzate dal datastore e possono essere utilizzate nei filtri e nell'ordinamento. Per le stringhe di testo più lunghe di 1500 byte (non indicizzate), utilizza un'istanza Text. Per le 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

Valore intero, fino a 64 bit.

I valori int Python vengono convertiti in valori 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 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 provengono dal datastore in formato UTC, con un valore tzinfo pari a None. Un'applicazione che richiede che i valori di data e ora si trovino in un determinato fuso orario devono 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 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 cambia il comportamento di alcune funzioni data/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 (incluso datetime.tzinfo). Vedi anche il modulo di terze parti pytz, anche se tieni presente che la distribuzione pytz ha molti file.

La classe della 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 funzionalità del modello e non sono disponibili nel valore non elaborato del datastore (ad esempio in una proprietà dinamica Expando).

Proprietà del modello: DateTimeProperty, DateProperty, TimeProperty

list

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

Quando viene utilizzato un list come valore di una proprietà dinamica Expando, non può essere un elenco vuoto. Ciò è dovuto al modo in cui vengono archiviati i valori 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 elenco vuoto per una proprietà.

Proprietà del modello: ListProperty

db.Key

La chiave di un'altra entità datastore.

Nota: le stringhe di chiave hanno un limite 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 per un valore Blobstore, generata dall'archivio BLOB 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 l'indirizzo email. Per questo motivo, ti consigliamo vivamente di evitare di archiviare 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 user.User archiviato con il nuovo valore di user.User, le modifiche non corrisponderanno. Utilizza invece user_id() del valore di user.User come identificatore univoco stabile dell'utente.

Proprietà del modello: UserProperty

class Blob(arg=Nessuno)

Dati binari, come stringa di byte. Questa è una sottoclasse del tipo integrato str.

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

Blob è per i dati binari, come le immagini. Richiede un valore str, che però viene memorizzato come stringa di byte e non viene 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())

Nel file XML, i blob sono codificati in base-64 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 del suo costruttore.

Le stringhe byte sono indicizzate dal datastore e possono essere utilizzate nei filtri e nelle ordinazioni. Per le stringhe di byte più lunghe di 1500 byte (non 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. Questa è una sottoclasse del tipo integrato unicode.

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 di codifiche standard per i possibili valori per la codifica.

A differenza di una proprietà entità il cui valore è una semplice str o unicode, una proprietà di testo può superare i 1500 byte. Tuttavia, le proprietà 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")
classe Categoria(tag)

Una categoria o un "tag". Questa è 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. Questa è una sottoclasse del tipo integrato unicode.

Né la classe della proprietà né la classe valore eseguono la convalida degli indirizzi email, ma archiviano soltanto 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 con virgola mobile.

Proprietà del modello: GeoPtProperty

In XML, questo è 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
sorseggiareSIP/SIMPLE
xmppXMPP/Jabber
http://aim.com/AIM
http://icq.com/ICQ
http://messenger.msn.com/Messenger (MSN)
http://messenger.yahoo.com/Yahoo Messenger
http://sametime.com/Loto nello stesso orario
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")

In XML, questo è un elemento gd:im.

Un URL completo. Questa è 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. Questa è 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(indirizzo)

Un indirizzo postale. Questa è 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)

Una valutazione fornita dall'utente per un contenuto, sotto forma di numero intero compreso tra 0 e 100. Questa è una sottoclasse del tipo integrato long. La classe convalida che il valore sia un numero intero compreso tra 0 e 100 e solleva 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)

In XML, questo è un elemento gd:rating.

Classi di proprietà

Tutte le classi di proprietà modello fornite da google.appengine.ext.db sono sottoclassi della classe di 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à 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 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 l'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, ...)

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 archiviata nel datastore, sovrascrivendo il valore precedente della proprietà. Ciò è utile per monitorare la data e l'ora di "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 archiviata nel datastore, a meno che alla proprietà non sia già stato assegnato un valore. Ciò è utile per archiviare la data e l'ora "create" per un'istanza del modello.

I valori di data e ora vengono archiviati come 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 valore eseguono la convalida degli indirizzi email, ma archiviano soltanto 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 con virgola mobile.

Tipo di valore: GeoPt

class IMProperty(...)

Un handle di messaggistica immediata.

Tipo di valore: IM

class IntegerProperty(...)

Valore intero, fino a 64 bit.

I valori int Python vengono convertiti in valori 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 rispetto ai membri dell'elenco: list_property = value verifica se il valore compare in qualsiasi punto dell'elenco, list_property < value verifica se alcuni membri dell'elenco sono inferiori al valore specificato e così via.

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

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 valore del datastore e non può essere list.

Il valore di ListProperty non può essere None. Tuttavia, l'elenco può rimanere 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é ListProperty i tipi aggregati non utilizzano le Property classi, Property funzioni delle classi come i valori automatici e la convalida non vengono applicate automaticamente ai membri del valore 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à list. Se None, il valore predefinito è un elenco vuoto. Una proprietà elenco può definire uno validator personalizzato per non consentire l'elenco vuoto.

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

Tipo di valore: un valore 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()

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=Nessuno, ...)

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, solo le istanze del modello della classe possono essere assegnate a questa proprietà. 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 a cui viene fatto riferimento in lettere minuscole e l'aggiunta di _set).

Nota: è necessario impostare collection_name 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 riferimento e rimuove automaticamente le istanze del modello come valori della 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; l'entità datastore viene recuperata e l'istanza del modello creata quando viene utilizzata per la prima volta in questo modo. Le proprietà del 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 con un valore Key, è possibile che un valore di proprietà di riferimento faccia riferimento a un'entità dati che non esiste. Se un'entità di 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=Nessuno, verbose_name=Nessuno, ...)

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

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

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

Una stringa corta. Utilizza un valore str o unicode (basestring) Python di 1500 byte o inferiore.

I valori StringProperty sono indicizzati e possono essere utilizzati nei filtri e nell'ordinamento.

Se multiline è False, il valore non può includere caratteri di avanzamento riga. La libreria djangoforms utilizza questo metodo per applicare una differenza tra i campi di testo e i campi di area di testo nel modello dei dati. Altri possono utilizzarla 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ò superare i 1500 byte. Tuttavia, i valori TextProperty non sono indicizzati e non possono essere utilizzati nei filtri o nell'ordinamento.

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

Se la proprietà text è 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. Utilizza un valore datetime.time della libreria standard Python; 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 modifica il proprio indirizzo email e confronti il vecchio valore User memorizzato con il nuovo valore di 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à. Ciò è utile per tenere traccia di 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 la prima volta che l'istanza del modello viene archiviata nel datastore, a meno che alla proprietà non sia già stato assegnato un valore. Ciò è utile per tenere traccia di quale utente crea un'istanza del modello, che potrebbe non essere lo stesso utente che la modificherà in seguito.

UserProperty non accetta un valore predefinito. I valori predefiniti vengono impostati quando la classe del modello viene importata per la prima volta e con la memorizzazione nella cache di importazione potrebbe non corrispondere l'utente attualmente connesso.

Tipo di valore: users.User