Model クラス

Model クラスは、データ モデル定義用のスーパークラスです。

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

• 概要
• Model()
• クラス メソッド:
  • Model.get()
  • Model.get_by_id()
  • Model.get_by_key_name()
  • Model.get_or_insert()
  • Model.all()
  • Model.gql()
  • Model.kind()
  • Model.properties()
• インスタンス メソッド:
  • key()
  • put()
  • delete()
  • is_saved()
  • parent()
  • parent_key()
  • to_xml()
• 無効なプロパティ名

概要

アプリケーションは、Model をサブクラスするクラスを定義することで、データ モデルを定義します。モデルのプロパティは、クラス属性と Property クラス インスタンスを使用して定義されます。次に例を示します。

class Story(db.Model):
  title = db.StringProperty()
  body = db.TextProperty()
  created = db.DateTimeProperty(auto_now_add=True)

アプリケーションは、Model クラスのサブクラスをインスタンス化して、新しいデータ エンティティを作成します。エンティティのプロパティは、インスタンスの属性を使用するか、コンストラクタに対するキーワード引数として割り当てられます。

s = Story()
s.title = "The Three Little Pigs"

s = Story(title="The Three Little Pigs")

モデル サブクラス名がデータストア エンティティの種類の名前として使用されます。属性名が対応するエンティティのプロパティ名として使用されます。名前がアンダースコア（_）で始まるモデル インスタンス属性は無視されるため、アプリケーションはこれらの属性を使用して、データをデータストアに保存されていないモデル インスタンスに格納することができます。

データストアとモデル クラス API は、プロパティ名とモデル インスタンス属性にいくつかの制限を設定します。詳しくは、無効なプロパティ名をご覧ください。

データ エンティティは任意の親エンティティを持つことができます。エンティティ グループは親子関係で構成されており、データストア内のトランザクション性およびデータの局所性の制御に使用されます。アプリケーションは、親エンティティを parent 引数として、子エンティティのコンストラクタに渡し、2 つのエンティティ間に親子関係を作成します。親と祖先に関する詳しい情報は、キーとエンティティ グループをご覧ください。

すべてのエンティティは、エンティティを表す一意の識別子であるキーを持っています。エンティティは、指定された種類のエンティティ全体にわたって一意的な文字列である、任意のキー名を持つことができます。エンティティの種類と名前を Key.from_path() および Model.get_by_key_name() メソッドに使用して、エンティティを取得できます。キーに関する詳しい情報は、キーとエンティティ グループをご覧ください。

Model.get_or_insert() のメソッドは、存在しない可能性のあるエンティティを必要に応じてデータストアに作成して取得するために使用されます。

keyname = "some_key"
s = Story.get_or_insert(keyname, title="The Three Little Pigs")

注: Model インスタンスは、初めて put() される（明示的に、または Model.get_or_insert() 経由で）までデータストアに対応するエンティティを持ちません。

Model クラスは、google.appengine.ext.db パッケージで提供されています。

コンストラクタ

Model クラスのコンストラクタは、次のように定義されます。

class Model(parent=None, key_name=None, **kw)

データ モデル定義用のスーパークラス。

引数:

parent

新しいエンティティの親であるエンティティの Model インスタンスまたは Key インスタンス。

key_name

新しいエンティティの名前。この名前は主キーの一部になります。None の場合は、システムによって生成された ID がキーとして使用されます。

key_name の値は、先頭を数字にしないでください。また、__*__ という形式にしないでください。ユーザーのアプリケーションは、ユーザーが送信したデータをデータストア エンティティ キー名（メール アドレスなど）として使用するには、たとえば「key:」のような既知の文字列を前に付ける方法で、その値を最初にサニタイズして、上記の要件を満たす必要があります。

key_name は Unicode 文字列として格納され、str 値は ASCII テキストに変換されます。

**kw

インスタンスのプロパティの初期値。キーワードの引数となります。各名前は Model クラスで定義された属性に対応します。

クラス メソッド

Model クラスには次のクラス メソッドがあります。

Model.get(keys)

指定された Key オブジェクトのモデル インスタンスを取得します。キーはモデルの種類のエンティティを表す必要があります。キーが正しい種類でない場合は、KindError が返されます。

このメソッドは種類のチェックが追加されている db.get() 関数に似ています。

引数:

keys

Key オブジェクト、または Key オブジェクトのリスト。Key オブジェクトの文字列版、または文字列のリストの場合もあります。

Model.get_by_id(ids, parent=None)

指定された数値 ID のモデル インスタンスを取得します。

引数:

ids

数値エンティティ ID、または数値エンティティ ID のリスト。

parent

リクエストされたエンティティの親エンティティ。Model インスタンスか Key インスタンス、または、リクエストされたエンティティが親を持たない場合は None（デフォルト）となります。1 回の呼び出しで複数のエンティティをリクエストする場合、エンティティは同じ親を持つものでなければなりません。

ids が 1 つの名前を表す文字列であれば、メソッドは名前に対してインスタンスを返すか、エンティティが存在しない場合、None を返します。ids がリストであれば、メソッドはモデル インスタンスのリストを返し、対応する Key にエンティティが存在しない場合、None 値を返します。

Model.get_by_key_name(key_names, parent=None)

指定されたキー名のモデル インスタンスを取得します。

引数:

key_names

キー名、またはキー名のリスト。

parent

