Property クラス

Property クラスは、データ モデルのプロパティ定義用のスーパークラスです。Property クラスは、プロパティ値の型、検証方法、データストアでの格納方法を定義します。

Property は、google.appengine.ext.db モジュールによって提供されています。

• 概要
• Property()
• クラス属性:
  • Property.data_type
• インスタンス メソッド:
  • default_value()
  • validate()
  • empty()
  • get_value_for_datastore()
  • make_value_from_datastore()

概要

プロパティ クラスは Model の値型、デフォルト値、検証ロジックとその他の機能のプロパティを記述します。各プロパティ クラスは、Property クラスのサブクラスです。Datastore API には、各データストア値型のプロパティ クラスと、データストア型に機能を追加するその他のプロパティ クラスがいくつか含まれます。詳細については、型とプロパティ クラスをご覧ください。

プロパティ クラスは、コンストラクタに渡される引数による設定を受け入れることができます。基本クラスのコンストラクタは、Datastore API で提供されているものも含め、すべてのプロパティ クラスで通常サポートされている引数をサポートします。こうした設定には、明示値が必要であるかどうかには関わらないデフォルト値、許容値のリスト、カスタム検証ロジックを含めることができます。プロパティ設定については、該当するプロパティ型に関するドキュメントをご覧ください。

プロパティ クラスは、データストア プロパティのモデルを定義します。モデル インスタンス用のプロパティ値は含まれません。Property クラスのインスタンスは、Property クラスのインスタンスに属するのではなく、Model クラスに属します。Python の用語では、Property クラスのインスタンスは Model インスタンスの属性の動作をカスタマイズする「デスクリプタ」です。デスクリプタについては、Python ドキュメントをご覧ください。

コンストラクタ

Property 基本クラスのコンストラクタは次のように定義されています:

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

モデル プロパティ定義のスーパークラス。

引数:

verbose_name

このプロパティのユーザー フレンドリ名です。これは常に、プロパティ コンストラクタの最初の引数でなければなりません。これは、djangoforms ライブラリがフォーム フィールド用のラベルを作成するときに使用されますが、その他の類似した目的にも使用できます。

name

クエリで使用される、プロパティ用のストレージ名。デフォルトでは、プロパティに使用される属性名になっています。モデル クラスはプロパティ以外の属性を持っているため（この属性はプロパティには使用できません）、プロパティでは name を使用して、データストア内の予約された属性名をプロパティ名として使用し、プロパティ属性には別の名前を使用することができます。詳しくは、無効なプロパティ名をご覧ください。

default

プロパティのデフォルト値。プロパティ値に値が設定されなかった場合、または None の値が設定された場合、値はデフォルト値と見なされます。

注: Model クラスの定義は、その他のアプリケーション コードとともにキャッシュされます。これには、プロパティのデフォルト値のキャッシュも含まれます。モデル定義内の default をリクエストに固有のデータ（users.get_current_user() など）に設定しないでください。代わりに、プロパティ値を初期化する __init__() メソッドを Model クラスに定義してください。

required

True のとき、プロパティは None の値を取ることができません。モデル インスタンスは、コンストラクタ内の必要なプロパティをすべて初期化して、インスタンスが見つからない値で作成されることがないようにする必要があります。必要なプロパティを初期化せずにインスタンスを生成しようとするか、または必要なプロパティに None を割り当てようとすると、BadValueError になります。

デフォルト値を持つ必須プロパティは、コンストラクタでデフォルト値が設定されていない場合、このデフォルト値を使用します。ただし、このプロパティには None の値を割り当てることはできません。また、別の値が割り当てられた後に自動的にデフォルト値に戻す方法はありません。いつでもプロパティの default 属性にアクセスし、この値を取得して明示的に割り当てることができます。

validator

プロパティ値が割り当てられたとき、値を検証するために呼び出される関数。この関数は割り当てられた値を唯一の引数とし、値が無効の場合は例外を返します。指定されたバリデータは、必要なプロパティに値があるかのチェックといった他の検証の終了後に呼び出されます。

choices

プロパティの許容値のリスト。設定されると、リストにない値をプロパティに割り当てることはできません。required やその他の検証と同様に、インスタンスが無効な値で作成されることがないように、モデル インスタンスでは選択肢を使用してすべてのプロパティを初期化する必要があります。choices が None の場合、検証を通過した値はすべて受け入れ可能になります。

クラス属性

Property クラスのサブクラスは、次のクラス属性を定義します。

data_type

プロパティが Python ネイティブの値として受け入れる、Python データ型またはクラス。

インスタンス メソッド

Property クラスのインスタンスには次のメソッドがあります。

default_value()

プロパティのデフォルト値を返します。基本の実装では、コンストラクタに渡された default 引数の値を使用します。プロパティ クラスではこれをオーバーライドして、DateTimeProperty の auto-now 機能のような、特別なデフォルト値動作を提供することができます。

validate(value)

プロパティ用の完全な検証ルーチン。value が有効な場合、そのままの値、または必要な型に適合させた値を返します。それ以外の場合、対応する例外を返します。

基本の実装では、要求された場合、value が None でないか（基本の Property コンストラクタの required 引数）、プロパティに選択肢が設定されている場合、有効な選択肢であるか（choices 引数）、カスタム バリデータがある場合は、カスタム バリデータを通過するか（validator 引数）をチェックします。

検証ルーチンはプロパティ型を使用するモデルが（デフォルト値または初期化値によって）インスタンス化されるか、または型のプロパティに値が割り当てられると呼び出されます。このルーチンに副作用がないようにしてください。

empty(value)

このプロパティ型について、value が空の値であると見なした場合に True を返します。基本の実装では not value に等しく、これはほとんどの型で有効です。Boolean のような他の型では、このメソッドをより適切なテストでオーバーライドできます。

get_value_for_datastore(model_instance)

このプロパティで、指定されたモデル インスタンス内のデータストアに格納されるべき値を返します。基本の実装では、モデル インスタンス内のプロパティの Python ネイティブの値を返します。プロパティ クラスは、モデル インスタンスではなくデータストア用に別のデータ型を使用するためや、モデル インスタンスを格納する直前に他のデータ変換を実行するために、これをオーバーライドすることもできます。

make_value_from_datastore(value)

データストアからの指定された値に対し Python ネイティブ表現を返します。基本の実装では、単に値を返します。プロパティ クラスはデータストアではなくモデル インスタンス用に別のデータ型を使用するために、これをオーバーライドすることもできます。