型とプロパティ クラス

App Engine データストアは、データ エンティティのプロパティに対し値型の固定セットをサポートします。Property クラスは値の基本型から（または値の基本型に）変換する新しい型を定義できます。値型は Expando 動的プロパティと ListProperty 集約プロパティ モデルを使えば直接使用できます。

Property クラスとその値に直接対応するデータの基本型を次の表に示します。これらの値型はどれでも Expando 動的プロパティや ListProperty 集約型で使用できます。

データストアの値型

データストア エンティティ プロパティの値は、次の型のいずれかです。Property クラス（Model 定義で使用する）については、上の表をご覧ください。

Python の標準型と users.User を除き、このセクションで説明するクラスはすべて google.appengine.ext.db モジュールで提供されます。

str または unicode

500 バイト未満の短い文字列値。

str 値は、ascii コーデックでテキスト エンコードされることが想定され、保存前に unicode 値に変換されます。この値はデータストアによって unicode 値として返されます。他のコーデックを使った短い文字列には、unicode 値を使用します。

短い文字列はデータストアによってインデックス化され、フィルタや並び替え順序に使用できます。500 バイトより長い（インデックス化されていない）テキスト文字列には、Text インスタンスを使用します。500 バイトより長い、エンコードされていない（インデックス化もされていない）バイト文字列には、Blob インスタンスを使用します。

モデル プロパティ: StringProperty

bool

Boolean 値（True または False）。

モデル プロパティ: BooleanProperty

int または long

整数値。

Python int 値は Python long 値に変換して保存されます。int として保存された値は long として返されます。

モデル プロパティ: IntegerProperty

float

浮動小数点値。

モデル プロパティ: FloatProperty

datetime.datetime

日付と時刻。datetime モジュールのドキュメントをご覧ください。

datetime 値が tzinfo 属性を持つ場合は、UTC タイムゾーンに変換して保存されます。値はデータストアから UTC として None の tzinfo と一緒に戻ります。日付と時刻を特定のタイムゾーンの値にする必要があるアプリケーションの場合、値を更新するときは tzinfo を正しく設定し、値にアクセスするときは値をそのタイムゾーンに変換する必要があります。

一部のライブラリは TZ 環境変数を使って、日付と時刻の値に適用するタイムゾーンをコントロールします。App Engine はこの環境変数を "UTC" に設定します。なお、アプリケーションでこの変数を変更しても一部の datetime 関数の動作は変化しません。これは環境変数の変更が Python コードの外部から見えないためです。

値を特定のタイムゾーンに（また、特定のタイムゾーンから）変換するだけであれば、カスタム datetime.tzinfo を実装して、データストアから値を変換しても構いません。

class Pacific_tzinfo(datetime_module.tzinfo):
 """Implementation of the Pacific timezone."""
 def utcoffset(self, dt):
   return datetime_module.timedelta(hours=-8) + self.dst(dt)

 def _FirstSunday(self, dt):
   """First Sunday on or after dt."""
   return dt + datetime_module.timedelta(days=(6-dt.weekday()))

 def dst(self, dt):
   # 2 am on the second Sunday in March
   dst_start = self._FirstSunday(datetime_module.datetime(dt.year, 3, 8, 2))
   # 1 am on the first Sunday in November
   dst_end = self._FirstSunday(datetime_module.datetime(dt.year, 11, 1, 1))

   if dst_start <= dt.replace(tzinfo=None) < dst_end:
     return datetime_module.timedelta(hours=1)
   else:
     return datetime_module.timedelta(hours=0)

 def tzname(self, dt):
   if self.dst(dt) == datetime_module.timedelta(hours=0):
     return "PST"
   else:
     return "PDT"

pacific_time = utc_time.astimezone(Pacific_tzinfo())

datetime モジュールのドキュメント（datetime.tzinfo を含む）をご覧ください。サードパーティのモジュール pytz もご覧ください。ただし、pytz の配布モジュールは多数のファイルから成ります。

