google.appengine.api.datastore module

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.

• 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.

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

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.

Create a Configuration object for use in configuring datastore calls.

This configuration can be passed to most datastore calls using the ‘config=…’ argument.

• 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().

A datastore_rpc.Configuration instance.

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.

• 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.

A UserRPC instance.

Create a configuration object for use in configuring transactions.

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

• 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().

A datastore_rpc.TransactionOptions instance.

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.

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.

• 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.

TransactionFailedError, if the Delete could not be committed.

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.

Bases: dict

A datastore entity.

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

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.

• 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.

Entity or list of Entity objects

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.

Retrieves the application indexes and their states.

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

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

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.

Get a Configuration object from the keyword arguments.

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

• 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.

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

TypeError if unexpected keyword arguments are present.

Bases: google.appengine.api.datastore._BaseIndex

A datastore index.

Determine whether already running in transaction.

True if already running in transaction, else False.

Bases: google.appengine.datastore.datastore_query.ResultsIterator

Thin wrapper of datastore_query.ResultsIterator.

Deprecated, do not use, only for backwards compatability.

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

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.

• _func – do not use

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

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

Normalizes and type checks the given argument.

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

• types – allowed type or tuple of types

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.

• AssertionError – types includes list or tuple.

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

• types.

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.

keys – a Key or sequence of Keys

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

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

• types.

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.

• entities – Entity or list of Entities

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

Key or list of Keys

TransactionFailedError, if the Put could not be committed.

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.

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.

Runs a function inside a read-only datastore transaction.

A read-only transaction cannot perform writes, but may be able to execute more efficiently.

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

• function – a function to be run inside the transaction on all remaining arguments

• *args – positional arguments for function.

• **kwargs – keyword arguments for function.

the function’s return value, if any

TransactionFailedError, if the transaction could not be committed.

Runs a function inside a read-only datastore transaction.

A read-only transaction cannot perform writes, but may be able to execute more efficiently.

Like RunInTransactionOptions, but with a read-only transaction.

• 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.

the function’s return value, if any

TransactionFailedError, if the transaction could not be committed.

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.

the function’s return value, if any

TransactionFailedError, if the transaction could not be committed.

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.

the function’s return value, if any

TransactionFailedError, if the transaction could not be committed.

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.

• 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.

the function’s return value, if any

TransactionFailedError, if the transaction could not be committed.

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.

• _func – do not use.

• **kwargs – TransactionOptions configuration options.

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