La clase Model

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.

La clase Model es la superclase de las definiciones de modelos de datos.

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

Introducción

Una aplicación define un modelo de datos definiendo una clase que es una subclase de Model. Las propiedades del modelo se definen mediante atributos de clase e 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 instanciando una subclase de la clase Model. Las propiedades de una entidad se pueden asignar mediante 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 del modelo se usa como nombre del tipo de entidad de Datastore. Datastore reserva todos los nombres de tipo que empiezan por dos guiones bajos (__). Las subclases de modelo no deben usar estos nombres.

Los nombres de los atributos se usan como nombres de las propiedades correspondientes de una entidad. Los atributos de instancia de modelo cuyos nombres empiezan por 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 guarde en Datastore.

Datastore y la API de clase de modelo imponen varias restricciones en los nombres de las propiedades y los atributos de las instancias de modelo. Consulta la descripción completa en la sección Nombres de propiedades no permitidos.

Cada entidad tiene una clave,un identificador único que representa la entidad. La clave puede incluir un nombre de clave opcional,una cadena única entre las entidades del tipo indicado. El tipo y el nombre de la clave de la entidad se pueden usar con los métodos Key.from_path() y Model.get_by_key_name() para obtener la entidad.

Una entidad también puede tener una entidad principal opcional. Las relaciones entre elementos principales y secundarios forman grupos de entidades,que se utilizan para controlar la transaccionalidad y la localidad de los datos en Datastore. Una aplicación crea una relación de principal-secundario entre dos entidades pasando la entidad principal al constructor de la entidad secundaria como argumento parent.

El método Model.get_or_insert() se puede usar para obtener una entidad que puede que no exista, creándola 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 de forma explícita 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 de la clase Model se define de la siguiente manera:

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

Superclase para definir modelos de datos.

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

Argumentos

parent

La instancia del modelo o la clave de la entidad que es el elemento superior de la nueva entidad.

key_name

Nombre de la clave de la entidad. El nombre pasa a formar parte de la clave principal. Si 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 cadena Unicode, con valores str convertidos como texto ASCII.

Si llamas a put() en este objeto, se sobrescribirá cualquier entidad de Datastore que tenga la misma clave.

kwds

Valores iniciales de las propiedades de la instancia, como argumentos de palabras clave. Cada nombre corresponde a un atributo definido en la clase Model.

Argumento de palabra clave adicional

clave

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

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

Si llamas a put() en este objeto, se sobrescribirá cualquier entidad de Datastore que tenga la misma clave.

Métodos de clase

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

Model.get (keys)

Obtiene la instancia (o las instancias) del modelo de la clave (o las claves) proporcionada. Las claves deben representar entidades del tipo del 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 comprobación de tipos adicional.

Argumentos

claves

Clave de la entidad que se va a recuperar, una representación de cadena de la clave o una lista de claves o sus representaciones de cadena.

read_policy

Lee la política que especifica el nivel de coherencia de datos que quieres:

STRONG_CONSISTENCY

Garantiza los resultados más recientes, pero solo se puede usar con un grupo de entidades.

EVENTUAL_CONSISTENCY

Puede abarcar varios grupos de entidades, pero puede devolver resultados obsoletos en ocasiones. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia fuerte, pero no hay ninguna garantía.

Nota: Las consultas globales (no antecesoras) ignoran este argumento.

deadline

Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

Si keys consta de una sola clave (o su representación de cadena), este método devuelve la instancia del modelo asociada a la clave si la clave existe en Datastore. De lo contrario, devuelve None. Si keys es una lista, el valor devuelto es una lista correspondiente de instancias de modelo, con valores None cuando no existe ninguna entidad para una clave determinada.

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

Model.get_by_id (ids, parent=None)

Obtiene la instancia (o las instancias) del modelo correspondiente al ID numérico (o a los IDs) proporcionado.

Argumentos

ids

Un ID de entidad numérico o una lista de IDs numéricos.

parent

Entidad superior de las entidades solicitadas, como modelo o clave, o None (valor predeterminado) si las entidades solicitadas no tienen una entidad superior. Todas las entidades solicitadas en una llamada deben tener el mismo elemento superior.

read_policy

Lee la política que especifica el nivel de coherencia de datos que quieres:

STRONG_CONSISTENCY

Garantiza los resultados más recientes, pero solo se puede usar con un grupo de entidades.

EVENTUAL_CONSISTENCY

Puede abarcar varios grupos de entidades, pero puede devolver resultados obsoletos en ocasiones. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia fuerte, pero no hay ninguna garantía.

Nota: Las consultas globales (no antecesoras) ignoran este argumento.

deadline

Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

Si ids consta de un solo ID numérico, este método devuelve la instancia del modelo asociada al ID si este existe en Datastore. De lo contrario, devuelve None. Si ids es una lista, el valor devuelto es una lista correspondiente de instancias de modelo, con valores None cuando no existe ninguna entidad para un ID numérico determinado.

Model.get_by_key_name (key_names, parent=None)

Obtiene la instancia (o las instancias) del modelo correspondiente al nombre (o los nombres) de clave proporcionado.

Argumentos

key_names

Un nombre de clave o una lista de nombres de claves.

parent

La entidad superior de las entidades solicitadas, como instancia de modelo o clave, o None (el valor predeterminado) si las entidades solicitadas no tienen un elemento superior. Todas las entidades solicitadas en una llamada deben tener el mismo elemento superior.

read_policy

Lee la política que especifica el nivel de coherencia de datos que quieres:

STRONG_CONSISTENCY

