Property 类

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

Property 由 google.appengine.ext.db 模块提供。

• 简介
• Property()
• 类属性：
  • Property.data_type
• 实例方法：
  • default_value()
  • validate()
  • empty()
  • get_value_for_datastore()
  • make_value_from_datastore()

简介

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

Property 类可接受通过传递到构造函数的参数所进行的配置。基类构造函数支持通常在所有 Property 类中都受支持的多个参数，包括在数据存储区 API 中提供的所有参数。此类配置可以包含默认值（无论是否需要确切值）、可接受的值的列表以及自定义的验证逻辑。有关配置该属性的详细信息，请参阅特定属性类型的文档。

Property 类定义数据存储区属性的模型。它不包含 Model 实例的属性值。Property 类的实例属于 Model 类，而不是该类的实例。在 Python 术语中，Property 类实例是可以自定义 Model 实例属性的行为方式的“描述符”。有关描述符的详细信息，请参阅 Python 文档。

构造函数

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

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

Model 属性定义的超类。

参数：

verbose_name

用户友好的属性名称。该参数必须始终是属性构造函数的第一个参数。djangoforms 库使用该参数来为表格字段标记标签，其他库可使用该参数进行类似的操作。

name

属性的存储名称，可在查询中使用。默认情况下，该名称是用于属性的属性名称。由于 Model 类具有属性以外的属性（无法用于属性），因此属性可以使用 name 来使用保留的属性名称来作为数据存储区中的属性名称，并使用其他名称作为属性名称。有关详细信息，请参阅禁止使用的属性名称。

default

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

注意：Model 类定义随应用程序代码的其余部分一起缓存。其中包括缓存属性的默认值。请勿通过请求特定的数据（例如 users.get_current_user()）在 Model 定义中设置 default。而应为初始化属性值的 Model 类定义 __init__() 方法。

required

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

如果在构造函数中没有为必需并具有默认值的属性赋值，则该属性会使用默认值。但是，不能为该属性分配 None 值，也不能在分配了其他值后自动恢复默认值。您随时可以访问属性的 default 属性来获取该值并对其进行显式分配。

validator

分配属性值时应调用便以验证该值的函数。该函数使用该属性值作为其唯一的参数，如果属性值无效，则会引发异常错误。在执行了其他验证（例如检查必需的属性是否具有值）之后，便会调用指定的验证程序。

choices

可接受的属性值的列表。如果设置了该参数，则不能给属性分配该列表以外的其他值。与 required 和其他验证一样，Model 实例必须初始化选择的所有属性，这样才不会使用无效值创建实例。如果 choices 为 None，则以其他方式通过验证的所有值都可以接受。

类属性

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

data_type

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

实例方法

Property 类实例具有以下方法：

default_value()

返回属性的默认值。基础实施方案使用传递到构造函数 default 参数的值。Property 类可以替换该方法以提供特殊的默认值行为，例如 DateTimeProperty 的 auto-now 功能。

validate(value)

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

基础实施方案会检查以下内容：如有需要，value 是否为 None（传递到基础 Property 构造函数的 required 参数）；如果已根据选择的内容对属性进行了配置，该值是否为一个有效的选择（choices 参数）；如果存在，该值是否通过自定义验证程序的验证（validator 参数）。

使用该属性类型的 Model 进行实例化（使用默认值或初始化值）以及为该类型的属性进行赋值时，会调用该验证程序。该程序不应该有副作用。

empty(value)

如果该属性类型的 value 使用空值，则返回 True。基础实施方案与 not value 等效，足以适用于大多数类型。其他类型（如布尔值类型）可以使用更合适的测试来替换该方法。

get_value_for_datastore(model_instance)

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

make_value_from_datastore(value)

从数据存储区中返回指定值的 Python 自有表达方式。基础实施方案只返回该值。Property 类可以将其替换，以便 Model 实例能够使用与数据存储区不同的其他数据类型。