google.appengine.ext.ndb.context module

Summary

Context class.

Contents

class google.appengine.ext.ndb.context.Context(conn=None, auto_batcher_class=google.appengine.ext.ndb.context.AutoBatcher, config=None, parent_context=None)source

Bases: object

allocate_ids(*args, **kwds)source

call_on_commit(callback)source

Call a callback upon successful commit of a transaction.

If not in a transaction, the callback is called immediately.

In a transaction, multiple callbacks may be registered and will be called once the transaction commits, in the order in which they were registered. If the transaction fails, the callbacks will not be called.

If the callback raises an exception, it bubbles up normally. This means: If the callback is called immediately, any exception it raises will bubble up immediately. If the call is postponed until commit, remaining callbacks will be skipped and the exception will bubble up through the transaction() call. (However, the transaction is already committed at that point.)

clear_cache()source

Clears the in-memory cache.

NOTE: This does not affect memcache.

static default_cache_policy(key)source

Default cache policy.

This defers to _use_cache on the Model class.

Parameters

key – Key instance.

Returns

A bool or None.

static default_datastore_policy(key)source

Default datastore policy.

This defers to _use_datastore on the Model class.

Parameters

key – Key instance.

Returns

A bool or None.

static default_memcache_policy(key)source

Default memcache policy.

This defers to _use_memcache on the Model class.

Parameters

key – Key instance.

Returns

A bool or None.

static default_memcache_timeout_policy(key)source

Default memcache timeout policy.

This defers to _memcache_timeout on the Model class.

Parameters

key – Key instance.

Returns

Memcache timeout to use (integer), or None.

delete(*args, **kwds)source

flush(*args, **kwds)source

get(*args, **kwds)source

Return a Model instance given the entity key.

It will use the context cache if the cache policy for the given key is enabled.

Parameters

• key – Key instance.

• **ctx_options – Context options.

Returns

A Model instance if the key exists in the datastore; None otherwise.

get_cache_policy()source

Return the current context cache policy function.

Returns

A function that accepts a Key instance as argument and returns a bool indicating if it should be cached. May be None.

get_datastore_policy()source

Return the current context datastore policy function.

Returns

A function that accepts a Key instance as argument and returns a bool indicating if it should use the datastore. May be None.

get_indexes(*args, **kwds)source

get_memcache_policy()source

Return the current memcache policy function.

Returns

A function that accepts a Key instance as argument and returns a bool indicating if it should be cached. May be None.

get_memcache_timeout_policy()source

Return the current policy function for memcache timeout (expiration).

in_transaction()source

Return whether a transaction is currently active.

iter_query(*args, **kwds)source

map_query(*args, **kwds)source

memcache_add(key, value, time=0, namespace=None, deadline=None)source

memcache_cas(key, value, time=0, namespace=None, deadline=None)source

memcache_decr(key, delta=1, initial_value=None, namespace=None, deadline=None)source

memcache_delete(key, seconds=0, namespace=None, deadline=None)source

memcache_get(key, for_cas=False, namespace=None, use_cache=False, deadline=None)source

An auto-batching wrapper for memcache.get() or .get_multi().

Parameters

• key – Key to set. This must be a string; no prefix is applied.

• for_cas – If True, request and store CAS ids on the Context.

• namespace – Optional namespace.

• deadline – Optional deadline for the RPC.

Returns

A Future (!) whose return value is the value retrieved from memcache, or None.

memcache_gets(key, namespace=None, use_cache=False, deadline=None)source

memcache_incr(key, delta=1, initial_value=None, namespace=None, deadline=None)source

memcache_replace(key, value, time=0, namespace=None, deadline=None)source

memcache_set(key, value, time=0, namespace=None, use_cache=False, deadline=None)source

put(*args, **kwds)source

set_cache_policy(func)source

Set the context cache policy function.

Parameters

func – A function that accepts a Key instance as argument and returns a bool indicating if it should be cached. May be None.

set_datastore_policy(func)source

Set the context datastore policy function.

Parameters

func – A function that accepts a Key instance as argument and returns a bool indicating if it should use the datastore. May be None.

set_memcache_policy(func)source

Set the memcache policy function.

Parameters

func – A function that accepts a Key instance as argument and returns a bool indicating if it should be cached. May be None.

set_memcache_timeout_policy(func)source

Set the policy function for memcache timeout (expiration).

Parameters

func – A function that accepts a key instance as argument and returns an integer indicating the desired memcache timeout. May be None.

If the function returns 0 it implies the default timeout.

transaction(*args, **kwds)source

urlfetch(*args, **kwds)source

class google.appengine.ext.ndb.context.ContextOptionssource

Bases: google.appengine.datastore.datastore_rpc.Configuration

Configuration options that may be passed along with get/put/delete.

max_memcache_items

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

memcache_deadline

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

memcache_timeout

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

use_cache

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

use_datastore

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

use_memcache

A descriptor for a Configuration option.

This class is used to create a configuration option on a class that inherits from BaseConfiguration. A validator function decorated with this class will be converted to a read-only descriptor and BaseConfiguration will implement constructor and merging logic for that configuration option. A validator function takes a single non-None value to validate and either throws an exception or returns that value (or an equivalent value). A validator is called once at construction time, but only if a non-None value for the configuration option is specified the constructor’s keyword arguments.

class google.appengine.ext.ndb.context.TransactionOptionssource

Bases: google.appengine.ext.ndb.context.ContextOptions, google.appengine.datastore.datastore_rpc.TransactionOptions

Support both context options and transaction options.

class google.appengine.ext.ndb.context.AutoBatcher(todo_tasklet, limit)source

Bases: object

Batches multiple async calls if they share the same rpc options.

Here is an example to explain what this class does.

Life of a key.get_async(options) API call: *) Key gets the singleton Context instance and invokes Context.get. *) Context.get calls Context._get_batcher.add(key, options). This

returns a future “fut” as the return value of key.get_async. At this moment, key.get_async returns.

*) When more than “limit” number of _get_batcher.add() was called,

_get_batcher invokes its self._todo_tasklet, Context._get_tasklet, with the list of keys seen so far.

*) Context._get_tasklet fires a MultiRPC and waits on it. *) Upon MultiRPC completion, Context._get_tasklet passes on the results

to the respective “fut” from key.get_async.

*) If user calls “fut”.get_result() before “limit” number of add() was called,

“fut”.get_result() will repeatedly call eventloop.run1().

*) After processing immediate callbacks, eventloop will run idlers.

AutoBatcher._on_idle is an idler.

*) _on_idle will run the “todo_tasklet” before the batch is full.

So the engine is todo_tasklet, which is a proxy tasklet that can combine arguments into batches and passes along results back to respective futures. This class is mainly a helper that invokes todo_tasklet with the right arguments at the right time.

action()source

add(arg, options=None)source

Adds an arg and gets back a future.

Parameters

• arg – one argument for _todo_tasklet.

• options – rpc options.

Returns

An instance of future, representing the result of running

_todo_tasklet without batching.

add_once(arg, options=None)source

flush(*args, **kwds)source

run_queue(options, todo)source

Actually run the _todo_tasklet.