Tipos y clases de propiedades

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 y desde los tipos de valores subyacentes y los tipos de valores se pueden utilizar directamente con propiedades dinámicas Expando y modelos de propiedades agrupados ListProperty.

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.

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 anterior de clases Property correspondientes para utilizar con definiciones de Model.

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

str o unicode

Un valor de cadena corta, con una longitud inferior a 500 bytes.

Se asume que el texto de un valor str está 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 valor unicode. Utiliza un valor unicode para las cadenas cortas que utilicen otros códecs.

El almacén de datos indexa las cadenas cortas, que se pueden utilizar con fines de ordenación o filtrado. Utiliza una instancia de Text para las cadenas de texto con una longitud superior a 500 bytes (que no están indexadas). Utiliza una instancia de Blob para las cadenas de bytes no codificadas con una longitud superior a 500 bytes (que tampoco están indexadas).

Propiedad Model: StringProperty

bool

Un valor booleano, True o False.

Propiedad Model: BooleanProperty

int o long

Un valor entero.

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

Propiedad Model: IntegerProperty

float

Un valor de punto flotante.

Propiedad Model: FloatProperty

datetime.datetime

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

Si el valor datetime contiene un atributo tzinfo, se convertirá en la zona horaria UTC (Tiempo Universal Coordinado) para el almacenamiento. Los valores volverán del almacén de datos como UTC, con un valor de None para el atributo tzinfo. Las aplicaciones que requieran que los valores de fecha y hora se encuentren en una zona horaria concreta deberán establecer el parámetro tzinfo correctamente cuando actualicen el valor, así como convertir los valores a la zona horaria cuando se acceda al valor.

Algunas bibliotecas utilizan la variable de entorno TZ para controlar la zona horaria que se aplica a los valores de fecha y hora. App Engine establece el valor "UTC" para 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 sólo convierte valores hacia y desde una zona horaria concreta, puedes implementar un parámetro datetime.tzinfo personalizado para convertir valores desde el almacén de datos:

class Pacific_tzinfo(datetime_module.tzinfo):
 """Implementation of the Pacific timezone."""
 def utcoffset(self, dt):
   return datetime_module.timedelta(hours=-8) + self.dst(dt)

 def _FirstSunday(self, dt):
   """First Sunday on or after dt."""
   return dt + datetime_module.timedelta(days=(6-dt.weekday()))

 def dst(self, dt):
   # 2 am on the second Sunday in March
   dst_start = self._FirstSunday(datetime_module.datetime(dt.year, 3, 8, 2))
   # 1 am on the first Sunday in November
   dst_end = self._FirstSunday(datetime_module.datetime(dt.year, 11, 1, 1))

   if dst_start <= dt.replace(tzinfo=None) < dst_end:
     return datetime_module.timedelta(hours=1)
   else:
     return datetime_module.timedelta(hours=0)

 def tzname(self, dt):
   if self.dst(dt) == datetime_module.timedelta(hours=0):
     return "PST"
   else:
     return "PDT"

pacific_time = utc_time.astimezone(Pacific_tzinfo())

Consulta la documentación del módulo datetime (incluido el objeto datetime.tzinfo). Consulta también el módulo externo pytz, aunque debes tener en cuenta que la distribución de pytz contiene muchos archivos.

La clase de propiedad de modelo DateTimeProperty incluye funciones tales como la capacidad de utilizar de forma automática la fecha y hora almacenada en una instancia de modelo. Éstas son funciones del modelo y no están disponibles en el valor de almacén de datos sin procesar (como ocurre en una propiedad dinámica Expando).

Propiedades Model: DateTimeProperty, DateProperty, TimeProperty

list

Una lista de valores, siendo cada uno de ellos uno de los tipos de datos compatibles. Consulta Entidades y modelos: Listas.

Cuando una lista (list) se utiliza como valor de una propiedad dinámica Expando, no puede estar 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 utilizar una propiedad estática y la clase ListProperty para representar un valor de lista vacía para una propiedad.

Propiedad Model: ListProperty

db.Key

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

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 Model: ReferenceProperty, SelfReferenceProperty

users.User

Un usuario con una cuenta de Google.

Si el usuario modifica su dirección de correo electrónico, los valores User del almacén de datos no se actualizan. Esto se solucionará en futuras versiones. Hasta entonces, puedes utilizar user_id() del valor User como el único identificador estable del usuario.

Propiedad Model: UserProperty

class Blob(arg=None)

Datos binarios, representados como una cadena de bytes. Se trata de 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. Utiliza un valor str, pero este valor se almacena como una cadena de bytes y no se codifica como texto. Utiliza una instancia de Text para datos de texto de gran tamaño.

Propiedad Model: BlobProperty

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

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

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

class ByteString(arg)

Un valor de blob corto (una "cadena de blobs"), menos de 500 bytes de longitud. ByteString es una subclase de str y toma un valor str decodificado como argumento para su constructor.

