Note: Python 2.7 has reached end of support on January 31, 2024. Your existing Python 2.7 applications will continue to run and receive traffic. However, App Engine might block re-deployment of applications that use runtimes after their end of support date. We recommend that you migrate to the latest supported version of Python.

google.appengine.api.datastore_types module

Summary

Higher-level, semantic data types for the datastore. These types are expected to be set as attributes of Entities. See “Supported Data Types” in the API Guide.

Most of these types are based on XML elements from Atom and GData elements from the atom and gd namespaces. For more information, see:

http://www.atomenabled.org/developers/syndication/ https://developers.google.com/gdata/docs/1.0/elements

The namespace schemas are:

http://www.w3.org/2005/Atom http://schemas.google.com/g/2005

class google.appengine.api.datastore_types.Blob(*args, **kwargs)source

Bases: google.appengine.api.datastore_types._BaseByteType

A blob type, appropriate for storing binary data of any length.

This behaves identically to the Python str type, except for the constructor, which only accepts str arguments.

meaning_uri

class google.appengine.api.datastore_types.BlobKey(blob_key)source

Bases: object

Key used to identify a blob in Blobstore.

This object wraps a string that gets used internally by the Blobstore API to identify application blobs. The BlobKey corresponds to the entity name of the underlying BlobReference entity.

This class is exposed in the API in both google.appengine.ext.db and google.appengine.ext.blobstore.

ToXml()source

class google.appengine.api.datastore_types.ByteStringsource

Bases: google.appengine.api.datastore_types._BaseByteType

A byte-string type, appropriate for storing short amounts of indexed data.

This behaves identically to Blob, except it’s used only for short, indexed byte strings.

class google.appengine.api.datastore_types.Category(tag)source

Bases: unicode

A tag, ie a descriptive word or phrase. Entities may be tagged by users, and later returned by a queries for that tag. Tags can also be used for ranking results (frequency), photo captions, clustering, activity, etc.

Here’s a more in-depth description: http://www.zeldman.com/daily/0405d.shtml

This is the Atom “category” element. In XML output, the tag is provided as the term attribute. See: http://www.atomenabled.org/developers/syndication/#category

Raises BadValueError if tag is not a string or subtype.

TERM = 'user-tag'

ToXml()source

google.appengine.api.datastore_types.DatetimeToTimestamp(value)source

Converts a datetime.datetime to microseconds since the epoch, as a float. :param value: datetime.datetime

Returns: value as a long

google.appengine.api.datastore_types.DecodeAppIdNamespace(app_namespace_str)source

Decodes app_namespace_str into an (app_id, namespace) pair.

This method is the reverse of EncodeAppIdNamespace and is needed for datastore_file_stub.

Parameters

app_namespace_str – An encoded app_id, namespace pair created by EncodeAppIdNamespace

Returns

(app_id, namespace) pair encoded in app_namespace_str

class google.appengine.api.datastore_types.Email(email)source

Bases: unicode

An RFC2822 email address. Makes no attempt at validation; apart from checking MX records, email address validation is a rathole.

This is the gd:email element. In XML output, the email address is provided as the address attribute. See: https://developers.google.com/gdata/docs/1.0/elements#gdEmail

Raises BadValueError if email is not a valid email address.

ToXml()source

class google.appengine.api.datastore_types.EmbeddedEntitysource

Bases: google.appengine.api.datastore_types._BaseByteType

A proto encoded EntityProto.

This behaves identically to Blob, except for the constructor, which accepts a str or EntityProto argument.

Can be decoded using datastore.Entity.FromProto(), db.model_from_protobuf() or ndb.LocalStructuredProperty.

google.appengine.api.datastore_types.EncodeAppIdNamespace(app_id, namespace)source

Concatenates app id and namespace into a single string.

This method is needed for xml and datastore_file_stub.

Parameters

app_id – The application id to encode
namespace – The namespace to encode

Returns

The string encoding for the app_id, namespace pair.

google.appengine.api.datastore_types.FromPropertyPb(pb)source

Converts a property PB to a python value.

Parameters

pb – entity_pb.Property

Returns

# return type is determined by the type of the argument string, int, bool, double, users.User, or one of the atom or gd types

google.appengine.api.datastore_types.FromPropertyTypeName(type_name)source

Returns the python type given a type name.

Parameters

type_name – A string representation of a datastore type name.

Returns

A python type.

google.appengine.api.datastore_types.FromReferenceProperty(value)source