DateTimeProperty モデル プロパティ クラスには、モデル インスタンスが保存された日付と時刻を自動的に使用する機能などがあります。このような機能はこのモデルの特徴であり、生のデータストア値（たとえば Expando 動的プロパティ）には使用できません。

モデル プロパティ: DateTimeProperty、DateProperty、TimeProperty

list

値（サポートされるデータ型の値）のリスト。エンティティとモデル: リストをご覧ください。

list は、Expando 動的プロパティの値として使用するときは空のリストにできません。その理由はリスト値が保存される方法にあります。 リスト プロパティにアイテムがないと、データストアではリスト プロパティが表現されません。プロパティの空のリスト値を表現するには、静的プロパティと ListProperty クラスを使用します。

モデル プロパティ: ListProperty

db.Key

他のデータストア エンティティのキー。

m = Employee(name="Susan", key_name="susan5")
m.put()
e = Employee(name="Bob", manager=m.key())
e.put()

m_key = db.Key.from_path("Employee", "susan5")
e = Employee(name="Jennifer", manager=m_key)

モデル プロパティ: ReferenceProperty、SelfReferenceProperty

users.User

Google アカウントを持つユーザー。

データストアの User 値は、ユーザーが自分のメール アドレスを変更しても更新されません。これは今後のリリースで修正される可能性があります。それまでは、User 値の user_id() をユーザーの固定した一意の識別子として使用できます。

モデル プロパティ: UserProperty

class Blob(arg=None)

バイナリ データ（バイト文字列）。これは組み込み str 型のサブクラスです。

Blob プロパティはインデックス化されず、フィルタや並び替え順序に使用することはできません。

Blob は画像などのバイナリ データ用です。Blob は str 値を使用しますが、この値はバイト文字列として保存され、テキストとしてエンコードされません。大きなテキスト データには、Text インスタンスを使用します。

モデル プロパティ: BlobProperty

class MyModel(db.Model):
  blob = db.BlobProperty()

m = MyModel()
m.blob = db.Blob(open("image.png").read())

XML では、Blob はバイナリ データを含んでいるかどうかにかかわらず、Base-64 でエンコードされています。

class ByteString(arg)

短い Blob 値（「バイト文字列」）で、長さは 500 バイト未満です。ByteString は str のサブクラスで、エンコードされていない str 値をコンストラクタへの引数として使用します。

ByteString はデータストアによってインデックス付けされ、フィルタや並び替え順序に使用できます。500 バイトより長い（インデックス付けされていない）テキスト文字列には、Blob インスタンスを使用します。エンコードされたテキスト データには、str（短い、インデックス付き）または Text（長い、インデックスなし）を使用します。

モデル プロパティ: ByteStringProperty

class Text(arg=None, encoding=None)

長い文字列。これは組み込み unicode 型のサブクラスです。

arg は unicode または str 値です。arg は str であれば、encoding で指定されたエンコードを使って解析され、エンコードが指定されていなければ ascii です。encoding の設定可能な値については、標準エンコードのリストをご覧ください。

値がシンプルな str または unicode のエンティティ プロパティとは異なり、Text プロパティは 500 バイトより長くすることができます。ただし、Text プロパティはインデックス化されず、フィルタや並び替え順序に使用することはできません。

モデル プロパティ: TextProperty

class MyModel(db.Model):
  text = db.TextProperty()

m = MyModel()
m.text = db.Text(u"kittens")

m.text = db.Text("kittens", encoding="latin-1")

class Category(tag)

カテゴリまたは「タグ」。これは組み込み unicode 型のサブクラスです。

モデル プロパティ: CategoryProperty

class MyModel(db.Model):
  category = db.CategoryProperty()

m = MyModel()
m.category = db.Category("kittens")

XML では、これは Atom category 要素です。Atom 仕様をご覧ください。

class Email(email)

メール アドレス。これは組み込み unicode 型のサブクラスです。

プロパティ クラスと値クラスは、いずれもメール アドレスの検証は行わず、その値を保存するだけです。

モデル プロパティ: EmailProperty

class MyModel(db.Model):
  email_address = db.EmailProperty()

