Tipos y clases de propiedades

Nota: Se recomienda encarecidamente a los desarrolladores que creen aplicaciones nuevas que usen la biblioteca de cliente de NDB, que ofrece varias ventajas en comparación con esta biblioteca de cliente, como el almacenamiento automático en caché de entidades mediante la API Memcache. Si actualmente usas la biblioteca de cliente de DB anterior, consulta la guía de migración de DB a NDB.

El almacén de datos de App Engine admite un conjunto fijo de tipos de valores para propiedades en entidades de datos. Las clases Property pueden definir nuevos tipos que se convierten a los tipos de valor subyacentes y desde ellos, y los tipos de valor se pueden usar directamente con Expando propiedades dinámicas y ListProperty modelos de propiedades agregadas.

En la siguiente tabla se describen las clases Property cuyos valores se corresponden directamente con los tipos de datos subyacentes. Cualquiera de estos tipos de valores se puede utilizar en una propiedad dinámica Expando o un tipo agrupado ListProperty.

Clase Property	Tipo de valor	Ordenar por
IntegerProperty	int long (64 bits)	Numérico
FloatProperty	float	Numérico
BooleanProperty	bool	False < True
StringProperty	str unicode	Unicode (str se trata como ASCII)
TextProperty	db.Text	Ninguno
ByteStringProperty	ByteString	Orden de bytes
BlobProperty	db.Blob	Ninguno
DateProperty TimeProperty DateTimeProperty	datetime.date datetime.time datetime.datetime	Cronológico
GeoPtProperty	db.GeoPt	Por latitud, y luego por longitud
PostalAddressProperty	db.PostalAddress	Unicode
PhoneNumberProperty	db.PhoneNumber	Unicode
EmailProperty	db.Email	Unicode
UserProperty	users.User	Dirección de correo electrónico en orden Unicode. Ten en cuenta que debes evitar usar UserProperty, tal como se indica en la nota de la descripción de la clase UserProperty.
IMProperty	db.IM	Unicode
LinkProperty	db.Link	Unicode
CategoryProperty	db.Category	Unicode
RatingProperty	db.Rating	Numérico
ReferenceProperty SelfReferenceProperty	db.Key	Por elementos de ruta (tipo, identificador, tipo, identificador...)
blobstore.BlobReferenceProperty	blobstore.BlobInfo	Orden de bytes
ListProperty StringListProperty	list de un tipo admitido	Si es ascendente, por el elemento más pequeño. Si es descendente, por el elemento más grande.

Tipos de valores de almacén de datos

Los valores de propiedades de entidad de almacén de datos pueden ser uno de los siguientes tipos. Consulta la lista de clases Property correspondientes que se pueden usar con las definiciones de Model que se muestra más arriba.

Aparte de los tipos estándar de Python y users.User, todas las clases descritas en esta sección las proporciona el módulo google.appengine.ext.db.

str o unicode

Una cadena corta (1500 bytes o menos).

Se presupone que un valor str es texto codificado con el códec ascii y se convierte en un valor unicode antes de almacenarse. El almacén de datos devuelve el valor como un valor unicode. Para cadenas cortas que usen otros códecs, usa un valor de unicode.

El almacén de datos indexa las cadenas cortas, que se pueden utilizar con fines de ordenación o filtrado. En el caso de las cadenas de texto de más de 1500 bytes (que no están indexadas), usa una instancia de Text. Para cadenas de bytes sin codificar de más de 1500 bytes (que tampoco están indexadas), usa una instancia de Blob. Para las cadenas de bytes sin codificar no textuales de hasta 1500 bytes (no caracteres) que se deban indexar, usa una instancia de ByteString.

Propiedad de modelo: StringProperty

bool

Valor booleano (True o False).

Propiedad de modelo: BooleanProperty

int o long

Un valor entero, de hasta 64 bits.

Los valores de Python int se convierten en valores de Python long antes de almacenarse. Un valor almacenado como int se devolverá como long.

Si se asigna un long de más de 64 bits, solo se almacenan los 64 bits menos significativos.

Propiedad de modelo: IntegerProperty

float

Número de punto flotante.

Propiedad de modelo: FloatProperty

datetime.datetime

Una fecha y una hora. Consulta la documentación del módulo datetime.

