La clase Property

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 Property es la superclase que permite definir propiedades para los modelos de datos. Una clase Property define el tipo del valor de una propiedad, cómo se validan los valores y cómo se almacenan en el almacén de datos.

Property lo proporciona el módulo google.appengine.ext.db.

Introducción

Una clase de propiedad describe el tipo de valor, el valor predeterminado, la lógica de validación y otras características de una propiedad de un modelo. Cada clase de propiedad es una subclase de la clase Property. El API de almacén de datos incluye clases de propiedad para cada uno de los tipos de valor del almacén de datos y otras que proporcionan funciones adicionales aparte de los tipos de almacén de datos. Consulta Tipos y clases de propiedades.

Una clase de propiedad puede aceptar la configuración de los argumentos transmitidos al constructor. El constructor de clases básico admite varios argumentos que se suelen admitir en todas las clases de propiedad, incluidas todas aquellas proporcionadas en el API de almacén de datos. Esta configuración puede incluir un valor predeterminado, tanto si es necesario un valor explícito como si no, una lista de valores aceptables y una lógica de validación personalizada. Para obtener más información sobre la configuración de un tipo de propiedad específico, consulta la documentación de dicho tipo de propiedad.

Una clase de propiedad define el modelo de una propiedad del almacén de datos. No contiene el valor de propiedad de una instancia de modelo. Las instancias de la clase Property pertenecen a la clase Model, no a instancias de la clase. En términos de Python, las instancias de clase de propiedad son "descriptores" que personalizan el comportamiento de los atributos de las instancias de Model. Consulta la documentación de Python para obtener más información sobre los descriptores.

Constructor

El constructor de la clase básica Property se define del siguiente modo:

class Property(verbose_name=None, name=None, default=None, required=False, validator=None, choices=None, indexed=True)

La superclase de las definiciones de la propiedad Model.

Argumentos

verbose_name

Nombre de la propiedad fácil de usar. Siempre debe ser el primer argumento de un constructor de propiedades. La biblioteca djangoforms usa este elemento para crear etiquetas de campos de formulario, y otros pueden usarlo con un propósito similar.

name

Nombre de almacenamiento de la propiedad, que se usa en las consultas. El valor predeterminado es el nombre de atributo utilizado para la propiedad. Como las clases de modelo tienen atributos distintos de las propiedades (que no se pueden usar para las propiedades), una propiedad puede usar name para usar un nombre de atributo reservado como nombre de propiedad en el almacén de datos y usar un nombre diferente para el atributo de propiedad. Consulta más información en Nombres de propiedades no permitidos.

predeterminado

Un valor predeterminado para la propiedad. Si nunca se asigna un valor a la propiedad o se le asigna el valor None, se considera que tiene el valor predeterminado.

Nota: Las definiciones de clase de modelo se almacenan en caché junto con el resto del código de la aplicación. Esto incluye el almacenamiento en caché de los valores predeterminados de las propiedades. No defina un valor predeterminado en la definición del modelo con datos específicos de la solicitud (como users.get_current_user()). En su lugar, defina un método __init__() para la clase Model que inicialice los valores de las propiedades.

obligatorio

Si True, la propiedad no puede tener el valor None. Una instancia de modelo debe inicializar todas las propiedades necesarias en su constructor, de modo que a la instancia no le falten valores durante su creación. Si se intenta crear una instancia sin inicializar una propiedad obligatoria o se intenta asignar None a una propiedad obligatoria, se genera un error BadValueError.

Una propiedad que sea obligatoria y que tenga un valor predeterminado utilizará el valor predeterminado si no se proporciona uno en el constructor. Sin embargo, no se le puede asignar el valor None y no hay ninguna forma automática de restaurar el valor predeterminado después de que se haya asignado otro valor. Siempre puede acceder al atributo default de la propiedad para obtener este valor y asignarlo explícitamente.

validator