m = MyModel()
m.email_address = db.Email("larry@example.com")

XML では、これは gd:email 要素です。GData API リファレンスをご覧ください。

class GeoPt(lat, lon=None)

浮動小数点の緯度と経度の座標で表される地点。

モデル プロパティ: GeoPtProperty

XML では、これは georss:point 要素です。georss.org をご覧ください。

class IM(protocol, address=None)

インスタント メッセージング ハンドル。

protocol はインスタント メッセージング サービスの標準化された URL です。設定可能な値をいくつか次に示します。

Protocol	説明
sip	SIP/SIMPLE
xmpp	XMPP/Jabber
http://aim.com/	AIM
http://icq.com/	ICQ
http://talk.google.com/	Google トーク
http://messenger.msn.com/	MSN メッセンジャー
http://messenger.yahoo.com/	Yahoo メッセンジャー
http://sametime.com/	Lotus Sametime
http://gadu-gadu.pl/	Gadu-Gadu
unknown	不明または不特定

address はハンドルのアドレスです。

モデル プロパティ: IMProperty

class MyModel(db.Model):
  im = db.IMProperty()

m = MyModel()
m.im = db.IM("http://example.com/", "Larry97")

XML では、これは gd:im 要素です。GData API リファレンスをご覧ください。

class Link(link)

完全修飾 URL。これは組み込み unicode 型のサブクラスです。

モデル プロパティ: LinkProperty

class MyModel(db.Model):
  link = db.LinkProperty()

m = MyModel()
m.link = db.Link("http://www.google.com/")

XML では、これは Atom link 要素です。Atom 仕様をご覧ください。

class PhoneNumber(phone)

人が読み取れる電話番号。これは組み込み unicode 型のサブクラスです。

モデル プロパティ: PhoneNumberProperty

class MyModel(db.Model):
  phone = db.PhoneNumberProperty()

m = MyModel()
m.phone = db.PhoneNumber("1 (206) 555-1212")

XML では、これは gd.phoneNumber 要素です。GData API リファレンスをご覧ください。

class PostalAddress(address)

住所。これは組み込み unicode 型のサブクラスです。

モデル プロパティ: PostalAddressProperty

class MyModel(db.Model):
  address = db.PostalAddressProperty()

m = MyModel()
m.address = db.PostalAddress("1600 Ampitheater Pkwy., Mountain View, CA")

XML では、これは gd:postalAddress 要素です。GData API リファレンスをご覧ください。

class Rating(rating)

コンテンツについてユーザーが入力する評価（0 ～ 100 の整数）。これは組み込み long 型のサブクラスです。このクラスは値が 0～100 の整数であることを検証し、値が無効であれば BadValueError を発行します。

モデル プロパティ: RatingProperty

class MyModel(db.Model):
  rating = db.RatingProperty()

m = MyModel()
m.rating = db.Rating(97)

XML では、これは gd:rating 要素です。GData API リファレンスをご覧ください。

Property クラス

google.appengine.ext.db が提供するモデル プロパティ クラスはすべて Property 基本クラスのサブクラスであり、基本コンストラクタのすべての引数をサポートします。これらの引数については、基本クラスのドキュメントをご覧ください。

google.appengine.ext.db パッケージは次のモデル プロパティ クラスを提供します。

class BlobProperty(...)

バイナリ データ プロパティ。

Blob データはバイト文字列です。エンコードが必要なテキスト データには、TextProperty を使用します。

値型: Blob

class BooleanProperty(...)

Boolean プロパティ。

値型: bool

class ByteStringProperty(verbose_name=None, ...)

短い Blob プロパティ（「バイト文字列」）。500 バイト以下の ByteString 値を使用します。

ByteStringProperty プロパティ値はインデックス付けされ、フィルタや並び替え順序に使用することができます。

StringProperty と同様ですが、値はエンコードされていません。バイトはそのまま保存されます。

値型: ByteString

class CategoryProperty(...)

カテゴリまたは「タグ」（記述的な語または語句）。