Si el valor de datetime tiene un atributo tzinfo, se convertirá a la zona horaria UTC para almacenarlo. Los valores se devuelven del almacén de datos como UTC, con un tzinfo de None. Una aplicación que necesite que los valores de fecha y hora estén en una zona horaria concreta debe definir tzinfo correctamente al actualizar el valor y convertir los valores a la zona horaria al acceder al valor.

Algunas bibliotecas usan la variable de entorno TZ para controlar la zona horaria que se aplica a los valores de fecha y hora. App Engine asigna el valor "UTC" a esta variable de entorno. Ten en cuenta que, al cambiar esta variable en una aplicación, no se modificará el comportamiento de algunas funciones de datetime, porque los cambios en variables de entorno no se pueden ver fuera del código de Python.

Si solo convierte valores a una zona horaria concreta y viceversa, puede implementar un datetime.tzinfo personalizado para convertir valores del almacén de datos:

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 documentación del módulo datetime (incluido datetime.tzinfo). Consulta también el módulo de terceros pytz, aunque ten en cuenta que la distribución pytz tiene muchos archivos.

La clase de propiedad del modelo DateTimeProperty incluye funciones como la capacidad de usar automáticamente la fecha y la hora en las que se almacena una instancia del modelo. Estas son características del modelo y no están disponibles en el valor sin procesar del almacén de datos (por ejemplo, en una propiedad dinámica Expando ).

Propiedades del modelo: DateTimeProperty, DateProperty, TimeProperty

list

Una lista de valores, siendo cada uno de ellos uno de los tipos de datos compatibles.

Cuando se usa list como valor de una propiedad dinámica Expando, no puede ser una lista vacía. Esto se debe al modo de almacenamiento de los valores de lista: cuando una propiedad de lista no contiene elementos, no tiene representación en el almacén de datos. Puedes usar una propiedad estática y la clase ListProperty para representar un valor de lista vacío de una propiedad.

Propiedad de modelo: ListProperty

db.Key

La clave correspondiente a otra entidad de almacén de datos.

Nota: Las cadenas de claves tienen un límite de 1500 bytes.

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)

Propiedades del modelo: ReferenceProperty, SelfReferenceProperty

blobstore.BlobKey

La clave para un valor del almacén de blob, generado por el Blobstore cuando se sube el valor.

Propiedades del modelo: blobstore.BlobReferenceProperty

users.User

Un usuario con una cuenta de Google.

El valor user.User del almacén de datos no se actualiza si el usuario cambia su dirección de correo electrónico. Por este motivo, te recomendamos que no almacenes un users.User como valor de UserProperty, ya que incluye la dirección de correo junto con el ID único. Si un usuario cambia la dirección de correo y, a continuación, comparas el valor antiguo almacenado de user.User con el nuevo valor de user.User, no coincidirán. En su lugar, use el user.User de user_id() como identificador único estable del usuario.

Propiedad de modelo: UserProperty

class Blob(arg=None)

Datos binarios, representados como una cadena de bytes. Es una subclase del tipo str integrado.

Las propiedades Blob no se indexan y no se pueden utilizar con fines de ordenación o filtrado.

La propiedad Blob se emplea para datos binarios, tales como imágenes. Usa un valor str, pero este valor se almacena como una cadena de bytes y no se codifica como texto. Usa una instancia Text para grandes cantidades de datos de texto.

Propiedad de modelo: BlobProperty

class MyModel(db.Model):
    blob = db.BlobProperty()

m = MyModel()
m.blob = db.Blob(open("image.png", "rb").read())

En XML, los blobs están codificados con base 64, independientemente de que incluyan datos binarios o no.

class ByteString(arg)

Un valor de blob corto (una "cadena de bytes") de 1500 bytes o menos. ByteString es una subclase de str, y toma un valor str sin codificar como argumento de su constructor.

El almacén de datos indexa las ByteStrings, que se pueden utilizar con fines de ordenación o de filtrado. En el caso de las cadenas de bytes de más de 1500 bytes (que no están indexadas), usa una instancia de Blob. Para los datos de texto codificados, usa str (corto, indexado) o Text (largo, no indexado).

Propiedad de modelo: ByteStringProperty

class Text(arg=None, encoding=None)

Una cadena larga. Es una subclase del tipo unicode integrado.

arg un valor unicode o str. Si arg es str, se analiza con la codificación especificada por encoding o ascii si no se especifica ninguna codificación. Consulta la lista de codificaciones estándar para ver los posibles valores de encoding.