Converts a reference PropertyValue to a Key.

Parameters

value – entity_pb.PropertyValue

Returns

Key

Raises

BadValueError if the value is not a PropertyValue.

class google.appengine.api.datastore_types.GeoPt(lat, lon=None)source

Bases: object

A geographical point, specified by floating-point latitude and longitude coordinates. Often used to integrate with mapping sites like Google Maps. May also be used as ICBM coordinates.

This is the georss:point element. In XML output, the coordinates are provided as the lat and lon attributes. See: http://georss.org/

Serializes to ‘<lat>,<lon>’. Raises BadValueError if it’s passed an invalid serialized string, or if lat and lon are not valid floating points in the ranges [-90, 90] and [-180, 180], respectively.

ToXml()source

lat = None

lon = None

google.appengine.api.datastore_types.GetPropertyValueTag(value_pb)source: Returns the tag constant associated with the given entity_pb.PropertyValue.

class google.appengine.api.datastore_types.IM(protocol, address=None)source

Bases: object

An instant messaging handle. Includes both an address and its protocol. The protocol value is either a standard IM scheme or a URL identifying the IM network for the protocol. Possible values include:

Value Description sip SIP/SIMPLE unknown Unknown or unspecified xmpp XMPP/Jabber http://aim.com/ AIM http://icq.com/ ICQ http://talk.google.com/ Google Talk http://messenger.msn.com/ MSN Messenger http://messenger.yahoo.com/ Yahoo Messenger http://sametime.com/ Lotus Sametime http://gadu-gadu.pl/ Gadu-Gadu

This is the gd:im element. In XML output, the address and protocol are provided as the address and protocol attributes, respectively. See: https://developers.google.com/gdata/docs/1.0/elements#gdIm

Serializes to ‘<protocol> <address>’. Raises BadValueError if tag is not a standard IM scheme or a URL.

PROTOCOLS = ['sip', 'unknown', 'xmpp']

ToXml()source

address = None

protocol = None

class google.appengine.api.datastore_types.Key(encoded=None)source

Bases: object

The primary key for a datastore entity.

A datastore GUID. A Key instance uniquely identifies an entity across all apps, and includes all information necessary to fetch the entity from the datastore with Get().

Key implements __hash__, and key instances are immutable, so Keys may be used in sets and as dictionary keys.

ToTagUri()source

Returns a tag: URI for this entity for use in XML output.

Foreign keys for entities may be represented in XML output as tag URIs. RFC 4151 describes the tag URI scheme. From http://taguri.org/:

The tag algorithm lets people mint - create - identifiers that no one else using the same algorithm could ever mint. It is simple enough to do in your head, and the resulting identifiers can be easy to read, write, and remember. The identifiers conform to the URI (URL) Syntax.

Tag URIs for entities use the app’s auth domain and the date that the URI: is generated. The namespace-specific part is <kind>[<key>].

For example, here is the tag URI for a Kitten with the key “Fluffy” in the catsinsinks app:

tag:catsinsinks.googleapps.com,2006-08-29:Kitten[Fluffy]

Raises a BadKeyError if this entity’s key is incomplete.

ToXml()source

Returns a tag: URI for this entity for use in XML output.

Foreign keys for entities may be represented in XML output as tag URIs. RFC 4151 describes the tag URI scheme. From http://taguri.org/:

Tag URIs for entities use the app’s auth domain and the date that the URI: is generated. The namespace-specific part is <kind>[<key>].

For example, here is the tag URI for a Kitten with the key “Fluffy” in the catsinsinks app:

tag:catsinsinks.googleapps.com,2006-08-29:Kitten[Fluffy]

Raises a BadKeyError if this entity’s key is incomplete.

app()source: Returns this entity’s app id, a string.

entity_group()source

Returns this key’s entity group as a Key.

Note that the returned Key will be incomplete if this Key is for a root entity and it is incomplete.

static from_path(*args, **kwds)source

Static method to construct a Key out of a “path” (kind, id or name, …).

This is useful when an application wants to use just the id or name portion of a key in e.g. a URL, where the rest of the URL provides enough context to fill in the rest, i.e. the app id (always implicit), the entity kind, and possibly an ancestor key. Since ids and names are usually small, they’re more attractive for use in end-user-visible URLs than the full string representation of a key.

Parameters

kind – the entity kind (a str or unicode instance)
id_or_name – the id (an int or long) or name (a str or unicode instance)
parent – optional parent Key; default None.
namespace – optional namespace to use otherwise namespace_manager’s default namespace is used.