Garantiza los resultados más recientes, pero solo se puede usar con un grupo de entidades.

EVENTUAL_CONSISTENCY

Puede abarcar varios grupos de entidades, pero puede devolver resultados obsoletos en ocasiones. Por lo general, las consultas de coherencia eventual se ejecutan más rápido que las de coherencia fuerte, pero no hay ninguna garantía.

Nota: Las consultas globales (no antecesoras) ignoran este argumento.

deadline

Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

Si key_names consta de un solo nombre de clave, este método devuelve la instancia del modelo asociada al nombre si el nombre existe en Datastore. De lo contrario, devuelve None. Si key_names es una lista, el valor devuelto es una lista correspondiente de instancias de modelo, con valores None si no existe ninguna 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 proporcionado. Si existe, get_or_insert() simplemente lo devuelve. Si no existe, se crea, se almacena y se devuelve una entidad con el tipo, el nombre y los parámetros indicados en kwds.

Las operaciones get y las operaciones put posteriores (si las hay) se envuelven en una transacción para asegurar la atomicidad. Esto significa que get_or_insert() nunca sobrescribirá una entidad, sino que insertará una nueva entidad si y solo si no existe ninguna entidad con el tipo y el nombre indicados. 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 palabras clave que se pasarán al constructor de la clase de 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 los argumentos read_policy ni deadline.

El método devuelve una instancia de la clase de modelo que representa la entidad solicitada, tanto si ya existía como si se creó con el método. Al igual que con todas las operaciones de Datastore, este método puede generar una TransactionFailedError si no se puede completar la transacción.

Model.all (keys_only=False)

Devuelve un objeto Query que representa todas las entidades del tipo correspondiente a este modelo. Los métodos del objeto de consulta pueden aplicar filtros y criterios de ordenación a la consulta antes de que se ejecute. Consulta la página de la clase Query para obtener más información.

Argumentos

keys_only

Indica si la consulta debe devolver entidades completas o solo claves. Las consultas que devuelven claves son más rápidas y usan menos tiempo de CPU que las consultas que devuelven entidades completas.

Model.gql (query_string, *args, **kwds)

Realiza una consulta GQL sobre las instancias de este modelo.

Argumentos

query_string

La parte de la consulta de GQL que sigue a SELECT * FROM model (que se implica al usar este método de clase).

args

Enlace de parámetros posicionales, similar al constructor GqlQuery().

kwds

Enlace de parámetros de palabras clave, similar 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 devuelto es un objeto GqlQuery, que se puede usar para acceder a los resultados.

Model.kind ()

Devuelve el tipo del modelo, normalmente el nombre de la subclase Model.

Model.properties ()

Devuelve un diccionario de todas las propiedades definidas para esta clase de modelo.

Métodos de instancia

Las instancias del modelo tienen los siguientes métodos:

clave ()

Devuelve el almacén de datos Key de esta instancia del modelo.

La clave de una instancia de modelo incluye el tipo de entidad de la instancia, así como un identificador único. El identificador puede ser una cadena de nombre de clave, asignada explícitamente por la aplicación cuando se crea la instancia, o un ID numérico entero,asignado automáticamente por App Engine cuando se escribe la instancia (put) en Datastore. Si llamas a key() antes de que se haya asignado un identificador a la instancia, se producirá una excepción NotSavedError.

put ()

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

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

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

Argumentos

deadline

Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

delete ()

Elimina la instancia del modelo del almacén de datos. Si la instancia nunca se ha escrito (put) en Datastore, la eliminación genera una excepción NotSavedError.

Argumentos

deadline

Tiempo máximo, en segundos, que debe esperar Datastore para devolver un resultado antes de cancelar la operación con un error. Acepta un número entero o un valor de punto flotante. No se puede definir un valor superior al predeterminado (60 segundos), pero se puede reducir para asegurarse de que una operación concreta falle rápidamente (por ejemplo, para devolver una respuesta más rápida al usuario, volver a intentar la operación, probar otra operación o añadir la operación a una cola de tareas).

is_saved ()

Devuelve True si la instancia del modelo se ha escrito (put) en Datastore al menos una vez.

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

dynamic_properties ()

Devuelve una lista de los nombres de todas las propiedades dinámicas definidas para esta instancia del modelo. Esto solo se aplica a las instancias de las clases Expando. Expando classes. En el caso de las instancias del modelo que no sean Expando, devolverá una lista vacía.

parent ()

Devuelve una instancia del modelo de la entidad superior de esta instancia o None si esta instancia no tiene un elemento superior.

parent_key ()

Devuelve el Key de la entidad superior de esta instancia o None si esta instancia no tiene ningún elemento superior.

to_xml ()

Devuelve una representación XML de la instancia del modelo.

Los valores de las propiedades se ajustan a las especificaciones Atom y Data.

Nombres de propiedades no permitidos

Datastore y su API imponen varias restricciones a los nombres de las propiedades de las entidades y los atributos de las instancias de modelos.

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

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

Por último, la API del modelo de Python usa atributos de objeto para definir las propiedades de un modelo. De forma predeterminada, las propiedades de la entidad Datastore se denominan como los atributos. Como la clase Model tiene varias propiedades y métodos para otros fines, esos atributos no se pueden usar para las propiedades de 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. Para ello, debe proporcionar un argumento name al constructor de la propiedad. De esta forma, la entidad de Datastore puede tener un nombre de propiedad similar a un atributo reservado de la clase Model y usar un nombre de atributo diferente en la clase.

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

La clase Model de la API de Python tiene reservados los siguientes nombres de atributos: