Property 类

注意强烈建议构建新应用的开发者使用 NDB 客户端库,它与 DB 客户端库相比具有多项优势,例如可通过 Memcache API 进行自动实体缓存。如果您当前使用的是较早的 DB 客户端库,请参阅 DB 到 NDB 的迁移指南

Property 类是数据模型的属性定义的父类。Property 类定义了属性值的类型、值的验证方式以及值在数据存储区中的存储方式。

Propertygoogle.appengine.ext.db 模块提供。

简介

属性类描述了模型属性的值类型、默认值、验证逻辑和其他功能。每个属性类都是 Property 类的子类。数据存储区 API 包含每个数据存储区值类型的属性类,以及提供除数据存储区类型以外的其他功能的多个其他属性类。请参阅 Types 和 Property 类

属性类可接受来自传递给构造函数的参数的配置。基类构造函数支持所有属性类中通常都支持的多个参数,包括数据存储区 API 中提供的所有参数。此类配置可以包含默认值(无论是否需要明确的值)、可接受值的列表以及自定义的验证逻辑。如需详细了解如何配置该属性,请参阅特定属性类型的文档。

属性类定义了数据存储区属性的模型。它不包含模型实例的属性值。Property 类的实例属于模型类,而不是该类的实例。在 Python 术语中,属性类实例是指自定义模型实例属性行为方式的“描述符”。如需详细了解描述符,请参阅 Python 文档

构造函数

Property 基类的构造函数定义如下:

class Property(verbose_name=None, verbose_name=None, verbose_name=None, verbose_name=False, verbose_name=None, verbose_name=None, verbose_name=True)

模型属性定义的父类。

参数

verbose_name
简单易懂的属性名称。该参数必须始终是属性构造函数的第一个参数。djangoforms 库使用该参数为表单字段加标签,其他库可以将其用于类似目的。
name
属性的存储名称,可在查询中使用。这默认为用于属性的属性名称。由于模型类具有属性 (property) 以外的特性(attribute)(无法用于属性),因此属性可以使用 name 将保留的特性名称用作数据存储区中的属性名称,并且给属性特性指定一个不同的名称。如需了解详情,请参阅禁用的属性名称
默认

属性的默认值。如果属性值从未指定过值或指定的值为 None,则该属性值会视为默认值。

注意:模型类定义随应用代码的其余部分一起缓存。其中包括属性的缓存默认值。请勿使用特定于请求的数据(例如 users.get_current_user())在模型定义中设置 default。相反,请定义 Model 类的 __init__() 方法,可初始化属性值。

required

如果为 True,则属性值不能为 None。模型实例必须通过其构造函数初始化所有必需的属性,这样创建实例时才不会缺少值。在没有初始化必需属性的情况下创建实例的尝试,或将 None 分配给必需属性的尝试,都会引发 BadValueError

如果构造函数中不提供必需且具有默认值的属性,则该属性会使用默认值。但是,不能为该属性分配 None 值,也不能在分配了其他值后自动恢复默认值。您始终可以访问该属性的 default 特性来明确获取并分配此值。

验证器
分配属性值时为验证该值而应该调用的函数。该函数把该属性值作为其唯一参数,如果该值无效,则会引发异常。执行其他验证(例如,检查必需的属性是否具有一个值)后,会调用指定的验证程序。如果未给非必需属性指定值,则使用参数 None 调用验证程序。
choices
可接受的属性值的列表。如果设置了该参数,则不能给属性分配该列表以外的其他值。与 required 和其他验证一样,模型实例必须初始化选择的所有属性,这样才不会使用无效值创建实例。如果 choicesNone,则所有以其他方式通过验证的值都是可接受的。
indexed

不论开发者定义的内置索引中是否应该包含此属性。如果为 False,则对此属性(类似于 BlobText 属性)进行排序或过滤的查询绝对不会返回写入到数据存储区的实体。

注意:每个编入索引的属性都会增加少量开销、CPU 费用,并延长对 put()delete() 调用的时间。如果您根本无需对属性过滤或排序,请考虑使用 indexed=False 以避免这类开销。尽管如此,仍请务必小心谨慎!如果您稍后确定需要将该属性编入索引,则将它重新更改为 indexed=True 时,仅会影响从该点向前的写入内容。最初使用 indexed=False 写入的实体都不会重新编入索引。

类属性

Property 类的子类定义以下类属性:

data_type
属性接受作为 Python 自有值的 Python 数据类型或类。

实例方法

Property 类实例具有以下方法:

default_value()

返回属性的默认值。基本实现方案使用传递给构造函数 default 参数的值。属性类可以替换该参数,以提供特殊默认值行为,如 DateTimeProperty 的 auto-now 功能。

validate(value)

属性的完整验证程序。如果 value 有效,则会返回该值(保持不变或根据必需的类型进行了改变)。否则,便会引发相应的异常。

基本实现方案会检查 value 是否为 None(如果需要,基本 Property 构造函数的 required 参数),检查 value 是否为有效选择之一(如果该属性使用 choices 配置,choices 参数)以及检查 value 是否通过自定义验证程序(如果有,validator 参数)。

当使用默认值或初始化值实例化使用该属性类型的模型时,以及为该类型的属性分配值时,会调用该验证例程。该例程不应该有副作用。

empty(value)

如果 value 被视为此属性类型的空值,则返回 True。基本实现方案相当于 not value,这对于大多数类型来说已足够。其他类型(如布尔值类型)可以使用更合适的测试来替换该方法。

get_value_for_datastore(model_instance)

返回应该存储在数据存储区中且为指定模型实例中的该属性的值。基本实现方案只会返回模型实例中该属性的 Python 自有值。属性类可以将其替换,以便数据存储区能够使用与模型实例不同的其他数据类型,或在存储模型实例之前执行其他数据转换。

make_value_from_datastore(value)

从数据存储区中返回指定值的 Python 原生表示法。基本实现方案只返回该值。属性类可以将其替换,以便模型实例能够使用与数据存储区不同的其他数据类型。

make_value_from_datastore_index_value(value)

从数据存储区索引中返回指定值的 Python 原生表示法。基本实现方案只返回该值。属性类可以将其替换,以便模型实例能够使用与数据存储区不同的其他数据类型。