Returns

A new Key instance whose .kind() and .id() or .name() methods return the last kind and id or name positional arguments passed.

Raises

BadArgumentError for invalid arguments.
BadKeyError if the parent key is incomplete.

has_id_or_name()source: Returns True if this entity has an id or name, False otherwise.

id()source: Returns this entity’s id, or None if it doesn’t have one.

id_or_name()source: Returns this entity’s id or name, whichever it has, or None.

kind()source: Returns this entity’s kind, as a string.

name()source: Returns this entity’s name, or None if it doesn’t have one.

namespace()source: Returns this entity’s namespace, a string.

parent()source: Returns this entity’s parent, as a Key. If this entity has no parent, returns None.

to_path(_default_id=None, _decode=True, _fail=True)source

Construct the “path” of this key as a list.

Returns

A list [kind_1, id_or_name_1, …, kind_n, id_or_name_n] of the key path.

Raises

datastore_errors.BadKeyError if this key does not have a valid path.

class google.appengine.api.datastore_types.Link(link)source

Bases: unicode

A fully qualified URL. Usually http: scheme, but may also be file:, ftp:, news:, among others.

If you have email (mailto:) or instant messaging (aim:, xmpp:) links, consider using the Email or IM classes instead.

This is the Atom “link” element. In XML output, the link is provided as the href attribute. See: http://www.atomenabled.org/developers/syndication/#link

Raises BadValueError if link is not a fully qualified, well-formed URL.

ToXml()source

google.appengine.api.datastore_types.PackBlob(name, value, pbvalue)source

Packs a Blob property into a entity_pb.PropertyValue.

Parameters

name – The name of the property as a string.
value – A Blob instance.
pbvalue – The entity_pb.PropertyValue to pack this value into.

google.appengine.api.datastore_types.PackBool(name, value, pbvalue)source

Packs a boolean property into a entity_pb.PropertyValue.

Parameters

name – The name of the property as a string.
value – A boolean instance.
pbvalue – The entity_pb.PropertyValue to pack this value into.

google.appengine.api.datastore_types.PackDatetime(name, value, pbvalue)source

Packs a datetime-typed property into a entity_pb.PropertyValue.

Parameters

name – The name of the property as a string.
value – A datetime.datetime instance.
pbvalue – The entity_pb.PropertyValue to pack this value into.

google.appengine.api.datastore_types.PackFloat(name, value, pbvalue)source

Packs a float property into a entity_pb.PropertyValue.

Parameters

name – The name of the property as a string.
value – A float instance.
pbvalue – The entity_pb.PropertyValue to pack this value into.

google.appengine.api.datastore_types.PackGeoPt(name, value, pbvalue)source

Packs a GeoPt property into a entity_pb.PropertyValue.

Parameters

name – The name of the property as a string.
value – A GeoPt instance.
pbvalue – The entity_pb.PropertyValue to pack this value into.

google.appengine.api.datastore_types.PackInteger(name, value, pbvalue)source

Packs an integer property into a entity_pb.PropertyValue.

Parameters

name – The name of the property as a string.
value – An int or long instance.
pbvalue – The entity_pb.PropertyValue to pack this value into.

google.appengine.api.datastore_types.PackKey(name, value, pbvalue)source

Packs a reference property into a entity_pb.PropertyValue.

Parameters

name – The name of the property as a string.
value – A Key instance.
pbvalue – The entity_pb.PropertyValue to pack this value into.

google.appengine.api.datastore_types.PackString(name, value, pbvalue)source

Packs a string-typed property into a entity_pb.PropertyValue.

Parameters

name – The name of the property as a string.
value – A string, unicode, or string-like value instance.
pbvalue – The entity_pb.PropertyValue to pack this value into.

google.appengine.api.datastore_types.PackUser(name, value, pbvalue)source

Packs a User property into a entity_pb.PropertyValue.

Parameters

name – The name of the property as a string.
value – A users.User instance.
pbvalue – The entity_pb.PropertyValue to pack this value into.

google.appengine.api.datastore_types.PartitionString(value, separator)source

Equivalent to python2.5 str.partition(): TODO use str.partition() when python 2.5 is adopted.

Parameters

value – String to be partitioned
separator – Separator string

class google.appengine.api.datastore_types.PhoneNumber(phone)source

Bases: unicode

A human-readable phone number or address.

No validation is performed. Phone numbers have many different formats - local, long distance, domestic, international, internal extension, TTY, VOIP, SMS, and alternative networks like Skype, XFire and Roger Wilco. They all have their own numbering and addressing formats.

This is the gd:phoneNumber element. In XML output, the phone number is provided as the text of the element. See: https://developers.google.com/gdata/docs/1.0/elements#gdPhoneNumber

Raises BadValueError if phone is not a string or subtype.

ToXml()source

class google.appengine.api.datastore_types.PostalAddress(address)source

Bases: unicode

A human-readable mailing address. Again, mailing address formats vary widely, so no validation is performed.

This is the gd:postalAddress element. In XML output, the address is provided as the text of the element. See: https://developers.google.com/gdata/docs/1.0/elements#gdPostalAddress

Raises BadValueError if address is not a string or subtype.

ToXml()source

google.appengine.api.datastore_types.PropertyTypeName(value)source

Returns the name of the type of the given property value, as a string.

Raises BadValueError if the value is not a valid property type.

Parameters

value – any valid property value

Returns

string

google.appengine.api.datastore_types.PropertyValueFromString(type_, value_string, _auth_domain=None)source

Returns an instance of a property value given a type and string value.

The reverse of this method is just str() and type() of the python value.

Note that this does not support non-UTC offsets in ISO 8601-formatted datetime strings, e.g. the -08:00 suffix in ‘2002-12-25 00:00:00-08:00’. It only supports -00:00 and +00:00 suffixes, which are UTC.

Parameters

type – A python class.
value_string – A string representation of the value of the property.

Returns

An instance of ‘type’.

Raises

ValueError if type_ is datetime and value_string has a timezone offset.

google.appengine.api.datastore_types.PropertyValueToKeyValue(prop_value)source

Converts a entity_pb.PropertyValue into a comparable hashable “key” value.

The values produces by this function mimic the native ording of the datastore and uniquely identify the given PropertyValue.

Parameters

prop_value – The entity_pb.PropertyValue from which to construct the key value.

Returns

A comparable and hashable representation of the given property value.

class google.appengine.api.datastore_types.Rating(rating)source

Bases: long

A user-provided integer rating for a piece of content. Normalized to a 0-100 scale.

This is the gd:rating element. In XML output, the address is provided as the text of the element. See: https://developers.google.com/gdata/docs/1.0/elements#gdRating

Serializes to the decimal string representation of the rating. Raises BadValueError if the rating is not an integer in the range [0, 100].

MAX = 100

MIN = 0

ToXml()source

google.appengine.api.datastore_types.ReferenceToKeyValue(key, id_resolver=None)source

Converts a key into a comparable hashable “key” value.

Parameters

key – The entity_pb.Reference or googledatastore.Key from which to construct the key value.
id_resolver – An optional datastore_pbs.IdResolver. Only necessary for googledatastore.Key values.

Returns

A comparable and hashable representation of the given key that is compatible with one derived from a key property value.

google.appengine.api.datastore_types.ResolveAppId(app)source

Validate app id, providing a default.

If the argument is None, $APPLICATION_ID is substituted.

Parameters

app – The app id argument value to be validated.

Returns

The value of app, or the substituted default. Always a non-empty string.

Raises

BadArgumentError if the value is empty or not a string.

google.appengine.api.datastore_types.ResolveNamespace(namespace)source

Validate app namespace, providing a default.

If the argument is None, namespace_manager.get_namespace() is substituted.

Parameters

namespace – The namespace argument value to be validated.

Returns

The value of namespace, or the substituted default. The empty string is used to denote the empty namespace.

Raises

BadArgumentError if the value is not a string.

google.appengine.api.datastore_types.RestoreFromIndexValue(index_value, data_type)source

Restores a index value to the correct datastore type.

Projection queries return property values direclty from a datastore index. These values are the native datastore values, one of str, bool, long, float, GeoPt, Key or User. This function restores the original value when the original type is known.

This function returns the value type returned when decoding a normal entity, not necessarily of type data_type. For example, data_type=int returns a long instance.

Parameters

index_value – The value returned by FromPropertyPb for the projected property.
data_type – The type of the value originally given to ToPropertyPb

Returns

The restored property value.

Raises

datastore_errors.BadValueError if the value cannot be restored.

google.appengine.api.datastore_types.SetNamespace(proto, namespace)source

Sets the namespace for a protocol buffer or clears the field.

Parameters