リクエストされたエンティティの親エンティティ。Model インスタンスか Key インスタンス、または、リクエストされたエンティティが親を持たない場合は None（デフォルト）となります。1 回の呼び出しで複数のエンティティをリクエストする場合、エンティティは同じ親を持つものでなければなりません。

key_names が 1 つの名前を表す文字列であれば、メソッドは名前に対してインスタンスを返すか、エンティティが存在しない場合、None を返します。key_names がリストであれば、メソッドはモデル インスタンスのリストを返し、対応する Key にエンティティが存在しない場合、None 値を返します。

Model.get_or_insert(key_name, **kwds)

指定されたキー名で、モデルの種類のエンティティを 1 回のトランザクションで取得または作成します。トランザクションは、2 人のユーザーが指定された名前で同時にエンティティを取得または作成しようとすると、どちらのプロセスが作成したかには関係なく、両方のユーザーがエンティティを参照するモデル インスタンスを確実に得ることができるようにします。

引数:

key_name

エンティティのキーの名前。

**kwds

指定されたキー名を持つインスタンスが存在しない場合にモデル クラスに渡すキーワード引数。要求されたエンティティが親を持っている場合は、parent 引数が必要です。

メソッドは、リクエストされたエンティティを表すモデル クラスのインスタンスを、そのインスタンスが存在していたか、メソッドによって作成されたかには関係なく返します。すべてのデータストア オペレーションと同様に、このメソッドはトランザクションを完了できなかった場合、TransactionFailedError を返すことができます。

Model.all()

このモデルに対応する種類のすべてのエンティティを表す Query オブジェクトを返します。Query オブジェクトに対するメソッドは、クエリに対して、実行される前にフィルタと並び替え順序を適用することができます。詳しくは、クエリ をご覧ください。

Model.gql(query_string, *args, **kwds)

このモデルのインスタンスに対し、GQL クエリを実行します。

引数:

query_string

(このクラス メソッドを使用することで暗黙に示される) SELECT * FROM model に続く GQL クエリの一部。

*args

GqlQuery コンストラクタに似た、位置付きパラメータ バインディング。

**kw

GqlQuery コンストラクタに似た、キーワード パラメータ バインディング。

s = Story.gql("WHERE title = :1", "Little Red Riding Hood")

s = Story.gql("WHERE title = :title", title="Little Red Riding Hood")

戻り値は GqlQuery オブジェクトとなり、結果にアクセスするために使用できます。

Model.kind()

モデルの種類（通常は Model のサブクラス名）を返します。

Model.properties()

このモデル クラスに定義されたすべてのプロパティのディクショナリを返します。

インスタンス メソッド

モデル インスタンスには次のメソッドがあります。

key()

このモデル インスタンスに対し、データストアの Key を返します。

モデル インスタンスはデータストアに put() されるまでキーを持ちません。インスタンスがキーを持つ前に key() が呼び出されると、NotSavedError が返されます。

put()

モデル インスタンスをデータストアに格納します。モデル インスタンスが新しく作成され、まだ一度も格納されていなければ、このメソッドがデータストア内に新しいデータ エンティティを作成します。それ以外の場合、データ エンティティを最新のプロパティ値で更新します。

このメソッドは格納されたエンティティの Key を返します。

delete()

モデル インスタンスをデータストアから削除します。インスタンスが一度も put() されていなければ、何も削除されません。

is_saved()

モデル インスタンスが 1 回でもデータストアに put() されていれば、True が返されます。

このメソッドは、インスタンスが作成されてから少なくとも 1 回は格納されたかどうかをチェックするだけのものです。インスタンスのプロパティが最後に put() されてから更新されたかどうかはチェックしません。

dynamic_properties()

このモデル クラスに定義されたすべての動的プロパティ名のリストを返します。これが適用されるのは Expando クラスのインスタンスだけです。Expando 以外のモデル インスタンスに対しては、空のリストを返します。

parent()

このインスタンスの親エンティティ用のモデル インスタンスか、またはインスタンスが親を持たない場合は None を返します。

parent_key()

このインスタンスの親エンティティの Key か、またはインスタンスが親を持たない場合は None を返します。

to_xml()

モデル インスタンスの XML 表現を返します。

プロパティ値は Atom および GData 仕様に適合します。

無効なプロパティ名

データストアとその API はエンティティのプロパティ名およびモデル インスタンス属性にいくつかの制限を設定します。

データストアは 2 つのアンダースコアで始まり、終わる（__*__）すべてのプロパティ名を保存します。データストア エンティティはこのような名前のプロパティを持つことができません。

Python Model API は Model または Expando にある、アンダースコア（_）で始まるすべての属性を無視します。アプリケーションは、データとデータストアに保存されていないモデル オブジェクトを関連付けるためにこれらの属性を使用できます。

最後に、Python Model API はオブジェクト属性を使用してモデルのプロパティを定義し、デフォルトでは、データストア エンティティには属性に従った名前が付けられます。Model クラスには、その他を目的としたいくつかのプロパティとメソッドがあるため、これらの属性は Python API のプロパティとして使用することはできません。たとえば、Model は key 属性でアクセスされるプロパティを持つことはできません。

ただし、プロパティはプロパティ コンストラクタに name 引数を渡すことで、属性名とは異なったデータストア名を指定することができます。これによりデータストア エンティティは Model クラスの保存された属性と類似したプロパティ名を持つことができ、クラスで異なった属性名を使用することができます。

class MyModel(db.Model):
  obj_key = db.StringProperty(name="key")

Python API では、次の属性名が Model クラスによって保存されます。