Property クラス

注: 新しいアプリケーションを作成する際は、NDB クライアント ライブラリを使用することを強くおすすめします。NDB クライアント ライブラリには、Memcache API によるエンティティの自動キャッシュをはじめ、このクライアント ライブラリにはないメリットがあります。古い DB クライアント ライブラリを現在使用している場合は、DB から NDB への移行ガイドをお読みください。

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

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

はじめに

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

プロパティ クラスは、コンストラクタに渡された引数から設定を受け取ることができます。ベースクラスのコンストラクタは、すべてのプロパティ クラスで通常サポートされる複数の引数をサポートします。これには、Datastore API で提供されるすべての引数が含まれます。このような設定には、デフォルト値、明示的な値が必要かどうか、有効な値のリスト、カスタム検証ロジックを含めることができます。特定のプロパティの詳しい設定方法については、そのプロパティ型のドキュメントをご覧ください。

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

コンストラクタ

Property ベースクラスのコンストラクタは、次のように定義されています。

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

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

引数

verbose_name

プロパティのわかりやすい名前。これは、常にプロパティ コンストラクタの最初の引数である必要があります。djangoforms ライブラリでは、これを使用してフォーム フィールドのラベルを作成します。他のライブラリでも同様の目的でこれを使用できます。

name

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

default

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

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

required

True の場合は、プロパティに値 None を指定できません。モデル インスタンスでは、値がない状態でインスタンスが作成されないように、すべての必須プロパティをコンストラクタで初期化する必要があります。必須プロパティを初期化せずにインスタンスを作成しようとする、または必須プロパティに None を割り当てようとすると、BadValueError が発生します。

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

validator

プロパティの値を割り当てたときに値を検証するために呼び出す必要がある関数。この関数は、唯一の引数として値を取り、値が無効な場合は例外を生成します。指定された検証ツールは、必須プロパティに値があるかどうかのチェックなど、他の検証が行われた後で呼び出されます。必須でないプロパティに値が指定されなかった場合は、引数に None を指定して検証ツールが呼び出されます。

choices

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

indexed

組み込みまたはデベロッパー定義のインデックスにこのプロパティを含めるかどうか。False が指定されてデータストアに書き込まれたエンティティは、Blob プロパティや Text プロパティと同じように、このプロパティで並べ替えまたはフィルタリングするクエリでは返されません。

注: プロパティをインデックスに登録すると、put() と delete() の呼び出し時に少量のオーバーヘッド、CPU コスト、レイテンシが追加されます。このプロパティでフィルタリングや並べ替えを行う必要がない場合は、indexed=False を使用してオーバーヘッドを回避することを検討してください。ただし、注意事項があります。プロパティがインデックスに登録されるように、時間をおいて indexed=True へ変更した場合、それ以降の書き込みにのみ反映されます。indexed=False で書き込まれたエンティティは、インデックスに再登録されません。

クラス属性

Property クラスのサブクラスでは、次のクラス属性が定義されます。

data_type

プロパティに Python ネイティブ値として指定できる Python データ型またはクラス。

インスタンス メソッド

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

default_value()

プロパティのデフォルト値を返します。ベース実装では、コンストラクタに渡された default 引数の値が使用されます。プロパティ クラスでこれをオーバーライドして、特別なデフォルト値の動作（DateTimeProperty で自動的に現在日時を設定する機能など）を設定できます。

validate(value)

プロパティの完全な検証ルーチン。value が有効な場合は、その値を変更せずに、または必要な型に変換してから返します。無効な場合は、該当する例外を生成します。

ベース実装では、必須の value（ベース Property コンストラクタへの required 引数）が None でないこと、プロパティが選択肢（choices 引数）を使用して構成されている場合には値が有効な選択肢のいずれかであること、さらに、カスタム検証ツールがある（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 ネイティブ表現を返します。ベース実装は、値を返すだけです。プロパティ クラスでこれをオーバーライドして、データストアとは異なるデータ型をモデル インスタンスで使用できます。