A diferencia de una propiedad de entidad cuyo valor es un str o un unicode simple, una propiedad de texto puede tener más de 1500 bytes. Sin embargo, las propiedades Text no se indexan y no se pueden utilizar con fines de ordenación o filtrado.

Propiedad de modelo: 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 categoría o una etiqueta. Es una subclase del tipo unicode integrado.

Propiedad de modelo: CategoryProperty

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

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

En XML, se trata de un elemento Atom Category.

class Email(email)

Una dirección de correo electrónico. Es una subclase del tipo unicode integrado.

Ni la clase de propiedad ni la clase de valor llevan a cabo la validación de las direcciones de correo electrónico; tan sólo almacenan el valor.

Propiedad de modelo: EmailProperty

class MyModel(db.Model):
    email_address = db.EmailProperty()

m = MyModel()
m.email_address = db.Email("[e-mail]")

En XML, se trata de un elemento gd:email. gd:email

class GeoPt(lat, lon=None)

Un punto geográfico representado con coordenadas de latitud y longitud de punto flotante.

Propiedad de modelo: GeoPtProperty

En XML, se trata de un elemento georss:point.

class IM(protocol, address=None)

Un controlador de mensajería instantánea.

protocol es la URL canónica del servicio de mensajería instantánea. Entre los posibles valores se incluyen los siguientes:

Protocolo	Descripción
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
desconocido	Desconocido o no especificado

address es la dirección del controlador.

Propiedad de modelo: IMProperty

class MyModel(db.Model):
    im = db.IMProperty()

m = MyModel()
m.im = db.IM("http://example.com/", "Larry97")

En XML, se trata de un elemento gd:im. gd:im

class Link(link)

Una URL que cumple con todos los requisitos necesarios. Es una subclase del tipo unicode integrado.

Propiedad de modelo: LinkProperty

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

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

En XML, se trata de un elemento Atom Link.

class PhoneNumber(phone)

Un número de teléfono interpretable por humanos. Es una subclase del tipo unicode integrado.

Propiedad de modelo: PhoneNumberProperty

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

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

En XML, se trata de un elemento gd.phoneNumber. gd.phoneNumber

class PostalAddress(address)

Una dirección postal. Es una subclase del tipo unicode integrado.

Propiedad de modelo: PostalAddressProperty

class MyModel(db.Model):
    address = db.PostalAddressProperty()

m = MyModel()
m.address = db.PostalAddress("1600 Ampitheater Pkwy., Mountain View, CA")

En XML, se trata de un elemento gd:postalAddress. gd:postalAddress

class Rating(rating)

Una puntuación proporcionada por un usuario para un segmento de contenido como, por ejemplo, un número entero comprendido entre 0 y 100. Es una subclase del tipo long integrado. La clase valida que el valor sea un número entero entre 0 y 100, y genera un error BadValueError si el valor no es válido.

Propiedad de modelo: RatingProperty

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

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

En XML, se trata de un elemento gd:rating. gd:rating

Clases Property

Todas las clases de propiedades de modelo proporcionadas por google.appengine.ext.db son subclases de la clase base Property y admiten todos los argumentos del constructor base. Para obtener información sobre dichos argumentos, consulta la documentación de clase básica.

El paquete google.appengine.ext.db proporciona las siguientes clases de propiedades de modelo:

class BlobProperty(...)

Una colección de datos binarios sin interpretar.

Los datos de blob son una cadena de bytes. Para los datos de texto, que pueden implicar codificación, usa TextProperty.

Tipo de valor: Blob

class BooleanProperty(...)

Valor booleano (True o False).

Tipo de valor: bool

class ByteStringProperty(verbose_name=None, ...)

Un valor de blob corto (una "cadena de bytes") de 1500 bytes o menos.

Los valores de ByteStringProperty se indexan y se pueden usar en filtros y criterios de ordenación.

Como StringProperty, pero el valor no se codifica de ninguna manera. Los bytes se almacenan literalmente.

Si ByteStringProperty es obligatorio, el valor no puede ser una cadena vacía.

Tipo de valor: ByteString

class CategoryProperty(...)

Una categoría o "etiqueta", una palabra o una frase descriptiva.

Tipo de valor: Category

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

Una fecha sin hora del día. Consulta DateTimeProperty para obtener más información.

Tipo de valor: datetime.date; se convierte internamente en datetime.datetime

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

Una fecha y una hora.

Si auto_now es True, el valor de la propiedad se asigna a la hora actual cada vez que la instancia del modelo se almacena en el almacén de datos, lo que sobrescribe el valor anterior de la propiedad. Esto resulta útil para hacer un seguimiento de la fecha y la hora de la última modificación de una instancia de modelo.

Si auto_now_add es True, el valor de la propiedad se asigna a la hora actual la primera vez que la instancia del modelo se almacena en el almacén de datos, a menos que ya se le haya asignado un valor a la propiedad. Esto resulta útil para almacenar la fecha y la hora de creación de una instancia de modelo.

Los valores de fecha y hora se almacenan y se devuelven conforme a la zona horaria UTC. Consulta datetime.datetime para obtener información sobre cómo gestionar las zonas horarias.

Tipo de valor: datetime.datetime

class EmailProperty(...)

Una dirección de correo electrónico.

Ni la clase de propiedad ni la clase de valor llevan a cabo la validación de las direcciones de correo electrónico; tan sólo almacenan el valor.

Tipo de valor: Email

class FloatProperty(...)

Número de punto flotante.

Tipo de valor: float

class GeoPtProperty(...)

Un punto geográfico representado con coordenadas de latitud y longitud de punto flotante.

Tipo de valor: GeoPt

class IMProperty(...)

Un controlador de mensajería instantánea.

Tipo de valor: IM

class IntegerProperty(...)

Un valor entero, de hasta 64 bits.

Los valores de Python int se convierten en valores de Python long antes de almacenarse. Un valor almacenado como int se devolverá como long.

Si se asigna un long de más de 64 bits, solo se almacenan los 64 bits menos significativos.

Tipo de valor: int o long

class LinkProperty(...)

Una URL que cumple con todos los requisitos necesarios.

Tipo de valor: Link

class ListProperty(item_type, verbose_name=None, default=None, ...)

Lista de valores del tipo especificado por item_type.

En una consulta, al comparar una propiedad de lista con un valor, se realiza la prueba con los miembros de la lista: list_property = value comprueba si el valor aparece en algún lugar de la lista, list_property < value comprueba si alguno de los miembros de la lista es menor que el valor dado, etc.

Una consulta no puede comparar dos valores de lista. No se puede comprobar la equivalencia de dos listas sin probar cada elemento con sus miembros independientemente.

item_type es el tipo de los elementos de la lista, como un tipo o una clase de Python. Todos los elementos del valor de la lista deben ser del tipo indicado. item_type debe ser uno de los tipos de valor de almacén de datos y no puede ser list.

El valor de ListProperty no puede ser None. Sin embargo, puede ser una lista vacía. Si se especifica None para el argumento default (o si no se especifica), el valor predeterminado de la propiedad es la lista vacía.

Nota: Como los tipos de agregación ListProperty no usan las clases Property, las funciones de la clase Property, como los valores automáticos y la validación, no se aplican automáticamente a los miembros del valor de la lista. Si quiere validar un valor de miembro mediante una clase Property, puede crear una instancia de la clase y llamar a su método validate() en el valor.

default es el valor predeterminado de la propiedad de lista. Si None, el valor predeterminado es una lista vacía. Una propiedad de lista puede definir un validador personalizado para no permitir la lista vacía.

Consulta la página Modelado de datos para obtener más información sobre las propiedades y los valores de las listas.

Tipo de valor: una tupla de Python list de valores del tipo especificado.

class PhoneNumberProperty(...)

Un número de teléfono interpretable por humanos.

Tipo de valor: PhoneNumber

class PostalAddressProperty(...)

Una dirección postal.

Tipo de valor: PostalAddress

class RatingProperty()

Una puntuación proporcionada por un usuario para un segmento de contenido como, por ejemplo, un número entero comprendido entre 0 y 100.

Tipo de valor: Rating

class ReferenceProperty(reference_class=None, verbose_name=None, collection_name=None, ...)

Una referencia a otra instancia de modelo. Por ejemplo, una referencia puede indicar una relación de "varios a uno" entre el modelo que incluye la propiedad y el modelo al que hace referencia esa propiedad.

reference_class es la clase de modelo de la instancia de modelo a la que se hace referencia. Si se especifica, sólo se pueden asignar instancias de modelo de la clase a esta propiedad. Si es None, cualquier instancia de modelo puede ser el valor de esta propiedad.

