The Property Class

Note: Developers building new applications are strongly encouraged to use the NDB Client Library, which has several benefits compared to this client library, such as automatic entity caching via the Memcache API. If you are currently using the older DB Client Library, read the DB to NDB Migration Guide

The Property class is the superclass of property definitions for data models. A Property class defines the type of a property's value, how values are validated, and how values are stored in the datastore.

Property is provided by the google.appengine.ext.db module.

Introduction

A property class describes the value type, default value, validation logic and other features of a property of a Model. Each property class is a subclass of the Property class. The datastore API includes property classes for each of the datastore value types, and several others that provide additional features on top of the datastore types. See Types and Property Classes.

A property class can accept configuration from arguments passed to the constructor. The base class constructor supports several arguments that are typically supported in all property classes, including all those provided in the datastore API. Such configuration can include a default value, whether or not an explicit value is required, a list of acceptable values, and custom validation logic. See the documentation for a specific property type for more information on configuring the property.

A property class defines the model for a datastore property. It does not contain the property value for a model instance. Instances of the Property class belong to the Model class, not instances of the class. In Python terms, property class instances are "descriptors" that customize how attributes of Model instances behave. See the Python documentation for more information about descriptors.

Constructor

The constructor of the Property base class is defined as follows:

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

The superclass of model property definitions.

Arguments

verbose_name

A user-friendly name of the property. This must always be the first argument to a property constructor. The djangoforms library uses this to make labels for form fields, and others can use it for a similar purpose.

name

The storage name for the property, used in queries. This defaults to the attribute name used for the property. Because model classes have attributes other than properties (which cannot be used for properties), a property can use name to use a reserved attribute name as the property name in the datastore, and use a different name for the property attribute. See Disallowed Property Names for more information.

default

A default value for the property. If the property value is never given a value, or is given a value of None, then the value is considered to be the default value.

Note: Model class definitions are cached along with the rest of the application code. This includes caching default values for properties. Do not set a default in the model definition with data specific to the request (such as users.get_current_user()). Instead, define an __init__() method for the Model class that initializes the property values.

required

If True, the property cannot have a value of None. A model instance must initialize all required properties in its constructor so that the instance is not created with missing values. An attempt to create an instance without initializing a required property, or an attempt to assign None to a required property, raises a BadValueError.

A property that is both required and has a default value uses the default value if one is not given in the constructor. However, the property cannot be assigned a value of None, and there is no automatic way to restore the default value after another value has been assigned. You can always access the property's default attribute to get this value and assign it explicitly.

validator

A function that should be called to validate the property's value when the value is assigned. The function takes the value as its only argument, and raises an exception if the value is invalid. The given validator is called after other validation has taken place, such as the check that a required property has a value. When a non-required property is not given a value, the validator is called with argument None.

choices

A list of acceptable values for the property. If set, the property cannot be assigned a value not in the list. As with required and other validation, a model instance must initialize all properties with choices so that the instance is not created with invalid values. If choices is None, then all values that otherwise pass validation are acceptable.

indexed

Whether this property should be included in the built-in and developer-defined indexes. If False, entities written to the datastore will never be returned by queries that sort or filter on this property, similar to Blob and Text properties.

Note: Every indexed property adds a small amount of overhead, CPU cost, and latency to put() and delete() calls. If you'll never need to filter or sort on a property, consider using indexed=False to avoid that overhead. Be careful, though! If you decide later that you want the property indexed after all, changing it back to indexed=True will only affect writes from that point onward. Entities that were originally written with indexed=False will not be re-indexed.

Class Attributes

Subclasses of the Property class define the following class attribute:

data_type

The Python data type or class the property accepts as a Python-native value.

Instance Methods

Instances of Property classes have the following methods:

default_value()

Returns the default value for the property. The base implementation uses the value of the default argument passed to the constructor. A property class could override this to provide special default value behavior, such as DateTimeProperty's auto-now feature.

validate(value)

The complete validation routine for the property. If value is valid, it returns the value, either unchanged or adapted to the required type. Otherwise it raises an appropriate exception.

The base implementation checks that value is not None if required (the required argument to the base Property constructor), the value is one of the valid choices if the property was configured with choices (the choices argument), and the value passes the custom validator if any (the validator argument).

The validation routine is called when a model using the property type is instantiated (with default or initialized values), and when a property of the type is assigned a value. The routine should not have side effects.

empty(value)

Returns True if value is considered an empty value for this property type. The base implementation is equivalent to not value, which is sufficient for most types. Other types, like a Boolean type, can override this method with a more appropriate test.

get_value_for_datastore(model_instance)

Returns the value that ought to be stored in the datastore for this property in the given model instance. The base implementation simply returns the Python-native value of the property in the model instance. A property class can override this to use a different data type for the datastore than for the model instance, or to perform other data conversion just prior to storing the model instance.

make_value_from_datastore(value)

Returns the Python-native representation for the given value from the datastore. The base implementation simply returns the value. A property class can override this to use a different data type for the model instance than for the datastore.

make_value_from_datastore_index_value(value)

Returns the Python-native representation for the given value from the datastore index. The base implementation simply returns the value. A property class can override this to use a different data type for the model instance than for the datastore.