値型: Category

class DateProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

データ プロパティ（時刻なし）。詳しくは DateTimeProperty をご覧ください。

値型: datetime.date。これは datetime.datetime に内部変換されます。

class DateTimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

日付と時刻プロパティ。

auto_now が True の場合、プロパティ値は、モデル インスタンスがデータストアに保存されたときの現在時刻に設定され、プロパティの前の値を上書きします。これはモデル インスタンスが「最後に変更された」日付と時刻を追跡する場合に便利です。

auto_now_add が True の場合、プロパティ値は、プロパティに値がすでに割り当てられていない限り、最初にモデル インスタンスがデータストアに保存されたときの現在時刻に設定されます。これはモデル インスタンスが「作成された」日付と時刻を保存する場合に便利です。

日付と時間の値が保存されるときも返されるときも UTC タイムゾーンが使用されます。タイムゾーンを管理する方法については、datetime.datetime をご覧ください。

値型: datetime.datetime

class EmailProperty(...)

メール アドレス。

プロパティ クラスと値クラスは、いずれもメール アドレスの検証は行わず、その値を保存するだけです。

値型: Email

class FloatProperty(...)

浮動小数点数プロパティ。

値型: float

class GeoPtProperty(...)

浮動小数点の緯度と経度の座標で表される地点。

値型: GeoPt

class IMProperty(...)

インスタント メッセージング ハンドル。

値型: IM

class IntegerProperty(...)

整数プロパティ。

Python int 値は Python long 値に変換して保存されます。int として保存された値は long として返されます。

値型: int または long

class LinkProperty(...)

完全修飾 URL。

値型: Link

class ListProperty(item_type, verbose_name=None, default=None, ...)

item_type として指定された型の値リスト。

クエリでは、リスト プロパティと値を比較してリスト メンバーを照合します。たとえば、list_property = value は値がリスト内に存在するかどうかを調べ、list_property < value はリストのメンバーが指定された値より小さいかどうか調べます。

クエリで 2 つのリスト値を比較することはできません。各要素がメンバーであることを個別に調べる以外に、2 つのリストが同じかどうか確かめる方法はありません。

item_type はリスト内のアイテムの型（Python 型かクラス）です。リスト値のすべてのアイテムは必ず指定された型にします。item_type はデータストアの値型にする必要があり、list にはできません。上記の データストアの値型をご覧ください。

静的プロパティ ListProperty の値は None にはできません。ただし、空のリストにすることはできます。

ヒント: ListProperty 集約型は Property クラスを使用しないので、値の自動検証のような Property クラスの機能はリスト値のメンバーに自動的に適用されません。Property クラスを使ってメンバー値を検証するには、Property クラスをインスタンス化し、その値を引数にして validate() メソッドを呼び出します。

default はリスト プロパティのデフォルト値です。None の場合、デフォルトは空のリストです。リスト プロパティは、カスタム validator を定義して空のリストを無効にすることができます。

ListProperty とリスト値について詳しくは、エンティティとモジュールをご覧ください。

値型: ゼロ以上の値（設定された値型）の Python list

class PhoneNumberProperty(...)

人が読み取れる電話番号。

値型: PhoneNumber

class PostalAddressProperty(...)

住所。

値型: PostalAddress

class RatingProperty()

コンテンツについてユーザーが入力する評価（0 ～ 100 の整数）。

値型: Rating

class ReferenceProperty(reference_class=None, verbose_name=None, collection_name=None, ...)

他のモデル インスタンスへの参照。たとえば参照は、プロパティを持つモデルとプロパティによって参照されるモデルの関係を多対 1 として示します。

reference_class は、参照されているモデル インスタンスのモデル クラスです。指定すれば、クラスのモデル インスタンスだけをこのプロパティに割り当てることができます。None の場合、モデル インスタンスをこのプロパティの値にすることができます。

collection_name は、参照されたモデル クラスに与えるプロパティの名前です。参照されたモデル クラスの値は、エンティティを参照するすべてのエンティティに対し Query となります。collection_name が設定されていない場合、modelname_set（小文字のモデル名に「_set」を付けたもの）が使用されます。

