Aviso: En los próximos meses, reorganizaremos el sitio de documentación de App Engine para facilitar la búsqueda de contenido y alinearlo mejor con el resto de los productos de Google Cloud. El mismo contenido estará disponible, pero la navegación ahora coincidirá con el resto de los productos de Cloud.

Python 2 ya no es compatible con la comunidad. Recomendamos que migres las apps de Python 2 a Python 3.

Tipos y clases de propiedades

Nota: Se recomienda enfáticamente a los desarrolladores que compilan aplicaciones nuevas que usen la biblioteca cliente de NDB, 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 por el momento usas la biblioteca cliente anterior de la base de datos, lee la Guía de migración de la base de datos 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 tipos de valores subyacentes y viceversa, y los tipos de valores se pueden usar directamente con propiedades dinámicas Expando y 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 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`, según la nota de la descripción de clase de 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 de acceso (tipo, identificador, tipo, identificador, etc.)
`blobstore.BlobReferenceProperty`	`blobstore.BlobInfo`	Orden de bytes
`ListProperty` `StringListProperty`	`list` de un tipo compatible	Si asciende, por elemento menor, si es 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. Consulte más arriba para obtener una lista de las clases de Property correspondientes que se usarán con las definiciones de Model.

Aparte de los tipos estándar de Python y users.User, el módulo google.appengine.ext.db proporciona 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 un 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 de más de 1,500 bytes (sin indexar), usa una instancia Text. En las strings de bytes sin codificación de más de 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 int de Python se convierten en valores long de Python antes del almacenamiento. Un valor almacenado como un int se mostrará como 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 (incluido 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 del modelo:DateTimeProperty, DateProperty, 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 un valor de lista sin completar 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)

Propiedades de modelo: ReferenceProperty, SelfReferenceProperty

blobstore.BlobKey

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

Propiedades 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 este motivo, te recomendamos que evites almacenar un valor users.User como UserProperty, ya que esto incluye la dirección de correo electrónico junto con el ID único. Si un usuario cambia su dirección de correo electrónico y comparas su user.User anterior almacenado con el valor user.User nuevo, no coincidirán. En su lugar, usa el valor de user_id() de 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 1500 bytes o menos. ByteString es una subclase de str y toma un valor str sin codificar como argumento para su constructor.

El almacén de datos indexa ByteStrings, que pueden usarse en filtros y órdenes de clasificación. En las strings de bytes de más de 1,500 bytes (sin indexar), usa una instancia Blob. En los datos de texto 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:

Protocolo	Descripción
sip	SIP y SIMPLE
xmpp	XMPP 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
desconocido	Desconocido 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.

class Link(link)

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 valida que el valor sea un número entero entre 0 y 100, y genera un 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, 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 int de Python se convierten en valores long de Python antes del almacenamiento. Un valor almacenado como un int se mostrará como 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, cuando se compara 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 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 determinado.item_type debe ser uno de los tipos de valor del almacén de datos, y no puede ser list.

El valor de un objeto ListProperty no puede ser None. Sin embargo, puede ser una lista vacía. Cuando se especifica None para el argumento predeterminado (o cuando no se especifica el argumento predeterminado), 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 los valores automáticos y la validación, no se aplican automáticamente 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 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 collection_name, se usa modelname_set (con el nombre del modelo al que se hace referencia en minúscula, 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 generará 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 de almacén de datos se recuperará y la instancia de modelo se creará cuando se use de este modo por primera vez. 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, es posible que un valor de propiedad de referencia se refiera 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, ...)

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

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 de Python o un valor unicode (basestring) de 1,500 bytes o menos.

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

Si multiline es False, el valor no puede incluir caracteres de salto de línea. La biblioteca djangoforms lo uso para aplicar una diferencia entre campos de texto y campos de área de texto en el modelo de datos y otras pueden usarlo con propósitos similares.

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 longitud. 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, convertido de manera interna en datetime.datetime.

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

Importante: Recomendamos encarecidamente 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 anterior almacenado con el valor User nuevo, no coincidirán.

Un usuario con una Cuenta de Google.

Si auto_current_user es True, el valor de la 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 la propiedad se establece en el usuario actualmente accedió la primera vez que la instancia del modelo se almacena en el almacén de datos, a menos que a la propiedad ya se le haya asignado un valor. 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