google.appengine.api.datastore module

Summary

The Python datastore API used by app developers.

Defines Entity, Query, and Iterator classes, as well as methods for all of the datastore's calls. Also defines conversions between the Python classes and their PB counterparts.

The datastore errors are defined in the datastore_errors module. That module is only required to avoid circular imports. datastore imports datastore_types, which needs BadValueError, so it can't be defined in datastore.

Contents

google.appengine.api.datastore.AllocateIds(model_key, size=None, **kwargs)source

Allocates a range of IDs of size or with max for the given key.

Allocates a range of IDs in the datastore such that those IDs will not be automatically assigned to new entities. You can only allocate IDs for model keys from your app. If there is an error, raises a subclass of datastore_errors.Error.

Either size or max must be provided but not both. If size is provided then a range of the given size is returned. If max is provided then the largest range of ids that are safe to use with an upper bound of max is returned (can be an empty range).

Max should only be provided if you have an existing numeric id range that you want to reserve, e.g. bulk loading entities that already have IDs. If you don't care about which IDs you receive, use size instead.

Parameters
  • model_key -- Key or string to serve as a model specifying the ID sequence in which to allocate IDs

  • size -- integer, number of IDs to allocate.

  • max -- integer, upper bound of the range of IDs to allocate.

  • config -- Optional Configuration to use for this request.

Returns

(start, end) of the allocated range, inclusive.

google.appengine.api.datastore.AllocateIdsAsync(model_key, size=None, **kwargs)source

Asynchronously allocates a range of IDs.

Identical to datastore.AllocateIds() except returns an asynchronous object. Call get_result() on the return value to block on the call and get the results.

google.appengine.api.datastore.CreateConfig(**kwds)source

Create a Configuration object for use in configuring datastore calls.

This configuration can be passed to most datastore calls using the 'config=...' argument.

Parameters
  • deadline -- Optional deadline; default None (which means the system default deadline will be used, typically 5 seconds).

  • on_completion -- Optional callback function; default None. If specified, it will be called with a UserRPC object as argument when an RPC completes.

  • read_policy -- Optional read policy; set to EVENTUAL_CONSISTENCY to enable eventually consistent reads (i.e. reads that may be satisfied from an older version of the datastore in some cases). The default read policy may have to wait until in-flight transactions are committed.

  • **kwds -- Other keyword arguments as long as they are supported by datastore_rpc.Configuration().

Returns

A datastore_rpc.Configuration instance.

google.appengine.api.datastore.CreateRPC(service='datastore_v3', deadline=None, callback=None, read_policy=None)source

Create an rpc for use in configuring datastore calls.

NOTE: This functions exists for backwards compatibility. Please use CreateConfig() instead. NOTE: the latter uses 'on_completion', which is a function taking an argument, wherease CreateRPC uses 'callback' which is a function without arguments.

Parameters
  • service -- Optional string; for backwards compatibility, must be 'datastore_v3'.

  • deadline -- Optional int or float, deadline for calls in seconds.

  • callback -- Optional callable, a callback triggered when this rpc completes; takes no arguments.

  • read_policy -- Optional read policy; set to EVENTUAL_CONSISTENCY to enable eventually consistent reads (i.e. reads that may be satisfied from an older version of the datastore in some cases). The default read policy may have to wait until in-flight transactions are committed.

Returns

A UserRPC instance.

google.appengine.api.datastore.CreateTransactionOptions(**kwds)source

Create a configuration object for use in configuring transactions.

This configuration can be passed as run_in_transaction_option's first argument.

Parameters
  • deadline -- Optional deadline; default None (which means the system default deadline will be used, typically 5 seconds).

  • on_completion -- Optional callback function; default None. If specified, it will be called with a UserRPC object as argument when an RPC completes.

  • xg -- set to true to allow cross-group transactions (high replication datastore only)

  • retries -- set the number of retries for a transaction

  • **kwds -- Other keyword arguments as long as they are supported by datastore_rpc.TransactionOptions().

Returns

A datastore_rpc.TransactionOptions instance.

class google.appengine.api.datastore.DatastoreAdapter(_id_resolver=None)source

