Tipos y clases de propiedades

Nota: Se recomienda a los desarrolladores que usen la biblioteca cliente de NDB para compilar aplicaciones nuevas, ya que tiene muchas ventajas en comparación con esta biblioteca cliente, como el almacenamiento en caché automático de entidades mediante la API de Memcache. Si actualmente usas la biblioteca cliente de DB antigua, lee 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 valor para propiedades en entidades de datos. Las clases Property pueden definir tipos nuevos que se convierten en y desde los tipos de valor subyacentes, y los tipos de valor se pueden usar directamente con las propiedades dinámicas Expando y los modelos de propiedad de agregación ListProperty.

La tabla siguiente describe las clases de propiedad cuyos valores corresponden de manera directa con los tipos de dato subyacentes. Cualquiera de estos tipos de valor se puede usar en una propiedad dinámica Expando o en un tipo de agregación ListProperty.

Clase de propiedad Tipo de valor Orden
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,
luego longitud
PostalAddressProperty db.PostalAddress Unicode
PhoneNumberProperty db.PhoneNumber Unicode
EmailProperty db.Email Unicode
UserProperty users.User Dirección de correo electrónico
en orden de Unicode. Ten en cuenta que debes evitar el uso de UserProperty, de acuerdo con 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 asciende, por elemento menor;
si desciende, por elemento mayor

Tipos de valor del almacén de datos

Los valores de propiedad de entidad del almacén de datos pueden ser uno de los siguientes tipos. Consulta la sección anterior para ver una lista de las clases Property que corresponde usar con las definiciones de la clase Model.

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

str o unicode

Una string corta (1,500 bytes o menos).

Se supone que un valor str está codificado con el códec ascii y se convierte en el valor unicode antes de almacenarse. El almacén de datos muestra el valor como un valor unicode. Para otras strings cortas que usan códecs, usa un valor unicode.

El almacén de datos indexa las strings cortas y se pueden usar en filtros y en órdenes de clasificación. En las strings de texto más largas que 1,500 bytes (sin indexar), usa una instancia Text. En las strings de bytes sin codificación más largas que 1,500 bytes (tampoco indexadas), usa una instancia Blob. En las strings de bytes sin codificación no textuales de hasta 1,500 bytes (sin caracteres) que deben indexarse, usa una instancia ByteString.

Propiedad de modelo: StringProperty

bool

Un valor booleano (True o False).

Propiedad de modelo: BooleanProperty

int o long

Un valor de número entero, hasta 64 bits.

Los valores Python int se convierten en valores Python long antes del almacenamiento. Un valor almacenado como un int se mostrará como un long.

Si se asigna un long más largo que 64 bits, solo se almacena el menos significativo de los 64 bits.

Propiedad de modelo: IntegerProperty

float

Un número de punto flotante.

Propiedad de modelo: FloatProperty

datetime.datetime

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

Si el valor datetime tiene un atributo tzinfo, se convertirá en la zona horaria UTC para el almacenamiento. Los valores regresan del almacén de datos como UTC, con un tzinfo de None. Una aplicación que necesita valores de fecha y hora de una zona horaria en particular debe configurar correctamente tzinfo cuando se actualiza el valor y convertir los valores a la zona horaria cuando se acceda al valor.

Algunas bibliotecas usan la variable de entorno TZ para controlar la zona horaria aplicada a los valores de fecha y hora. App Engine configura esta variable de entorno en "UTC". Ten en cuenta que, si cambias esta variable en una aplicación, no cambiará el comportamiento de algunas de las funciones de fecha y hora, debido a que los cambios en las variables de entorno no son visibles fuera del código de Python.

Si solo conviertes valores hacia y desde zona horaria en particular, puedes implementar una datetime.tzinfo personalizada desde el almacén de datos de la siguiente manera:

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

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

Propiedades de modelo: DateTimeProperty, DateProperty o TimeProperty

list

Una lista de valores, en la que cada uno de ellos es uno de los tipos de datos compatibles.

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

Propiedad de modelo: ListProperty

db.Key

La clave para otra entidad del almacén de datos.

Nota: Las strings de clave se limitan a 1,500 bytes o menos.

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)

Propiedad de modelo: ReferenceProperty o SelfReferenceProperty

blobstore.BlobKey

La clave para un valor Blobstore, generada por el Blobstore cuando se subir un valor.

Propiedad de modelo: blobstore.BlobReferenceProperty

users.User

Un usuario con una Cuenta de Google.

Un valor user.User en el almacén de datos no se actualiza si el usuario cambia su dirección de correo electrónico. Por ese motivo, recomendamos que evites almacenar un users.User como un valor UserProperty, ya que esto incluye la dirección de correo electrónico junto con el ID único. Si el usuario cambia la dirección de correo electrónico y, luego, comparas el user.User almacenado anterior con el valor nuevo de user.User, no coincidirán. En cambio, usa el user_id() del valor user.User como el identificador único estable del usuario.

Propiedad de modelo: UserProperty

class Blob(arg=None)

Datos binarios, como una string de bytes. Esta es una subclase del tipo str integrado.

Las propiedades BLOB no se indexan y no se pueden usar en filtros ni en órdenes de clasificación.

BLOB es para datos binarios, como imágenes. Toma un valor str, pero este valor se almacena como una string de bytes y no se codifica como texto. Usa una instancia Text para datos de texto grandes.

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 BLOB están codificados en base 64 sin importar si contienen o no datos binarios.

class ByteString(arg)

Un valor blob corto (una “string de bytes”) de 1,500 bytes o menos. ByteString es una subclase de str, y toma un valor str sin codificar como un argumento para su constructor.

El almacén de datos indexa ByteStrings, que pueden usarse en filtros y órdenes de clasificación. En las strings más largas que 1,500 bytes (sin indexar), usa una instancia Blob. En los datos de textos codificados, usa str (cortos, indexados) o Text (largos, sin indexar).

Propiedad de modelo: ByteStringProperty

class Text(arg=None, encoding=None)

Una string larga. Esta es una subclase del tipo unicode integrado.

El argumento es un valor unicode o str. Si el argumento es str, se analiza con la codificación especificada por la codificación, o ascii si no se especifica la codificación. Consulta la lista de codificaciones estándar a fin de ver los valores de codificación posibles.

A diferencia de una propiedad de entidad cuyo valor es un str simple o unicode, una propiedad de texto puede ser más larga que 1,500 bytes. Sin embargo, las propiedades de texto no están indexadas y no se pueden usar en órdenes de clasificación ni en filtros.

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". Esta 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, este es un elemento Atom Category.

class Email(email)

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

La clase de propiedad y la clase de valor no realizan una validación de direcciones de correo electrónico, solo almacenan el valor.

Propiedad de modelo: EmailProperty

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

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

En XML, este es un elemento gd:email.

class GeoPt(lat, lon=None)

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

Propiedad de modelo: GeoPtProperty

En XML, este es un elemento georss:point.

class IM(protocol, address=None)

Un controlador de mensajería instantánea.

El protocolo es la URL canónica del servicio de mensajería instantánea. Los siguientes son algunos valores posibles:

ProtocoloDescripción
sipSIP y SIMPLE
xmppXMPP y 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
desconocidoDesconocido o sin especificar

La dirección 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, este es un elemento gd:im.

Una URL completamente calificada. Esta 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, este es un elemento Atom Link.

class PhoneNumber(phone)

Un número de teléfono legible. Esta 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 (206) 555-1212")

En XML, este es un elemento gd.phoneNumber.

class PostalAddress(address)

Una dirección postal. Esta 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, este es un elemento gd:postalAddress.

class Rating(rating)

Una calificación que proveen los usuarios para un contenido, en formato de un número entero entre 0 y 100. Esta es una subclase del tipo long integrado. La clase corrobora que el valor sea un número entero entre 0 y 100, y genera un BadValueError si este no es válido.

