型とプロパティ クラス

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

App Engine Datastore は、データ エンティティのプロパティに関して固定された一連の値の型をサポートしています。 Property クラスでは、基本となる値の型との間で変換される新しい型を定義できます。これらの値の型は、 Expando 動的プロパティと ListProperty 集約プロパティ モデルで直接使用できます。

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

Property クラス 値の型 並べ替え順
IntegerProperty int
long (64 ビット)
数値
FloatProperty float 数値
BooleanProperty bool False < True
StringProperty str
unicode
Unicode(str は ASCII として処理されます)
TextProperty db.Text なし
ByteStringProperty ByteString
バイト順
BlobProperty db.Blob なし
DateProperty
TimeProperty
DateTimeProperty
datetime.date
datetime.time
datetime.datetime
時系列
GeoPtProperty db.GeoPt 緯度、
経度の順
PostalAddressProperty db.PostalAddress Unicode
PhoneNumberProperty db.PhoneNumber Unicode
EmailProperty db.Email Unicode
UserProperty users.User メールアドレス
Unicode 順UserProperty クラスの説明に含まれる注意事項のとおり、UserProperty の使用は避けてください。
IMProperty db.IM Unicode
LinkProperty db.Link Unicode
CategoryProperty db.Category Unicode
RatingProperty db.Rating 数値
ReferenceProperty
SelfReferenceProperty
db.Key パス要素順
(種類、識別子、
種類、識別子...)
blobstore.BlobReferenceProperty blobstore.BlobInfo バイト順
ListProperty
StringListProperty
サポートされている型の list 昇順の場合は、小さい要素から順に
降順の場合は、大きい要素から順に

データストアの値の型

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

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

str または unicode

短い文字列(1,500 バイト以下)。

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

短い文字列は、データストアによってインデックスに登録され、フィルタや並べ替え順に使用できます。長さが 1,500 バイトを超え、インデックスに登録されていないテキスト文字列の場合は、Text インスタンスを使用します。1,500 バイトを超え(インデックスに登録されず)、エンコードされていないバイト文字列には Blob インスタンスを使用します。エンコードされていない 1,500 バイトまでのテキスト以外のバイト文字列には、ByteString インスタンスを使用します。これらはインデックスに登録する必要があります。

モデル プロパティ: StringProperty

bool

ブール値(True または False)。

モデル プロパティ: BooleanProperty

int または long

整数値(最大 64 ビット)。

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

64 ビットを超える long が割り当てられた場合は、下位の 64 ビットのみが保存されます。

モデル プロパティ: IntegerProperty

float

浮動小数点数。

モデル プロパティ: FloatProperty

datetime.datetime

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

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

一部のライブラリでは、TZ 環境変数を使用して日付値に適用されるタイムゾーンを制御します。App Engine はこの環境変数を "UTC" に設定します。アプリケーションでこの変数を変更しても、Python コードの外部では環境変数の変更が認識されないため、一部の datetime 関数の動作は変更されません。

値を特定のタイムゾーンとの間でのみ変換する場合は、カスタムの datetime.tzinfo を実装してデータストアから取得した値を変換できます。

import datetime
import time

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

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

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

        if dst_start <= dt.replace(tzinfo=None) < dst_end:
            return datetime.timedelta(hours=1)
        else:
            return datetime.timedelta(hours=0)
    def tzname(self, dt):
        if self.dst(dt) == datetime.timedelta(hours=0):
            return "PST"
        else:
            return "PDT"

pacific_time = datetime.datetime.fromtimestamp(time.mktime(utc_time.timetuple()), Pacific_tzinfo())

詳しくは datetime モジュールのドキュメントdatetime.tzinfo を含む)をご覧ください。サードパーティのモジュール pytz もご覧ください。ただし、pytz のディストリビューションには多くのファイルが含まれていることにご注意ください。

DateTimeProperty モデル プロパティ クラスには、モデル インスタンスが保存された日時を自動的に使用する機能などが備えられています。これらはモデルの機能であり、生のデータストア値(Expando 動的プロパティなど)では使用できません。

モデル プロパティ: DateTimePropertyDatePropertyTimeProperty

list

サポートされているデータ型の値で構成される値のリスト。

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

モデル プロパティ: ListProperty

db.Key

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

注: キー文字列は 1,500 バイト以下に制限されています。

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)

モデル プロパティ: ReferencePropertySelfReferenceProperty

blobstore.BlobKey

値をアップロードしたときに Blobstore によって生成される Blobstore 値のキー。

モデル プロパティ: blobstore.BlobReferenceProperty

users.User

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

ユーザーが自身のメールアドレスを変更しても、データストア内の user.User 値は更新されません。このため、users.User 値を UserProperty 値として保存しないことを強くおすすめします。これにはメールアドレスとともに一意の ID が含まれているためです。ユーザーがメールアドレスを変更すると、古い保存済みの user.User と新しい user.User の値を比較した場合に一致しなくなります。代わりに、user.User 値の user_id() をユーザーの不変の一意の ID として使用します。

モデル プロパティ: UserProperty

class Blob(arg=None)

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

Blob プロパティはインデックスに登録されず、フィルタや並べ替え順には使用できません。

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

モデル プロパティ: BlobProperty

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

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

XML では、Blob はバイナリデータを含むかどうかに関係なく Base-64 でエンコードされます。

class ByteString(arg)

1,500 バイト以下の短い Blob 値(「バイト文字列」)。ByteString は str のサブクラスで、そのコンストラクタへの引数としてエンコードされていない str 値を取ります。

ByteString はデータストアによってインデックスに登録され、フィルタや並べ替え順に使用できます。長さが 1,500 バイトを超える(インデックスに登録されない)バイト文字列には、Blob インスタンスを使用します。エンコードされているテキストデータには、str(インデックスに登録される短い文字列)または Text(インデックスに登録されない長い文字列)を使用してください。

モデル プロパティ: ByteStringProperty

class Text(arg=None, encoding=None)

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

arg: unicode または str 値。argstr の場合は、encoding で指定されたエンコードを使用して解析されます(エンコードが指定されていない場合は ascii が使用されます)。encoding に指定できる値については、標準のエンコードのリストをご覧ください。

値が単純な str または unicode であるエンティティ プロパティとは異なり、Text プロパティの長さは 1,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 要素です。

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 要素です。

class GeoPt(lat, lon=None)

浮動小数点型の緯度と経度の座標で表される地理的位置。

モデル プロパティ: GeoPtProperty

XML では、これは georss:point 要素です。

class IM(protocol, address=None)

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

protocol は、インスタント メッセージ サービスの正規 URL です。次のような値を指定できます。

プロトコル説明
sipSIP/SIMPLE
xmppXMPP/Jabber
http://aim.com/AIM
http://icq.com/ICQ
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 要素です。

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

モデル プロパティ: LinkProperty

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

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

XML では、これは Atom の Link 要素です。

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 要素です。

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 要素です。

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 要素です。

プロパティ クラス

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

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

class BlobProperty(...)

解釈されていないバイナリデータのコレクション。

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

値の型: Blob

class BooleanProperty(...)

ブール値(True または False)。

値の型: bool

class ByteStringProperty(verbose_name=None, ...)

1,500 バイト以下の短い Blob 値(「バイト文字列」)。

ByteStringProperty 値はインデックスに登録され、フィルタや並べ替え順序で使用できます。

StringProperty とほぼ同じですが、値がエンコードされない点が異なります。バイトはそのまま保存されます。

ByteStringProperty が必須の場合、その値を空の文字列にすることはできません。

値の型: 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_nowTrue の場合は、モデル インスタンスがデータストアに保存されるたびに、このプロパティの前の値が上書きされ、プロパティ値が現在の時刻に設定されます。これは、モデル インスタンスの「最終更新」日時を追跡するのに便利です。

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

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

値の型: datetime.datetime

class EmailProperty(...)

メールアドレス。

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

値の型: Email

class FloatProperty(...)

浮動小数点数。

値の型: float

class GeoPtProperty(...)

浮動小数点型の緯度と経度の座標で表される地理的位置。

値の型: GeoPt

class IMProperty(...)

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

値の型: IM

class IntegerProperty(...)

整数値(最大 64 ビット)。

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

64 ビットを超える long が割り当てられた場合は、下位の 64 ビットのみが保存されます。

値の型: 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 にすることはできません。ただし、空のリストにすることはできます。Nonedefault 引数に指定された場合(または default 引数が指定されなかった場合)、このプロパティのデフォルト値は空のリストです。

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

default は、リスト プロパティのデフォルト値です。None の場合、デフォルトは空のリストです。リスト プロパティでカスタム検証ツールを定義することにより、空のリストを禁止できます。

リスト プロパティとリスト値の詳細については、データ モデリングのページをご覧ください。

値の型: 指定された型の値を持つ 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 値は、モデル インスタンスと同じように使用できます。この値を最初にこの方法で使用するときに、データストア エンティティがフェッチされ、モデル インスタンスが作成されます。手つかずの参照プロパティによって不要なデータのクエリが実行されることはありません。

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

author = db.get(author_key)
stories_by_author = author.story_set.get()

Key 値と同様に、参照プロパティの値が、存在しないデータ エンティティを参照することがあります。参照されているエンティティがデータストアから削除された場合、そのエンティティへの参照は更新されません。存在しないエンティティにアクセスすると、 ReferencePropertyResolveError が発生します。

エンティティを削除しても、参照プロパティによって参照されているエンティティは削除されません。

値の型: db.Key

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

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

値の型: db.Key

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

Python str または unicodebasestring)の値のリスト プロパティと同様です。

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

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

短い文字列。1,500 バイト以下の Python str または unicodebasestring)の値を取ります。

StringProperty 値はインデックスに登録され、フィルタや並べ替え順序で使用できます。

multilineFalse の場合は、値にラインフィード文字を含めることができません。djangoforms ライブラリでは、これを使用してテキスト フィールドとテキスト領域フィールドの違いをデータモデルに適用します。他のライブラリでも同様の目的でこれを使用できます。

文字列プロパティが必須の場合、その値を空の文字列にすることはできません。

値の型: str または unicode

class TextProperty()

長い文字列。

StringProperty とは異なり、TextProperty 値の長さは 1,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, ...)

重要: メールアドレスとユーザーの一意の ID が含まれているため、UserProperty を保存しないことを強くおすすめします。ユーザーがメールアドレスを変更すると、そのユーザーの古いメールアドレス(User に格納されている)と新しい User の値を比較したときに一致しません。

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

auto_current_userTrue の場合は、モデル インスタンスがデータストアに保存されるたびに、このプロパティの前の値が上書きされ、プロパティ値が現在ログインしているユーザーに設定されます。これは、モデル インスタンスを変更したユーザーを追跡するのに便利です。

auto_current_user_addTrue の場合は、このプロパティにすでに値が割り当てられている場合を除き、モデル インスタンスが最初にデータストアに保存されるときに、プロパティ値が現在ログインしているユーザーに設定されます。これは、モデル インスタンスを作成したユーザー(後でモデル インスタンスを変更したユーザーとは異なる可能性がある)を追跡するのに便利です。

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

値の型: users.User