Bases: google.appengine.datastore.datastore_rpc.AbstractAdapter

Adapter between datatypes defined here (Entity etc.) and protobufs.

See the base class in datastore_rpc.py for more docs.

entity_to_pb(entity)source
index_direction_mappings = {1: 1, 2: 2}
index_state_mappings = {1: 0, 2: 1, 3: 2, 4: 3}
key_to_pb(key)source
pb_to_entity(pb)source
pb_to_index(pb)source
pb_to_key(pb)source
google.appengine.api.datastore.Delete(keys, **kwargs)source

Deletes one or more entities from the datastore. Use with care!

Deletes the given entity(ies) from the datastore. You can only delete entities from your app. If there is an error, raises a subclass of datastore_errors.Error.

Parameters
  • the primary key (#) --

  • keys -- Key or string or list of Keys or strings

  • config -- Optional Configuration to use for this request, must be specified as a keyword argument.

Raises

TransactionFailedError, if the Delete could not be committed.

google.appengine.api.datastore.DeleteAsync(keys, **kwargs)source

Asynchronously deletes one or more entities from the datastore.

Identical to datastore.Delete() except returns an asynchronous object. Call get_result() on the return value to block on the call.

class google.appengine.api.datastore.Entity(kind, parent=None, _app=None, name=None, id=None, unindexed_properties=[], namespace=None, **kwds)source

Bases: dict

A datastore entity.

Includes read-only accessors for app id, kind, and primary key. Also provides dictionary-style access to properties.

static FromPb(pb, validate_reserved_properties=True, default_kind='')source

Static factory method. Returns the Entity representation of the given protocol buffer (datastore_pb.Entity).

Parameters
  • pb -- datastore_pb.Entity or str encoding of a datastore_pb.Entity

  • validate_reserved_properties -- deprecated

  • default_kind -- str, the kind to use if the pb has no key.

Returns

the Entity representation of pb

Return type

Entity

ToPb()source

Converts this Entity to its protocol buffer representation.

Returns

entity_pb.Entity

ToXml()source

Returns an XML representation of this entity. Atom and gd:namespace properties are converted to XML according to their respective schemas. For more information, see:

http://www.atomenabled.org/developers/syndication/ http://code.google.com/apis/gdata/common-elements.html

This is not optimized. It shouldn't be used anywhere near code that's performance-critical.

app()source

Returns the name of the application that created this entity, a string or None if not set.

copy()source

The copy method is not supported.

entity_group()source

Returns this entity's entity group as a Key.

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

is_projection()source

Returns if this entity is a projection from full entity.

Projected entities: - may not contain all properties from the original entity; - only contain single values for lists; - may not contain values with the same type as the original entity.

is_saved()source

Returns if this entity has been saved to the datastore.

key()source

Returns this entity's primary key, a Key instance.

kind()source

Returns this entity's kind, a string.

namespace()source

Returns the namespace of this entity, a string or None.

parent()source

Returns this entity's parent, as a Key. If this entity has no parent, returns None.

set_unindexed_properties(unindexed_properties)source
setdefault(name, value)source

If the property exists, returns its value. Otherwise sets it to value.

If the property name is the empty string or not a string, raises BadPropertyError. If the value is not a supported type, raises BadValueError.

unindexed_properties()source

Returns this entity's unindexed properties, as a frozenset of strings.

update(other)source

Updates this entity's properties from the values in other.

If any property name is the empty string or not a string, raises BadPropertyError. If any value is not a supported type, raises BadValueError.

google.appengine.api.datastore.Get(keys, **kwargs)source

Retrieves one or more entities from the datastore.

Retrieves the entity or entities with the given key(s) from the datastore and returns them as fully populated Entity objects, as defined below. If there is an error, raises a subclass of datastore_errors.Error.

If keys is a single key or string, an Entity will be returned, or EntityNotFoundError will be raised if no existing entity matches the key.

However, if keys is a list or tuple, a list of entities will be returned that corresponds to the sequence of keys. It will include entities for keys that were found and None placeholders for keys that were not found.

Parameters
  • keys -- Key or string or list of Keys or strings

  • config -- Optional Configuration to use for this request, must be specified as a keyword argument.

Returns

Entity or list of Entity objects

google.appengine.api.datastore.GetAsync(keys, **kwargs)source

Asynchronously retrieves one or more entities from the datastore.

Identical to datastore.Get() except returns an asynchronous object. Call get_result() on the return value to block on the call and get the results.

google.appengine.api.datastore.GetIndexes(**kwargs)source

Retrieves the application indexes and their states.

Parameters

config -- Optional Configuration to use for this request, must be specified as a keyword argument.

Returns

A list of (Index, Index.[BUILDING|SERVING|DELETING|ERROR]) tuples. An index can be in the following states:

Index.BUILDING: Index is being built and therefore can not serve queries Index.SERVING: Index is ready to service queries Index.DELETING: Index is being deleted Index.ERROR: Index encounted an error in the BUILDING state

google.appengine.api.datastore.GetIndexesAsync(**kwargs)source

Asynchronously retrieves the application indexes and their states.

Identical to GetIndexes() except returns an asynchronous object. Call get_result() on the return value to block on the call and get the results.

google.appengine.api.datastore.GetRpcFromKwargs(kwargs, convert_rpc=False, config_class=google.appengine.datastore.datastore_rpc.Configuration)source

Get a Configuration object from the keyword arguments.

This is purely an internal helper for the various public APIs below such as Get().

Parameters
  • kwargs -- A dict containing the keyword arguments passed to a public API.

  • convert_rpc -- If the an rpc should be converted or passed on directly.

  • config_class -- The config class that should be generated.

Returns

A UserRPC instance, or a Configuration instance, or None.

Raises

TypeError if unexpected keyword arguments are present.

class google.appengine.api.datastore.Index(index_id, kind, has_ancestor, properties)source

Bases: google.appengine.api.datastore._BaseIndex

A datastore index.

HasAncestor()source

Indicates if this is an ancestor index, a boolean.

Id()source

Returns the index id, a long.

Kind()source

Returns the index kind, a string. Empty string ('') if none.

Properties()source

Returns the index properties. a tuple of (index name as a string, [ASCENDING|DESCENDING]) tuples.

google.appengine.api.datastore.IsInTransaction()source

Determine whether already running in transaction.

Returns

True if already running in transaction, else False.

class google.appengine.api.datastore.Iterator(batcher)source

Bases: google.appengine.datastore.datastore_query.ResultsIterator

Thin wrapper of datastore_query.ResultsIterator.

Deprecated, do not use, only for backwards compatability.

GetCompiledCursor(query)source
GetIndexList()source

Returns the list of indexes used to perform the query.

index_list()source

Returns the list of indexes used to perform the query.

class google.appengine.api.datastore.MultiQuery(bound_queries, orderings)source

Bases: google.appengine.api.datastore.Query

Class representing a query which requires multiple datastore queries.

This class is actually a subclass of datastore.Query as it is intended to act like a normal Query object (supporting the same interface).

Does not support keys only queries, since it needs whole entities in order to merge sort them. (That's not true if there are no sort orders, or if the sort order is on __key__, but allowing keys only queries in those cases, but not in others, would be confusing.)

Count(limit=1000, **kwargs)source

Return the number of matched entities for this query.

Will return the de-duplicated count of results. Will call the more efficient Get() function if a limit is given.

Parameters
  • limit -- maximum number of entries to count (for any result > limit, return

  • limit). --

  • config -- Optional Configuration to use for this request.

Returns

count of the number of entries returned.

Get(limit, offset=0, **kwargs)source

Deprecated, use list(Run(...)) instead.

Parameters
  • limit -- int or long representing the maximum number of entities to return.

  • offset -- int or long representing the number of entities to skip

  • kwargs -- Any keyword arguments accepted by datastore_query.QueryOptions().

Returns

A list of entities with at most "limit" entries (less if the query completes before reading limit values).

GetCompiledCursor()source
GetCompiledQuery()source

Internal only, do not use.

GetCursor()source
GetIndexList()source
Run(**kwargs)source

Return an iterable output with all results in order.

Merge sort the results. First create a list of iterators, then walk though them and yield results in order.

Parameters

kwargs -- Any keyword arguments accepted by datastore_query.QueryOptions().

Returns

An iterator for the result set.

class SortOrderEntity(entity_iterator, orderings)source

Bases: object

Allow entity comparisons using provided orderings.

The iterator passed to the constructor is eventually consumed via calls to GetNext(), which generate new SortOrderEntity s with the same orderings.

CmpProperties(that)source

Compare two entities and return their relative order.

Compares self to that based on the current sort orderings and the key orders between them. Returns negative, 0, or positive depending on whether self is less, equal to, or greater than that. This comparison returns as if all values were to be placed in ascending order (highest value last). Only uses the sort orderings to compare (ignores

keys).

Parameters

that -- SortOrderEntity

Returns

Negative if self < that Zero if self == that Positive if self > that

GetEntity()source

Gets the wrapped entity.

GetNext()source

Wrap and return the next entity.

The entity is retrieved from the iterator given at construction time.

google.appengine.api.datastore.NonTransactional(*args, **kwds)source

A decorator that insures a function is run outside a transaction.

If there is an existing transaction (and allow_existing=True), the existing transaction is paused while the function is executed.

Parameters
  • _func -- do not use

  • allow_existing -- If false, throw an exception if called from within a transaction

Returns

A wrapper for the decorated function that ensures it runs outside a transaction.

google.appengine.api.datastore.NormalizeAndTypeCheck(arg, types)source

Normalizes and type checks the given argument.

Parameters
  • arg -- an instance or iterable of the given type(s)

  • types -- allowed type or tuple of types

Returns

A (list, bool) tuple. The list is a normalized, shallow copy of the argument. The boolean is True if the argument was a sequence, False if it was a single object.

Raises
  • AssertionError -- types includes list or tuple.

  • BadArgumentError -- arg is not an instance or sequence of one of the given

  • types.

google.appengine.api.datastore.NormalizeAndTypeCheckKeys(keys)source

Normalizes and type checks that the given argument is a valid key or keys.

A wrapper around NormalizeAndTypeCheck() that accepts strings, Keys, and Entities, and normalizes to Keys.

Parameters

keys -- a Key or sequence of Keys

Returns

A (list of Keys, bool) tuple. See NormalizeAndTypeCheck.

Raises
  • BadArgumentError -- arg is not an instance or sequence of one of the given

  • types.

google.appengine.api.datastore.Put(entities, **kwargs)source

Store one or more entities in the datastore.

The entities may be new or previously existing. For new entities, Put() will fill in the app id and key assigned by the datastore.

If the argument is a single Entity, a single Key will be returned. If the argument is a list of Entity, a list of Keys will be returned.

Parameters
  • entities -- Entity or list of Entities

  • config -- Optional Configuration to use for this request, must be specified as a keyword argument.

Returns

Key or list of Keys

Raises

TransactionFailedError, if the Put could not be committed.

google.appengine.api.datastore.PutAsync(entities, **kwargs)source

Asynchronously store one or more entities in the datastore.

Identical to datastore.Put() except returns an asynchronous object. Call get_result() on the return value to block on the call and get the results.

class google.appengine.api.datastore.Query(kind=None, filters={}, _app=None, keys_only=False, compile=True, cursor=None, namespace=None, end_cursor=None, projection=None, distinct=None, _namespace=None)source

Bases: dict

A datastore query.

(Instead of this, consider using appengine.ext.gql.Query! It provides a query language interface on top of the same functionality.)

Queries are used to retrieve entities that match certain criteria, including app id, kind, and property filters. Results may also be sorted by properties.

App id and kind are required. Only entities from the given app, of the given type, are returned. If an ancestor is set, with Ancestor(), only entities with that ancestor are returned.

Property filters are used to provide criteria based on individual property values. A filter compares a specific property in each entity to a given value or list of possible values.

An entity is returned if its property values match all of the query's filters. In other words, filters are combined with AND, not OR. If an entity does not have a value for a property used in a filter, it is not returned.

Property filters map filter strings of the form '<property name> <operator>' to filter values. Use dictionary accessors to set property filters, like so:

> query = Query('Person') > query['name ='] = 'Ryan' > query['age >='] = 21

This query returns all Person entities where the name property is 'Ryan' and the age property is at least 21.

Another way to build this query is:

> query = Query('Person') > query.update({'name =': 'Ryan', 'age >=': 21})

The supported operators are =, >, <, >=, and <=. Only one inequality filter may be used per query. Any number of equals filters may be used in a single Query.

A filter value may be a list or tuple of values. This is interpreted as multiple filters with the same filter string and different values, all ANDed together. For example, this query returns everyone with the tags "google" and "app engine":

> Query('Person', {'tag =': ('google', 'app engine')})

Result entities can be returned in different orders. Use the Order() method to specify properties that results will be sorted by, and in which direction.

Note that filters and orderings may be provided at any time before the query is run. When the query is fully specified, Run() runs the query and returns an iterator. The query results can be accessed through the iterator.

A query object may be reused after it's been run. Its filters and orderings can be changed to create a modified query.

If you know how many result entities you need, use Get() to fetch them:

> query = Query('Person', {'age >': 21}) > for person in query.Get(4): > print 'I have four pints left. Have one on me, %s!' % person['name']

If you don't know how many results you need, or if you need them all, you can get an iterator over the results by calling Run():

> for person in Query('Person', {'age >': 21}).Run(): > print 'Have a pint on me, %s!' % person['name']

Get() is more efficient than Run(), so use Get() whenever possible.

Finally, the Count() method returns the number of result entities matched by the query. The returned count is cached; successive Count() calls will not re-scan the datastore unless the query is changed.

ANCESTOR_FIRST = 2
ASCENDING = 1
Ancestor(ancestor)source

Sets an ancestor for this query.

This restricts the query to only return result entities that are descended from a given entity. In other words, all of the results will have the ancestor as their parent, or parent's parent, or etc.

Raises BadArgumentError or BadKeyError if parent is not an existing Entity or Key in the datastore.

Parameters
  • the key must be complete (#) --

  • ancestor -- Entity or Key

Returns

# this query Query

Count(limit=1000, **kwargs)source

Returns the number of entities that this query matches.

Parameters
  • a number or None. If there are more results than this, stop short (limit,) --

  • just return this number. Providing this argument makes the count (and) --

  • more efficient. (operation) --

  • config -- Optional Configuration to use for this request.

Returns

The number of results.

DESCENDING = 2
FILTER_FIRST = 3
FILTER_REGEX = <_sre.SRE_Pattern object>
Get(limit, offset=0, **kwargs)source

Deprecated, use list(Run(...)) instead.

Parameters
  • limit -- int or long representing the maximum number of entities to return.

  • offset -- int or long representing the number of entities to skip

  • kwargs -- Any keyword arguments accepted by datastore_query.QueryOptions().

Returns

# a list of entities [Entity, ...]

GetBatcher(config=None)source

Runs this query and returns a datastore_query.Batcher.

This is not intended to be used by application developers. Use Get() instead!

Parameters

config -- Optional Configuration to use for this request.

Returns

# an iterator that provides access to the query results Iterator

GetCompiledCursor()source

Get the cursor from the last run of this query.

The source of this cursor varies depending on what the last call was:
  • Run: A cursor that points immediately after the last result pulled off the returned iterator.

  • Get: A cursor that points immediately after the last result in the returned list.

  • Count: A cursor that points immediately after the last result counted.

Returns

A datastore_query.Cursor object that can be used in subsequent query requests.

Raises

AssertionError -- The query has not yet been run or cannot be compiled.

GetCompiledQuery()source

Returns the internal-only pb representation of the last query run.

Do not use.

Raises

AssertionError -- Query not compiled or not yet executed.

GetCursor()source

Get the cursor from the last run of this query.

The source of this cursor varies depending on what the last call was:
  • Run: A cursor that points immediately after the last result pulled off the returned iterator.

  • Get: A cursor that points immediately after the last result in the returned list.

  • Count: A cursor that points immediately after the last result counted.

Returns

A datastore_query.Cursor object that can be used in subsequent query requests.

Raises

AssertionError -- The query has not yet been run or cannot be compiled.

GetDistinct()source

Returns True if the current instance is distinct.

Returns

A boolean indicating if the distinct flag is set.

GetFilterPredicate()source

Returns a datastore_query.FilterPredicate for the current instance.

Returns

datastore_query.FilterPredicate or None if no filters are set on the current Query.

GetIndexList()source

Get the index list from the last run of this query.

Returns

A list of indexes used by the last run of this query.

Raises

AssertionError -- The query has not yet been run.

GetOrder()source

Gets a datastore_query.Order for the current instance.

Returns

datastore_query.Order or None if there are no sort orders set on the current Query.

GetQuery()source

Returns a datastore_query.Query for the current instance.

GetQueryOptions()source

Returns a datastore_query.QueryOptions for the current instance.

Hint(hint)source

Sets a hint for how this query should run.

The query hint gives us information about how best to execute your query. Currently, we can only do one index scan, so the query hint should be used to indicates which index we should scan against.

Use FILTER_FIRST if your first filter will only match a few results. In this case, it will be most efficient to scan against the index for this property, load the results into memory, and apply the remaining filters and sort orders there.

Similarly, use ANCESTOR_FIRST if the query's ancestor only has a few descendants. In this case, it will be most efficient to scan all entities below the ancestor and load them into memory first.

Use ORDER_FIRST if the query has a sort order and the result set is large or you only plan to fetch the first few results. In that case, we shouldn't try to load all of the results into memory; instead, we should scan the index for this property, which is in sorted order.

Note that hints are currently ignored in the v3 datastore!

Arg:

one of datastore.Query.[ORDER_FIRST, ANCESTOR_FIRST, FILTER_FIRST]

Returns

# this query Query

INEQUALITY_OPERATORS = frozenset(['<=', '>=', '<', '>'])
IsKeysOnly()source

Returns True if this query is keys only, false otherwise.

OPERATORS = {'>=': 4, '==': 5, '<=': 2, '=': 5, '<': 1, '>': 3}
ORDER_FIRST = 1
Order(*orderings)source

Specify how the query results should be sorted.

Result entities will be sorted by the first property argument, then by the second, and so on. For example, this:

> query = Query('Person') > query.Order('bday', ('age', Query.DESCENDING))

sorts everyone in order of their birthday, starting with January 1. People with the same birthday are sorted by age, oldest to youngest.

The direction for each sort property may be provided; if omitted, it defaults to ascending.

Order() may be called multiple times. Each call resets the sort order from scratch.

If an inequality filter exists in this Query it must be the first property passed to Order. Any number of sort orders may be used after the inequality filter property. Without inequality filters, any number of filters with different orders may be specified.

Entities with multiple values for an order property are sorted by their lowest value.

Note that a sort order implies an existence filter! In other words, Entities without the sort order property are filtered out, and not included in the query results.

If the sort order property has different types in different entities - ie, if bob['id'] is an int and fred['id'] is a string - the entities will be grouped first by the property type, then sorted within type. No attempt is made to compare property values across types.

Raises BadArgumentError if any argument is of the wrong format.

Parameters
  • the properties to sort by, in sort order. each argument may be either a (#) --

  • string or (#) --

Returns

# this query Query

Run(**kwargs)source

Runs this query.

If a filter string is invalid, raises BadFilterError. If a filter value is invalid, raises BadValueError. If an IN filter is provided, and a sort order on another property is provided, raises BadQueryError.

If you know in advance how many results you want, use limit=#. It's more efficient.

Parameters

kwargs -- Any keyword arguments accepted by datastore_query.QueryOptions().

Returns

# an iterator that provides access to the query results Iterator

UPPERBOUND_INEQUALITY_OPERATORS = frozenset(['<=', '<'])
copy()source

The copy method is not supported.

setdefault(filter, value)source

If the filter exists, returns its value. Otherwise sets it to value.

If the property name is the empty string or not a string, raises BadPropertyError. If the value is not a supported type, raises BadValueError.

update(other)source

Updates this query's filters from the ones in other.

If any filter string is invalid, raises BadFilterError. If any value is not a supported type, raises BadValueError.

google.appengine.api.datastore.RunInTransaction(function, *args, **kwargs)source

Runs a function inside a datastore transaction.

Runs the user-provided function inside transaction, retries default number of times.

Args:
function: a function to be run inside the transaction on all remaining

arguments

*args: positional arguments for function. **kwargs: keyword arguments for function.

Returns

the function's return value, if any

Raises

TransactionFailedError, if the transaction could not be committed.

google.appengine.api.datastore.RunInTransactionCustomRetries(retries, function, *args, **kwargs)source

Runs a function inside a datastore transaction.

Runs the user-provided function inside transaction, with a specified number of retries.

Args:

retries: number of retries (not counting the initial try) function: a function to be run inside the transaction on all remaining

arguments

*args: positional arguments for function. **kwargs: keyword arguments for function.

Returns

the function's return value, if any

Raises

TransactionFailedError, if the transaction could not be committed.

google.appengine.api.datastore.RunInTransactionOptions(options, function, *args, **kwargs)source

Runs a function inside a datastore transaction.

Runs the user-provided function inside a full-featured, ACID datastore transaction. Every Put, Get, and Delete call in the function is made within the transaction. All entities involved in these calls must belong to the same entity group. Queries are supported as long as they specify an ancestor belonging to the same entity group.

The trailing arguments are passed to the function as positional arguments. If the function returns a value, that value will be returned by RunInTransaction. Otherwise, it will return None.

The function may raise any exception to roll back the transaction instead of committing it. If this happens, the transaction will be rolled back and the exception will be re-raised up to RunInTransaction's caller.

If you want to roll back intentionally, but don't have an appropriate exception to raise, you can raise an instance of datastore_errors.Rollback. It will cause a rollback, but will not be re-raised up to the caller.

The function may be run more than once, so it should be idempotent. It should avoid side effects, and it shouldn't have any side effects that aren't safe to occur multiple times. This includes modifying the arguments, since they persist across invocations of the function. However, this doesn't include Put, Get, and Delete calls, of course.

Example usage:

> def decrement(key, amount=1): > counter = datastore.Get(key) > counter['count'] -= amount > if counter['count'] < 0: # don't let the counter go negative > raise datastore_errors.Rollback() > datastore.Put(counter) > > counter = datastore.Query('Counter', {'name': 'foo'}) > datastore.RunInTransaction(decrement, counter.key(), amount=5)

Transactions satisfy the traditional ACID properties. They are:

  • Atomic. All of a transaction's operations are executed or none of them are.

  • Consistent. The datastore's state is consistent before and after a

transaction, whether it committed or rolled back. Invariants such as "every entity has a primary key" are preserved.

  • Isolated. Transactions operate on a snapshot of the datastore. Other

datastore operations do not see intermediated effects of the transaction; they only see its effects after it has committed.

  • Durable. On commit, all writes are persisted to the datastore.

Nested transactions are not supported.

Parameters
  • options -- TransactionOptions specifying options (number of retries, etc) for this transaction

  • function -- a function to be run inside the transaction on all remaining arguments *args: positional arguments for function. **kwargs: keyword arguments for function.

Returns

the function's return value, if any

Raises

TransactionFailedError, if the transaction could not be committed.

google.appengine.api.datastore.Transactional(_func=None, **kwargs)source

A decorator that makes sure a function is run in a transaction.

Defaults propagation to datastore_rpc.TransactionOptions.ALLOWED, which means any existing transaction will be used in place of creating a new one.

WARNING: Reading from the datastore while in a transaction will not see any changes made in the same transaction. If the function being decorated relies on seeing all changes made in the calling scoope, set propagation=datastore_rpc.TransactionOptions.NESTED.

Parameters
  • _func -- do not use.

  • **kwargs -- TransactionOptions configuration options.

Returns

A wrapper for the given function that creates a new transaction if needed.

Send feedback about...

App Engine standard environment for Python