注: 同じモデル クラスを参照している同じモデル内に複数のプロパティがある場合、collection_name を設定する必要があります。設定しないと、デフォルト名が作成されたときに DuplicatePropertyError が発行されます。

ReferenceProperty は、モデル インスタンスを自動的にプロパティ値として参照および逆参照します。 モデル インスタンスは ReferenceProperty に直接割り当てることができます。その場合は、そのキーが使用されます。ReferenceProperty 値はモデル インスタンスと同じように使用することができます。その場合は、データストア エンティティがフェッチされ、モデル インスタンスがこの方法で最初の使用時に作成されます。未使用の参照プロパティは不要なデータのクエリを行いません。

class Author(db.Model):
  name = db.StringProperty()

class Story(db.Model):
  author = db.ReferenceProperty(Author)

story = db.get(story_key)
author_name = story.author.name

Key 値と同様、参照プロパティ値は、存在しないデータ エンティティを参照することができます。参照されたエンティティがデータストアから削除されても、そのエンティティへの参照は更新されません。アプリケーションは db.get() を使って明示的に ReferenceProperty の値（Key）を取得し、参照されたエンティティの有無を確認できます。

エンティティの削除では、ReferenceProperty によって参照されたエンティティは削除されません。

参照プロパティの概要もご覧ください。

値型: db.Key（上記を参照）

class SelfReferenceProperty(verbose_name=None, collection_name=None, ...)

同じクラスの他のモデル インスタンスへの参照。ReferenceProperty をご覧ください。

値型: db.Key（上記を参照）

class StringListProperty(verbose_name=None, default=None, ...)

Python str または unicode（basestring）値の ListProperty と同様。ListProperty をご覧ください。

値型: str または unicode 値の Python list

class StringProperty(verbose_name=None, multiline=False, ...)

短い文字列プロパティ。 500 バイト以下の Python str または unicode（basestring）値を使用します。

StringProperty プロパティ値はインデックス化され、フィルタや並び替え順序に使用することができます。

multiline が False の場合、値に改行文字を含めることはできません。djangoforms ライブラリはこれを使って、データ モデル内のテキスト フィールドとテキストエリア フィールドの違いを強化します。他のライブラリもこれを同じ目的のために使用することができます。

値型: str または unicode

class TextProperty()

長い文字列。

StringProperty と異なり、TextProperty 値は 500 バイトより長くすることができます。ただし、TextProperty 値はインデックス化されず、フィルタや並び替え順序に使用することはできません。

TextProperty 値は、テキスト エンコードを使ってテキストを保存します。バイナリ データの場合は、BlobProperty を使用します。

値型: Text

class TimeProperty(verbose_name=None, auto_now=False, auto_now_add=False, ...)

時刻プロパティ（日付なし）。Python の標準ライブラリ datetime.time 値を使用します。詳しくは DateTimeProperty をご覧ください。

値型: datetime.time。これは datetime.datetime に内部変換されます。

class UserProperty(verbose_name=None, auto_current_user=False, auto_current_user_add=False, ...)

Google アカウントを持つユーザー。

auto_current_user が True の場合、プロパティ値は、モデル インスタンスがデータストアに保存された時点でログイン中のユーザーに設定され、プロパティの前の値を上書きします。これは、どのユーザーがモデル インスタンスを変更したか追跡する際に便利です。

auto_current_user_add が True の場合、プロパティ値は、プロパティに値がすでに割り当てられていない限り、最初にモデル インスタンスがデータストアに保存された時点でログインしているユーザーに設定されます。これは、どのユーザーがモデル インスタンスを生成したか追跡する際に便利で、このユーザーは後で変更を行うユーザーと同じでないことがあります。

UserProperty はデフォルト値を受け付けません。デフォルト値は、モデル クラスが最初にインポートされたときに設定され、インポートの際にキャッシュを行っているのは現在ログインしているユーザーではないことがあります。

値型: users.User（上記を参照）