Propiedad de modelo: RatingProperty

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

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

En XML, este es un elemento gd:rating.

Clases de propiedades

Todas las clases de propiedad de modelo que proporciona google.appengine.ext.db son subclases de la clase base Property, y admiten todos los argumentos del constructor base. Consulta la documentación de clase básica para obtener más información sobre esos argumentos.

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

class BlobProperty(...)

Una colección no interpretada de datos binarios.

Los datos BLOB son una string de bytes. Para los datos de texto, que pueden incluir codificación, usa TextProperty.

Tipo de valor: Blob

class BooleanProperty(...)

Un valor booleano (True o False).

Tipo de valor: bool

class ByteStringProperty(verbose_name=None, ...)

Un valor blob corto (una “string de bytes”) de 1500 bytes o menos.

Los valores ByteStringProperty se indexan y se pueden usar en filtros y órdenes de clasificación.

Como StringProperty, excepto que el valor no esté codificado de ninguna manera. Los bytes se almacenan de manera literal.

Si se exige la ByteStringProperty, el valor no puede ser una string vacía.

Tipo de valor: ByteString

class CategoryProperty(...)

Una categoría o “etiqueta”, una frase o palabra 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; convertido de manera interna en datetime.datetime

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

Una fecha y hora.

Si auto_now es True, el valor de la propiedad se establece en la hora actual cada vez que la instancia del modelo se almacena en el almacén de datos, y reemplaza al valor previo de la propiedad. Eso es útil con el fin de realizar un seguimiento de una “última modificación” de fecha y hora para una instancia de modelo.

Si auto_now_add es True, el valor de la propiedad se establece en la hora actual 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. Eso es útil para almacenar una fecha y hora “creadas” para una instancia de modelo.

Los valores de fecha y hora se almacenan y se muestran con la zona horaria UTC. Consulta datetime.datetime para ver un análisis sobre cómo administrar zonas horarias.

Tipo de valor: datetime.datetime

class EmailProperty(...)

Una dirección de correo electrónico.

La clase de propiedad y la clase de valor no realizan una validación de direcciones de correo electrónico, solo almacenan el valor.

Tipo de valor: Email

class FloatProperty(...)

Un número de punto flotante.

Tipo de valor: float

class GeoPtProperty(...)

Un punto geográfico representado por 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 de número entero, hasta 64 bits.

Los valores Python int se convierten en valores Python long antes del almacenamiento. Un valor almacenado como un int se mostrará como un long.

Si se asigna un long más largo que 64 bits, solo se almacena el menos significativo de los 64 bits.

Tipo de valor: int o long

class LinkProperty(...)

Una URL completamente calificada.

Tipo de valor: Link

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

Una lista de valores de tipo especificado por item_type.

En una consulta, comparar una propiedad de lista con un valor realiza la prueba con los miembros de la lista: list_property = value evalúa si el valor aparece en algún lugar de la lista, list_property < value evalúa si alguno de los miembros de la lista es menor que un valor determinado y así sucesivamente.

Una consulta no puede comparar dos valores de la lista. No hay manera de evaluar la igualdad de dos listas sin evaluar cada elemento para membresía por separado.

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

El valor de un ListProperty no puede ser None. Sin embargo, puede ser una lista vacía. Cuando se especifica None para el argumento predeterminado (o cuando el argumento predeterminado no está especificado), el valor predeterminado de la propiedad es la lista vacía.

Sugerencia: Debido a que los tipos de agregación ListProperty no usan las clases Property, las características de la clase Property, como valores y validación automáticos, no se aplican de manera automática a los miembros del valor de lista. Si deseas corroborar un valor de miembro mediante una clase Property, puedes crear una instancia de la clase y llamar a su método validate() en el valor.

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

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

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

class PhoneNumberProperty(...)

Un número de teléfono legible.

