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

La clase Model

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.

La clase Model es la superclase para las definiciones de modelo de datos.

Model se define en el módulo google.appengine.ext.db.

Introducción

Una aplicación define un modelo de datos mediante la definición de una clase con una subclase Model. Las propiedades del modelo se definen con los atributos de clase y las instancias de clase Property. Por ejemplo:

class Story(db.Model):
  title = db.StringProperty()
  body = db.TextProperty()
  created = db.DateTimeProperty(auto_now_add=True)

Una aplicación crea una entidad de datos nueva mediante la creación de una instancia de una subclase de la clase Model. Las propiedades de una entidad pueden asignarse mediante los atributos de la instancia o como argumentos de palabras clave al constructor.

s = Story()
s.title = "The Three Little Pigs"

s = Story(title="The Three Little Pigs")

El nombre de la subclase modelo se usa como el nombre del similar de entidad de Datastore. Datastore reserva todos los nombres de categorías que comienzan con dos guiones bajos (__). Las subclases modelo no deben usar esos nombres.

Los nombres de los atributos se usan como los nombres de las propiedades correspondientes en una entidad. Los atributos de la instancia de modelo cuyos nombres comienzan con un guion bajo (_) se ignoran, por lo que tu aplicación puede usar estos atributos para almacenar datos en una instancia de modelo que no se guarda en Datastore.

Datastore y la API de la clase modelo imponen varias restricciones en los nombres de propiedades y atributos de la instancia de modelo. Consulta Nombres de propiedades no permitidos para obtener una descripción completa.

Cada entidad tiene una clave, un identificador único que representa a la entidad. La clave puede incluir un nombre de clave opcional, una string única para todas las entidades del tipo específico. El tipo de entidad y el nombre de clave se pueden usar con los métodos Key.from_path() y Model.get_by_key_name() para recuperar la entidad.

Una entidad también puede tener una entidad principal opcional. Las relaciones entre superiores y secundarias forman grupos de entidades, que se usan para controlar la transaccionalidad y la localización de datos en Datastore. Una aplicación crea una relación principal-secundaria entre dos entidades si pasa la entidad principal al constructor de la entidad secundaria, como argumento parent.

El método Model.get_or_insert() se puede usar para recuperar una entidad que puede no existir y crearla en Datastore si es necesario:

keyname = "some_key"
s = Story.get_or_insert(keyname, title="The Three Little Pigs")

Nota: Una instancia de modelo no tiene una entidad correspondiente en Datastore hasta que se escribe (put) por primera vez, ya sea explícitamente o mediante Model.get_or_insert().

Para crear un dict que sea una copia de los datos de una instancia de modelo, usa la función db.to_dict.

Constructor

El constructor para la clase Model se define de la manera siguiente:

class Model (parent=None, key_name=None, **kwds)

La superclase para definiciones de modelos de datos.

Durante la construcción, se llama al método validate() de cada propiedad. Las excepciones de tales llamadas se propagan a los emisores de este constructor.

Argumentos

parent
La clave o instancia de modelo para la entidad que es la principal de la nueva entidad.
key_name

El nombre clave para la entidad. El nombre se convierte en parte de la clave primaria. Si es None, se usa un ID numérico generado por el sistema para la clave.

El valor de key_name no debe tener el formato __*__.

El nombre de la clave se almacena como una string Unicode, con valores str convertidos como texto ASCII.

Si se llama a put() en este objeto, se reemplazará cualquier entidad de Datastore existente con la misma clave.

kwds
Valores iniciales para las propiedades de la instancia, como argumentos de palabra clave. Cada nombre se corresponde con un atributo definido en la clase Modelo.

Argumento adicional de palabra clave

key

La instancia Key explícita para la entidad. No se puede usar con key_name ni parent. Si es None, recurre al comportamiento de key_name y parent. Es útil cuando se usa allocate_ids() para reservar ID numéricos para entidades nuevas.