Función a la que se debe llamar para validar el valor de la propiedad cuando se le asigne un valor. La función utiliza el valor como su único argumento y genera una excepción si el valor no es válido. La función validator determinada se invoca después de que haya tenido lugar otra validación como, por ejemplo, la comprobación de que una propiedad obligatoria tiene un valor. Cuando no se asigna un valor a una propiedad no obligatoria, se llama al validador con el argumento None.

opciones

Una lista de valores aceptables para la propiedad. Si se establece, no se podrá asignar a la propiedad un valor que no esté en la lista. Al igual que con required y otras validaciones, una instancia de modelo debe inicializar todas las propiedades con opciones para que la instancia no se cree con valores no válidos. Si choices es None, se aceptarán todos los valores que superen la validación.

indexado

Indica si esta propiedad debe incluirse en los índices integrados y definidos por el desarrollador. Si False, las entidades escritas en el almacén de datos nunca se devolverán en las consultas que ordenen o filtren por esta propiedad, de forma similar a las propiedades Blob y Text.

Nota: Cada propiedad indexada añade una pequeña sobrecarga, un coste de CPU y una latencia a las llamadas put() y delete(). Si nunca vas a tener que filtrar ni ordenar por una propiedad, puedes usar indexed=False para evitar esa sobrecarga. No obstante, extrema las precauciones. Si más adelante decides que quieres que se indexe la propiedad, volver a cambiarla a indexed=True solo afectará a las escrituras a partir de ese momento. Las entidades que se escribieron originalmente con indexed=False no se volverán a indexar.

Atributos de clase

Las subclases de la clase Property definen el siguiente atributo de clase:

data_type

El tipo de datos o la clase de Python que acepta la propiedad como valor nativo de Python.

Métodos de instancia

Las instancias de las clases Property tienen los siguientes métodos:

default_value()

Devuelve el valor predeterminado para la propiedad. La implementación base usa el valor del argumento default que se ha transferido al constructor. Una clase de propiedad podría anular este valor para proporcionar un comportamiento especial del valor predeterminado, como la función de actualización automática de DateTimeProperty.

validate(value)

La rutina de validación completa de la propiedad. Si value es válido, devuelve el valor, sin cambios o adaptado al tipo requerido. De lo contrario, generará la excepción correspondiente.

La implementación base comprueba que value no sea None si es necesario (el argumento required del constructor de la propiedad base), que el valor sea una de las opciones válidas si la propiedad se ha configurado con opciones (el argumento choices) y que el valor supere el validador personalizado (el argumento validator).

La rutina de validación se invoca cuando se crea una instancia de un modelo que utiliza el tipo de propiedad (con valores inicializados o predeterminados) y cuando a una propiedad del tipo se le asigna un valor. La rutina no debe tener efectos secundarios.

empty(value)

Devuelve True si value se considera un valor vacío para este tipo de propiedad. La implementación base es equivalente a not value, que es suficiente para la mayoría de los tipos. Otros tipos como, por ejemplo, Boolean pueden anular este método con una prueba más adecuada.

get_value_for_datastore(model_instance)

Devuelve el valor que se debe almacenar en el almacén de datos para esta propiedad en la instancia de modelo determinada. La implementación básica devuelve simplemente el valor nativo Python de la propiedad en la instancia de modelo. Una clase de propiedad puede anularlo para utilizar un tipo de datos para el almacén de datos distinto de la instancia de modelo o para realizar otra conversión de datos justo antes de almacenar la instancia de modelo.

make_value_from_datastore(value)

Devuelve la representación nativa Python para el valor determinado desde el almacén de datos. La implementación básica devuelve simplemente el valor. Una clase de propiedad puede anularlo a fin de utilizar un tipo de datos distinto para la instancia de modelo y para el almacén de datos.

make_value_from_datastore_index_value(value)

Devuelve la representación nativa de Python del valor proporcionado del índice del almacén de datos. La implementación básica devuelve simplemente el valor. Una clase de propiedad puede anularlo a fin de utilizar un tipo de datos distinto para la instancia de modelo y para el almacén de datos.