El almacén de datos indexa las ByteStrings, que se pueden utilizar con fines de ordenación o de filtrado. Utiliza una instancia de Blob para las cadenas de bytes con una longitud superior a 500 bytes (que no están indexadas). Para los datos de texto codificados, utiliza str (corto, indexado) o bien Text (largo, no indexado).

Model property: ByteStringProperty

class Text(arg=None, encoding=None)

Una cadena larga. Se trata de una subclase del tipo unicode integrado.

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

A diferencia de una propiedad de entidad cuyo valor es sencillamente str o unicode, una propiedad Text puede tener una longitud superior a 500 bytes. Sin embargo, las propiedades Text no se indexan y no se pueden utilizar con fines de ordenación o filtrado.

Propiedad Model: 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 "etiqueta". Se trata de una subclase del tipo unicode integrado.

Propiedad Model: CategoryProperty

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

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

En XML, es un elemento category de Atom. Consulta la especificación de Atom.

class Email(email)

Una dirección de correo electrónico. Se trata de 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 Model: EmailProperty

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

m = MyModel()
m.email_address = db.Email("larry@example.com")

En XML, es un elemento gd:email. Consulta la referencia de API de datos de Google.

class GeoPt(lat, lon=None)

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

Propiedad Model: GeoPtProperty

En XML, es un elemento georss:point. Consulta georss.org.

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://talk.google.com/	Google Talk
http://messenger.msn.com/	MSN Messenger
http://messenger.yahoo.com/	Yahoo Messenger
http://sametime.com/	Lotus Sametime
http://gadu-gadu.pl/	Gadu-Gadu
unknown	Desconocido o no especificado

address es la dirección del controlador.

Propiedad Model: IMProperty

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

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

En XML, es un elemento gd:im. Consulta la referencia de API de datos de Google.

class Link(link)

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

Propiedad Model: LinkProperty

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

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

En XML, es un elemento link de Atom. Consulta la especificación de Atom.

class PhoneNumber(phone)

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

Propiedad Model: PhoneNumberProperty

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

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

En XML, es un elemento gd.phoneNumber. Consulta la referencia de API de datos de Google.

class PostalAddress(address)

Una dirección postal. Se trata de una subclase del tipo unicode integrado.

Propiedad Model: PostalAddressProperty

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

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

En XML, es un elemento gd:postalAddress. Consulta la referencia de API de datos de Google.

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. Se trata de una subclase del tipo long integrado. La clase comprueba que el valor sea un número entero entre 0 y 100 y genera un error de valor incorrecto (BadValueError) si el valor no es válido.

Propiedad Model: RatingProperty

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

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

En XML, es un elemento gd:rating. Consulta la referencia de API de datos de Google.

Clases Property

Todas las clases de propiedades de modelo proporcionadas por google.appengine.ext.db son subclases de la clase básica Property y admiten todos los argumentos del constructor básico. 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 propiedad de datos binarios.

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

Tipo de valor: Blob

class BooleanProperty(...)

Una propiedad booleana.

Tipo de valor: bool

class ByteStringProperty(verbose_name=None, ...)

Una propiedad blob corta (una "cadena de bytes"). Utiliza un valor ByteString con una longitud de 500 bytes o inferior.

Los valores de propiedad ByteStringProperty se indexan y se pueden utilizar con fines de ordenación y de filtrado.

Al igual que StringProperty, salvo por que no se codifica el valor de ninguna forma. Los bytes se almacenan literalmente.

Tipo de valor: ByteString

class CategoryProperty(...)

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

Tipo de valor: Category

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

Una propiedad de fecha sin hora del día. Para obtener más información, consulta la sección DateTimeProperty.

Tipo de valor: datetime.date. Este valor se convierte internamente en un valor datetime.datetime.

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

Una propiedad de fecha y hora.

Si el valor de auto_now es True, el valor de propiedad se establecerá en la hora actual cada vez que la instancia de modelo se almacene en el almacén de datos, sobrescribiendo el anterior valor de la propiedad. Resulta útil para realizar un seguimiento de la fecha y hora de la "última modificación" para una instancia de modelo.

Si el valor de auto_now_add es True, el valor de propiedad se establecerá en la hora actual la primera vez que la instancia de modelo se almacene en el almacén de datos, a menos que ya se haya asignado un valor a la propiedad. Resulta útil para almacenar una fecha y hora de "creación" para una instancia de modelo.

Los valores de fecha y hora se almacenan y se devuelven conforme a la zona horaria UTC. Si deseas saber más sobre cómo administrar zonas horarias, consulta la sección datetime.datetime.

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

Una propiedad de 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(...)

Una propiedad de número entero.

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

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

Una lista de valores del tipo determinado como item_type.

En una consulta, al comparar una propiedad de lista con un valor, se lleva a cabo la comprobación con los miembros de la lista: list_property = value comprueba si el valor aparece en cualquier lugar de la lista, list_property < value comprueba si alguno de los miembros de la lista es inferior al valor determinado, 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 elementos de la lista como, por ejemplo, un tipo o una clase de Python. Todos los elementos del valor de lista deben ser del mismo tipo. item_type debe ser uno de los tipos de valores del almacén de datos y no puede ser list. Consulta la sección anterior Tipos de valores de almacén de datos.

El valor de una propiedad estática ListProperty no puede ser None. Sin embargo, puede ser una lista vacía.

Sugerencia: dado que los tipos agrupados ListProperty no utilizan las clases Property, las funciones de clase Property, tales como la validación y los valores automáticos, no se aplican de forma automática a los miembros del valor de lista. Si deseas validar un valor de miembro con una clase Property, puedes crear una instancia de la clase y ejecutar su método validate() en el valor.

default es el valor predeterminado de la propiedad de lista. Si es valor es None, el valor predeterminado será una lista vacía. Una propiedad de lista puede definir un elemento de validación para no permitir una lista vacía.

Para obtener más información sobre ListProperty y los valores de lista, consulta Entidades y modelos.

Tipo de valor: una lista (list) de Python de cero o más valores, donde cada valor es del tipo configurado.

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 a esta propiedad. Si el valor es None, cualquier instancia de modelo puede ser el valor de esta propiedad.

collection_name es el nombre de la propiedad que se dará a la clase de modelo a la que se hace referencia cuyo valor es Query para todas las entidades que hacen referencia a la entidad. Si no se ha establecido ningún valor para collection_name, se utilizará modelname_set (con el nombre del modelo en minúsculas y "_set" añadido al final).

Nota: se debe establecer el valor de collection_name si hay varias propiedades en el mismo modelo que hagan referencia a la misma clase de modelo. De lo contrario, se originará un error de propiedad duplicada (DuplicatePropertyError) cuando se generen los nombres predeterminados.

ReferenceProperty hace referencia a instancias de modelos como valores de propiedad y anula su referencia de forma automática: se puede asignar una instancia de modelo directamente a una clase "ReferenceProperty" y se utilizará su clave. El valor de ReferenceProperty se puede utilizar como si se tratara de una instancia de modelo; la entidad de almacén de datos se extraerá y la instancia de modelo se creará cuando se utilice de esta forma por primera vez. 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

Al igual que con el valor Key, es posible que un valor de propiedad de referencia se refiera a una entidad de datos que no existe. 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. Una aplicación puede obtener de forma explícita mediante la función db.get() el valor de una clase "ReferenceProperty" (que es una clave) para comprobar si existe la entidad a la que se hace referencia.

Al eliminar una entidad, no se eliminarán las entidades a las que hace referencia una clase "ReferenceProperty".

Consulta también esta introducción a las propiedades de referencia.

Tipo de valor: db.Key (consulta la sección anterior que trata sobre este valor)

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

Una referencia a otra instancia de modelo de la misma clase. Consulta la sección sobre ReferenceProperty.

Tipo de valor: db.Key (consulta la sección anterior que trata sobre este valor)

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

Similar a una clase ListProperty de valores str o unicode (basestring) de Python. Consulta la sección sobre ListProperty.

Tipo de valor: una lista (list) de valores str o unicode de Python.

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

Una propiedad de cadena corta. Utiliza un valor str o unicode (basestring) de Python con una longitud de 500 bytes o inferior.

Los valores de propiedad StringProperty no se indexan y no se pueden utilizar con fines de ordenación y filtrado.

Si el valor de multiline es False, el valor no podrá contener caracteres de linefeed. La biblioteca djangoforms utiliza esta propiedad para imponer una diferencia entre campos de texto y campos de área de texto en el modelo de datos y, al mismo tiempo, otras bibliotecas pueden utilizarla con un fin similar.

Tipo de valor: str o unicode

class TextProperty()

Una cadena larga.

A diferencia de StringProperty, un valor de TextProperty puede tener una longitud superior a 500 bytes. Sin embargo, los valores TextProperty no se indexan y no se pueden utilizar con fines de ordenación o filtrado.

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

Tipo de valor: Text

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

Una propiedad de hora sin fecha. Utiliza el valor datetime.time de una biblioteca estándar de Python. Para obtener más información, consulta la sección DateTimeProperty.

Tipo de valor: datetime.time. Este valor se convierte internamente en un valor datetime.datetime.

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

Un usuario con una cuenta de Google.

Si el valor de auto_current_user es True, el valor de propiedad se establece en el usuario actual cada vez que el modelo se almacene en el almacén de datos, sobrescribiendo el valor de la propiedad anterior. Esto resulta útil a la hora de realizar el seguimiento de qué usuario modifica una instancia de modelo.

Si el valor de auto_current_user_add es True, el valor de propiedad se establece en el usuario actual la primera vez que la instancia de modelo se almacene en el almacén de datos, a menos que ya se haya asignado un valor a la propiedad. Esto resulta útil a la hora de realizar el seguimiento de qué usuario crea una instancia de modelo, ya que puede no ser el mismo usuario que la modifique más tarde.

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 (consulta la sección anterior que trata sobre el valor)