El valor de key debe ser una instancia Key válida.

Si se llama a put() en este objeto, se reemplazará cualquier entidad de Datastore existente con la misma clave.

Métodos de clase

La clase Model tiene los siguientes métodos de clase:

Model.get (keys)

Recupera la instancia (o instancias) de modelo para la clave (o claves) dadas. Las claves deben representar entidades del similar de modelo. Si una clave proporcionada no es del tipo correcto, se genera una excepción KindError.

Este método es similar a la función db.get(), con verificación de tipos adicional.

Argumentos

keys
La clave de la entidad que se recuperará, una representación de string de la clave o una lista de claves o sus representaciones de string.
read_policy
La política de lectura que especifica el nivel deseado de coherencia de datos:
STRONG_CONSISTENCY
Garantiza los resultados más recientes, pero se limita a un solo grupo de entidad.
EVENTUAL_CONSISTENCY
Puede abarcar varios grupos de entidad, pero a veces puede mostrar resultados obsoletos. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia sólida, pero no se garantiza.

Nota: Las consultas globales (no las principales) omiten este argumento.

plazo
El tiempo máximo en segundos que se esperará que el almacén de datos muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes establecerlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápido (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, reintentar la operación, probar con otra o agregarla a la lista de tareas en cola).

Si keys consiste en una sola clave (o su representación de string), este método muestra la instancia de modelo asociada a la clave si la clave existe en Datastore. Si no existe, muestra None. Si keys es una lista, el valor que se muestra es una lista correspondiente de instancias de modelo, con valores None en los que no existe una entidad para una clave determinada.

Consulta también la función db.get().

Model.get_by_id (ids, parent=None)

Recupera la instancia (o instancias) de modelo para el ID (o los ID) numéricos dados.

Argumentos

ids
Un ID de entidad numérico, o una lista de ID numéricos.
parent
La entidad principal para las entidades solicitadas, como modelo o clave, o None (el valor predeterminado) si las entidades solicitadas no tienen una principal. Las entidades múltiples que solicite una llamada deben tener la misma entidad principal.
read_policy
La política de lectura que especifica el nivel deseado de coherencia de datos:
STRONG_CONSISTENCY
Garantiza los resultados más recientes, pero se limita a un solo grupo de entidad.
EVENTUAL_CONSISTENCY
Puede abarcar varios grupos de entidad, pero a veces puede mostrar resultados obsoletos. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia sólida, pero no se garantiza.

Nota: Las consultas globales (no las principales) omiten este argumento.

plazo
El tiempo máximo en segundos que se esperará que el almacén de datos muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes establecerlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápido (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, reintentar la operación, probar con otra o agregarla a la lista de tareas en cola).

Si ids consta de un ID numérico único, este método muestra la instancia de modelo asociada con el ID si existe en Datastore; de lo contrario, None. Si ids es una lista, el valor de retorno es una lista correspondiente de instancias de modelo, con valores None donde no existe entidad para un ID numérico determinado.

Model.get_by_key_name (key_names, parent=None)

Recupera las instancias de modelo para los nombres determinados.

Argumentos

key_names
Un nombre de la clave o una lista de nombres de la clave.
parent
La entidad principal para las entidades solicitadas, como una instancia o clave de modelo, o None (el valor predeterminado) si las entidades solicitadas no tienen una principal. Las entidades múltiples que se soliciten por una llamada deben tener la misma entidad principal.
read_policy
La política de lectura que especifica el nivel deseado de coherencia de datos:
STRONG_CONSISTENCY
Garantiza los resultados más recientes, pero se limita a un solo grupo de entidad.
EVENTUAL_CONSISTENCY
Puede abarcar varios grupos de entidad, pero a veces puede mostrar resultados obsoletos. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia sólida, pero no se garantiza.

Nota: Las consultas globales (no las principales) omiten este argumento.