collection_name es el nombre de la propiedad que se va a asignar a la clase de modelo referenciada. El valor de la propiedad es Query para todas las entidades que hagan referencia a la entidad. Si no se define ningún collection_name, se usará modelname_set (con el nombre del modelo referenciado en minúsculas y _set añadido).

Nota: collection_name debe definirse si hay varias propiedades en el mismo modelo que hacen referencia a la misma clase de modelo. De lo contrario, se generará un DuplicatePropertyError cuando se generen los nombres predeterminados.

ReferenceProperty hace referencia y elimina la referencia de las instancias de modelo automáticamente como valores de propiedad: se puede asignar una instancia de modelo a una propiedad de referencia directamente y se usará su clave. El valor de ReferenceProperty se puede usar como si fuera una instancia de modelo. La entidad del almacén de datos se obtendrá y la instancia de modelo se creará cuando se use por primera vez de esta forma. Las propiedades de referencia sin modificar no solicitan datos innecesarios.

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

Al igual que con un valor Key, es posible que un valor de propiedad de referencia haga referencia a una entidad de datos que no exista. Si se elimina una entidad a la que se hace referencia del almacén de datos, las referencias a la entidad no se actualizarán. Si se accede a una entidad que no existe, se genera un error ReferencePropertyResolveError.

Si eliminas una entidad, no se eliminan las entidades a las que se hace referencia en una propiedad de referencia.

Tipo de valor: db.Key

class SelfReferenceProperty(verbose_name=None, collection_name=None, ...)

Una referencia a otra instancia de modelo de la misma clase (consulta ReferenceProperty).

Tipo de valor: db.Key

class StringListProperty(verbose_name=None, default=None, ...)

Es similar a una propiedad de lista de Python str o unicode (basestring).

Tipo de valor: un valor de Python list de str o unicode

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

Una cadena corta. Acepta un valor de Python str o unicode (basestring) de 1500 bytes o menos.

Los valores de StringProperty se indexan y se pueden usar en filtros y criterios de ordenación.

Si multiline es False, el valor no puede incluir caracteres de salto de línea. La biblioteca djangoforms usa este atributo para aplicar una diferencia entre los campos de texto y los campos de área de texto en el modelo de datos. Otros usuarios pueden usarlo con un propósito similar.

Si la propiedad de cadena es obligatoria, su valor no puede ser una cadena vacía.

Tipo de valor: str o unicode

class TextProperty()

Una cadena larga.

A diferencia de StringProperty, un valor de TextProperty puede tener más de 1500 bytes. Sin embargo, los valores TextProperty no se indexan y no se pueden usar en filtros ni en criterios de ordenación.

Los valores TextProperty almacenan texto con una codificación de texto. Para los datos binarios, usa BlobProperty.

Si la propiedad de texto es obligatoria, su valor no puede ser una cadena vacía.

Tipo de valor: Text

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

Una hora del día sin fecha. Toma un valor de la biblioteca estándar de Python datetime.time. Consulta DateTimeProperty para obtener más información.

Tipo de valor: datetime.time; se convierte internamente en datetime.datetime

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

Importante: Te recomendamos que no almacenes un UserProperty, ya que incluye la dirección de correo y el ID único del usuario. Si un usuario cambia su dirección de correo y comparas el valor antiguo almacenado User con el nuevo User, no coincidirán.

Un usuario con una cuenta de Google.

Si auto_current_user es True, el valor de la propiedad se asigna al usuario que ha iniciado sesión en ese momento cada vez que la instancia del modelo se almacena en el almacén de datos, lo que sobrescribe el valor anterior de la propiedad. Esto resulta útil a la hora de controlar qué usuario modifica una instancia de modelo.

Si auto_current_user_add es True, el valor de la propiedad se asigna al usuario que ha iniciado sesión en ese momento la primera vez que la instancia del modelo se almacena en el almacén de datos, a menos que la propiedad ya tenga un valor asignado. Esto resulta útil a la hora de controlar qué usuario crea una instancia de modelo, ya que puede no ser el mismo usuario que la modifique más tarde.

La clase UserProperty no admite un valor predeterminado. Los valores predeterminados se configuran cuando se importa por primera vez la clase de modelo y, con el almacenamiento en caché de la importación, puede que no se trate del usuario actual.

Tipo de valor: users.User