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 del 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 subclase de Model. Las propiedades del modelo se definen mediante 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 tipos de nombres que comienzan con dos guiones bajos (__). Las subclases modelo no deben usar tales 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 y el nombre de clave de la entidad 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 de forma explícita o a través de Model.get_or_insert().

Para crear un dict que es 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 el valor es None, se usa un ID generado por el sistema para la clave.

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

El nombre de clave se almacena como una string Unicode, con los valores de str convertidos en 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 para key_name y parent. Es útil cuando se usa allocate_ids() a fin de reservar ID numéricos para las 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 tipo 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 entidades.

EVENTUAL_CONSISTENCY

Puede abarcar varios grupos de entidades, 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.

deadline

El tiempo máximo en segundos que se esperará que Datastore 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 con la clave si esta existe en Datastore, de lo contrario, 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 entidades.

EVENTUAL_CONSISTENCY

Puede abarcar varios grupos de entidades, 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.

deadline

El tiempo máximo en segundos que se esperará que Datastore 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 consiste en un ID numérico único, este método muestra la instancia de modelo asociada con el ID si el ID existe en Datastore, de lo contrario, None. Si ids 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 ID numérico determinado.

Model.get_by_key_name (key_names, key_names=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 entidades.

EVENTUAL_CONSISTENCY

Puede abarcar varios grupos de entidades, 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.

deadline

El tiempo máximo en segundos que se esperará que Datastore 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 solo nombre de clave, este método muestra la instancia de modelo asociada con el nombre si el nombre existe en Datastore, de lo contrario, 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, key_name)

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, se crea, almacena y muestra una entidad nueva con el tipo, el nombre y los parámetros en kwds.

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, si no que insertará una entidad nueva si y solo si no existe una entidad con el tipo y nombre dados. 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 una entidad principal.

Nota: get_or_insert() no acepta un argumento read_policy ni 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, query_string, query_string)

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 que se muestra 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 instancia

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

deadline

El tiempo máximo en segundos que se esperará que Datastore 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 nunca se escribió la instancia (put) en Datastore, el borrarla genera una excepción NotSavedError.

Argumentos

deadline

El tiempo máximo en segundos que se esperará que Datastore 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 de 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 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 propiedades que empiezan 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 de una clase Model o Expando que empiezan con un guion bajo (_). La 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 con 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 si da un argumento de name al constructor de la propiedad. Esto permite que la entidad de 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: