型とプロパティ クラス

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

App Engine データストアは、データ エンティティのプロパティに関して固定された一連の値の型をサポートしています。 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() をユーザーの不変の一意識別子として使用してください。

モデル プロパティ: 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 に指定できる値については、標準のエンコードのリストをご覧ください。

値が単純な strunicode であるエンティティ プロパティとは異なり、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 の場合、デフォルトは空のリストになります。リスト プロパティでカスタム検証ツールを定義することにより、空のリストを禁止できます。

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

値の型: 指定された型の値の 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 または unicode (basestring) の値のリスト プロパティと同様です。

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

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

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

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, ...)

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

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

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

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

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

値の型: users.User

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

Python の App Engine スタンダード環境