Note:Developers building new applications arestrongly encouraged to use theNDB Client Library, which has several benefitscompared to this client library, such as automatic entity caching via the MemcacheAPI. If you are currently using the older DB Client Library, read theDB 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 thegoogle.appengine.ext.db module.

Introduction

A property class describes the value type, default value, validation logic and other features of a property of aModel. 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. SeeTypes 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. Seethe 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. Thedjangoforms 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 usename to use a reserved attribute name as the property name in the datastore, and use a different name for the property attribute. SeeDisallowed 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 ofNone, 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 adefault in the model definition with data specific to the request (such asusers.get_current_user()). Instead, define an__init__() method for theModel class that initializes the property values.

required

IfTrue, the property cannot have a value ofNone. 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 assignNone to a required property, raises aBadValueError.

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 ofNone, and there is no automatic way to restore the default value after another value has been assigned. You can always access the property'sdefault 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 argumentNone.

choices

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

indexed

Whether this property should be included in the built-in and developer-definedindexes. IfFalse, entities written to the datastore will never be returned by queries that sort or filter on this property, similar toBlob andText properties.

Note: Every indexed property adds a small amount of overhead, CPU cost, and latency toput() anddelete() calls. If you'll never need to filter or sort on a property, consider usingindexed=False to avoid that overhead. Be careful, though! If you decide later that you want the property indexed after all, changing it back toindexed=True will only affect writes from that point onward. Entities that were originally written withindexed=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 thedefault argument passed to the constructor. A property class could override this to provide special default value behavior, such asDateTimeProperty's auto-now feature.

validate(value)

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

The base implementation checks thatvalue is notNone if required (therequired argument to the base Property constructor), the value is one of the valid choices if the property was configured with choices (thechoices argument), and the value passes the custom validator if any (thevalidator 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)

ReturnsTrue ifvalue is considered an empty value for this property type. The base implementation is equivalent tonot 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.