plazo
El tiempo máximo en segundos que se esperará que el almacén de datos muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes establecerlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápido (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, reintentar la operación, probar con otra o agregarla a la lista de tareas en cola).

Si key_names consiste en un único nombre de clave, este método muestra la instancia de modelo asociada con el nombre si el nombre existe en Datastore. Si no existe, muestra None. Si key_names es una lista, el valor que se muestra es una lista correspondiente de instancias de modelo, con valores None en los que no existe una entidad para un nombre de clave determinado.

Model.get_or_insert (key_name, **kwds)

Intenta obtener la entidad del tipo del modelo con el nombre de clave dado. Si existe, get_or_insert() simplemente lo muestra. Si no existe, una entidad nueva con el tipo, nombre y parámetros especificados en kwds se crea, almacena y muestra.

Las operaciones get y subsecuentes (posibles) put se unen en una transacción para garantizar la atomicidad. Esto significa que get_or_insert() nunca reemplazará una entidad existente y que insertará una entidad nueva solo si no existe una entidad con el tipo y nombre especificados. En otras palabras, get_or_insert() es equivalente al siguiente código de Python:

def txn(key_name, **kwds):
  entity = Story.get_by_key_name(key_name, parent=kwds.get('parent'))
  if entity is None:
    entity = Story(key_name=key_name, **kwds)
    entity.put()
  return entity

def get_or_insert(key_name, **kwargs):
  return db.run_in_transaction(txn, key_name, **kwargs)

get_or_insert('some key', title="The Three Little Pigs")

Argumentos

key_name
El nombre de la clave de la entidad.
kwds
Argumentos de palabra clave para pasar al constructor de la clase modelo si no existe una instancia con el nombre de clave especificado. El argumento parent es obligatorio si la entidad deseada tiene un elemento superior.

Nota: get_or_insert() no acepta un argumento read_policy o deadline.

El método muestra una instancia de la clase modelo que representa la entidad solicitada, ya sea una existente o que el método haya creado. Al igual que con todas las operaciones de Datastore, este método puede generar un TransactionFailedError si la transacción no se pudo completar.

Model.all (keys_only=False)

Muestra un objeto Query que representa todas las entidades para el tipo correspondiente a este modelo. Los métodos en el objeto Query pueden aplicar filtros y clasificar los órdenes de la consulta antes de que se ejecute; consulta la página de la clase Query para obtener más información.

Argumentos

keys_only
Si la consulta debe mostrar entidades completas o solo claves. Las consultas que muestran claves son más rápidas y usan menos tiempo de CPU que las consultas que muestran entidades completas.
Model.gql (query_string, *args, **kwds)

Realiza una consulta de GQL sobre instancias de este modelo.

Argumentos

query_string
La parte de la consulta de GQL que se encuentra a continuación de SELECT * FROM model (que se implica mediante el uso de este método de clase).
args
Vinculaciones de parámetros de posicionamiento, similares al constructor GqlQuery().
kwds
Vinculaciones de parámetros de palabras clave, similares al constructor GqlQuery().
s = Story.gql("WHERE title = :1", "Little Red Riding Hood")

s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")

El valor de retorno es un objeto GqlQuery, que se puede usar para acceder a los resultados.

Model.kind()
Muestra el tipo de modelo, generalmente el nombre de la subclase Modelo.
Model.properties()
Muestra un diccionario de todas las propiedades definidas para esta clase modelo.

Métodos de instancias

Las instancias de modelo tienen los métodos siguientes:

key()

Muestra la Key de Datastore para esta instancia de modelo.

La clave de una instancia de modelo incluye el tipo de entidad de la instancia junto con un identificador único. El identificador puede ser una string de nombre de clave que la aplicación asigna de forma explícita cuando se crea la instancia o un ID numérico con números enteros que App Engine asigna de forma automática cuando se escribe la instancia (put) en Datastore. Llamar a key() antes de que se asigne un identificador a la instancia genera una excepción NotSavedError.