proto – the protocol buffer to update
namespace – the new namespace (None or an empty string will clear out the field).

class google.appengine.api.datastore_types.Textsource

Bases: unicode

A long string type.

Strings of any length can be stored in the datastore using this type. It behaves identically to the Python unicode type, except for the constructor, which only accepts str and unicode arguments.

google.appengine.api.datastore_types.ToPropertyPb(name, values)source

Creates type-specific entity_pb.PropertyValues.

Determines the type and meaning of the PropertyValue based on the Python type of the input value(s).

NOTE: This function does not validate anything!

Parameters

name – string or unicode; the property name
values – The values for this property, either a single one or a list of them. All values must be a supported type. Lists of values must all be of the same type.

Returns

A list of entity_pb.Property instances.

class google.appengine.api.datastore_types.UtcTzinfosource

Bases: datetime.tzinfo

dst(dt)source

tzname(dt)source

utcoffset(dt)source

google.appengine.api.datastore_types.ValidateInteger(value, name='unused', exception=google.appengine.api.datastore_errors.BadValueError, empty_ok=False, zero_ok=False, negative_ok=False)source

Raises an exception if value is not a valid integer.

An integer is valid if it’s not negative or empty and is an integer (either int or long). The exception type raised can be specified with the exception argument; it defaults to BadValueError.

Parameters

value – the value to validate.
name – the name of this value; used in the exception message.
exception – the type of exception to raise.
empty_ok – allow None value.
zero_ok – allow zero value.
negative_ok – allow negative value.

google.appengine.api.datastore_types.ValidateProperty(name, values, read_only=False)source

Helper function for validating property values.

Parameters

name – Name of the property this is for.
value – Value for the property as a Python native type.
read_only – deprecated

Raises

BadPropertyError if the property name is invalid. BadValueError if the
property did not validate correctly or the value was an empty list. Other
exception types (like OverflowError) if the property value does not meet
type-specific criteria.

google.appengine.api.datastore_types.ValidatePropertyInteger(name, value)source

Raises an exception if the supplied integer is invalid.

Parameters

name – Name of the property this is for.
value – Integer value.

Raises

OverflowError if the value does not fit within a signed int64.

google.appengine.api.datastore_types.ValidatePropertyKey(name, value)source

Raises an exception if the supplied datastore.Key instance is invalid.

Parameters

name – Name of the property this is for.
value – A datastore.Key instance.

Raises

datastore_errors.BadValueError if the value is invalid.

google.appengine.api.datastore_types.ValidatePropertyLink(name, value)source

Validates the length of an indexed Link property.

Parameters

name – Name of the property this is for.
value – String value.

google.appengine.api.datastore_types.ValidatePropertyNothing(name, value)source

No-op validation function.

Parameters

name – Name of the property this is for.
value – Not used.

google.appengine.api.datastore_types.ValidatePropertyString(name, value)source

Validates the length of an indexed string property.

Parameters

name – Name of the property this is for.
value – String value.

google.appengine.api.datastore_types.ValidateReadProperty(name, values, read_only=False)source

Helper function for validating property values.

Parameters

name – Name of the property this is for.
value – Value for the property as a Python native type.
read_only – deprecated

Raises

BadPropertyError if the property name is invalid. BadValueError if the
property did not validate correctly or the value was an empty list. Other
exception types (like OverflowError) if the property value does not meet
type-specific criteria.

google.appengine.api.datastore_types.ValidateString(value, name='unused', exception=google.appengine.api.datastore_errors.BadValueError, max_len=1500, empty_ok=False)source

Raises an exception if value is not a valid string or a subclass thereof.

A string is valid if it’s not empty, no more than _MAX_STRING_LENGTH bytes, and not a Blob. The exception type can be specified with the exception argument; it defaults to BadValueError.

Parameters

value – the value to validate.
name – the name of this value; used in the exception message.
exception – the type of exception to raise.
max_len – the maximum allowed length, in bytes.
empty_ok – allow empty value.

google.appengine.api.datastore_types.ValidateStringLength(name, value, max_len)source

Raises an exception if the supplied string is too long.

Parameters

name – Name of the property this is for.
value – String value.
max_len – Maximum length the string may be.

Raises

OverflowError if the value is larger than the maximum length.

google.appengine.api.datastore_types.typename(obj)source: Returns the type of obj as a string. More descriptive and specific than type(obj), and safe for any object, unlike __class__.

google.appengine.api.datastore_types module

Summary

Contents