Tipo de valor: PhoneNumber

class PostalAddressProperty(...)

Una dirección postal.

Tipo de valor: PostalAddress

class RatingProperty()

Una calificación que proveen los usuarios para un contenido, en formato de un número entero entre 0 y 100.

Tipo de valor: Rating

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

Una referencia para otra instancia de modelo. Por ejemplo, una referencia puede indicar una relación de muchos para uno entre el modelo con la propiedad y el modelo al que la propiedad hace referencia.

reference_class es la clase de modelo de la instancia de modelo a la que se hace referencia. Si se especifica, solo las instancias de modelo de la clase se pueden asignar 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 da a la clase de modelo a la que se hace referencia. El valor de la propiedad es una Query para todas las entidades que hacen referencia a la entidad. Si no se configura un collection_name, se usa modelname_set (con el nombre del modelo al que se hace referencia en letras minúsculas y se agrega _set).

Nota: El collection_name se debe configurar si hay varias propiedades dentro del mismo modelo que hace referencia a la misma clase de modelo. De lo contrario, se emitirá un DuplicatePropertyError cuando se generen los nombres predeterminados.

ReferenceProperty hace y deshace, de manera automática, referencia a instancias de modelo como valores de propiedad: una instancia de modelo se puede asignar a una propiedad de referencia directamente y se usará su clave. El valor ReferenceProperty se puede usar como si fuera una instancia de modelo y la entidad del almacén de datos se recuperará y la instancia de modelo se creará cuando se use por primera vez de esta manera. Las propiedades de referencia intactas no consultan por 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, un valor de propiedad de referencia puede hacer referencia a una entidad de datos que no existe. Si se borra una entidad de referencia del almacén de datos, no se actualizan las referencias a la entidad. El acceso a una entidad que no existe genera un ReferencePropertyResolveError.

La eliminación de una entidad no borra las entidades a las que hace referencia 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, ...)

Similar a una propiedad de lista de valores de Python str o unicode (basestring).

Tipo de valor: una list de Python de valores str o unicode

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

Una string corta. Toma una str Python o un valor unicode (basestring) de 1,500 bytes o menos.

Los valores StringProperty se indexan y se pueden usar como filtros y órdenes de clasificación.

Si multiline es False, el valor no puede incluir caracteres de salto de línea. La biblioteca djangoforms usa eso para aplicar una diferencia entre campos de texto y campos de área de texto en el modelo de datos y otros pueden usarlos con un mismo propósito.

Si se exige la propiedad de string, su valor no puede ser una string vacía.

Tipo de valor: str o unicode

class TextProperty()

Una string larga.

A diferencia de StringProperty, un valor TextProperty puede tener más de 1,500 bytes de largo. Sin embargo, los valores TextProperty no se indexan y no se pueden usar en filtros ni en órdenes de clasificación.

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

Si se exige la propiedad de texto, su valor no puede ser una string vacía.

Tipo de valor: Text

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

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

Tipo de valor: datetime.time, que se convierte de manera interna en datetime.datetime

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

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

Un usuario con una Cuenta de Google.

Si auto_current_user es True, el valor de propiedad se establece en el usuario que accedió cada vez que la instancia de modelo se almacena en el almacén de datos, y reemplaza al valor anterior de la propiedad. Esto sirve para realizar un seguimiento de qué usuario modifica una instancia de modelo.

Si auto_current_user_add es True, el valor de propiedad se establece en el usuario que accedió la primera vez que la instancia de modelo se almacena en el almacén de datos, a menos que la propiedad ya tenga un valor asignado. Esto sirve para realizar un seguimiento de qué usuario crea una instancia de modelo, que puede no ser el mismo usuario que la modifique más tarde.

UserProperty no acepta un valor predeterminado. Los valores predeterminados se establecen cuando la clase de modelo se importa por primera vez, y con la importación en caché puede que no sea el usuario que accedió en el momento.

Tipo de valor: users.User