put()

Almacena la instancia de modelo en Datastore. Si la instancia de modelo se creó recientemente y nunca se ha almacenado, este método crea una entidad de datos nueva en Datastore. De lo contrario, actualiza la entidad de datos con los valores de propiedad actuales.

El método muestra la clave de la entidad almacenada.

Si no se pudieron confirmar los datos, se genera una excepción TransactionFailedError.

Argumentos

plazo
El tiempo máximo en segundos que se esperará que el almacén de datos muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes establecerlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápido (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, reintentar la operación, probar con otra o agregarla a la lista de tareas en cola).
delete()

Borra la instancia de modelo de Datastore. Si la instancia nunca se escribió (put) en Datastore, la eliminación genera una excepción NotSavedError.

Argumentos

plazo
El tiempo máximo en segundos que se esperará que el almacén de datos muestre un resultado antes de anular con un error. Acepta un valor de número entero o punto flotante. No puedes establecerlo con un valor más alto que el predeterminado (60 segundos), pero puedes reducirlo para asegurarte de que una operación en particular falle rápido (por ejemplo, con el objetivo de mostrar una respuesta más rápida al usuario, reintentar la operación, probar con otra o agregarla a la lista de tareas en cola).
is_saved()

Muestra True si la instancia del modelo se escribió (put) en Datastore al menos una vez.

Este método solo verifica que la instancia se haya escrito en Datastore al menos una vez desde que se creó. No verifica si las propiedades de la instancia se han actualizado desde la última vez que se escribió.

dynamic_properties()

Muestra una lista de los nombres de todas las propiedades dinámicas definidas para esta instancia de modelo. Esto solo se aplica a las instancias de las clases Expando. Para las instancias de modelo que no sean de Expando, este muestra una lista vacía.

parent()

Muestra una instancia de modelo para la entidad principal de esta instancia o None si esta instancia no tiene una principal.

parent_key()

Muestra la Key de la entidad principal de esta instancia o None si esta instancia no tiene una principal.

to_xml()

Muestra una representación XML de la instancia de modelo.

Los valores de propiedad coinciden con las especificaciones de Atom y Data.

Nombres de propiedad no permitidos

Datastore y su API imponen varias restricciones en los nombres de las propiedades de la entidad y los atributos de la instancia de modelo.

Datastore reserva todos los nombres de propiedad que comienzan y terminan con dos guiones bajos (__*__). Una entidad de Datastore no puede tener una propiedad con ese nombre.

La API del modelo de Python ignora todos los atributos en una clase Model o Expando que comienzan con un guion bajo (_). Tu aplicación puede usar estos atributos para asociar datos con los objetos del modelo que no se guardan en Datastore.

Por último, la API del modelo de Python usa atributos de objeto para definir las propiedades de un modelo y, de forma predeterminada, las propiedades de la entidad de Datastore llevan el nombre de los atributos. Debido a que la clase Model tiene varias propiedades y métodos para otros fines, esos atributos no se pueden usar para las propiedades en la API de Python. Por ejemplo, un modelo no puede tener una propiedad a la que se acceda con el atributo key.

Sin embargo, una propiedad puede especificar un nombre diferente para Datastore que el nombre del atributo al proporcionar un argumento name al constructor de la propiedad. Esto permite que la entidad Datastore tenga un nombre de propiedad similar a un atributo reservado en la clase Model y use un nombre de atributo diferente en la clase.

class MyModel(db.Model):
  obj_key = db.StringProperty(name="key")

Los siguientes nombres de atributos están reservados por la clase Model en la API de Python:

  • all
  • app
  • copy
  • delete
  • entity
  • entity_type
  • fields
  • from_entity
  • get
  • gql
  • instance_properties
  • is_saved
  • key
  • key_name
  • kind
  • parent
  • parent_key
  • properties
  • put
  • setdefault
  • to_xml
  • update