Emlyn O'Regan
Feb 20, 2017 · 4 min read
We need a decorator!

Note: For the latest on @task, see:

In my previous article, I discussed the problems with Google App Engine’s deferred library.

I promised to present a replacement, so here it is.

Use the @task decorator from appenginetaskutils in your projects so that, unlike with defer(), you can run any function or callable at all in a separate task. You can escape this serious limitation of deferred and all other replacement libraries, and pick up a few more nice features as a bonus.

UPDATE: I’ve moved @task to its own package im-task on pypi; the im_task repo is here. appenginetaskutils is now deprecated.


On github:


On pypi:



Use the python package for this library. You can find the package online here.

Change to your Python App Engine project’s root folder and do the following:

pip install appenginetaskutils --target lib

Or add it to your requirements.txt. You’ll also need to set up vendoring, see app engine vendoring instructions here.


The most basic element of the appenginetaskutils library is @task. This decorator function is designed to be used as a replacement for deferred.

Configuring @task

When using deferred you have a builtin to configure in app.yaml to make it work. For @task, you need to add the following to your app.yaml and/or <servicename>.yaml file:

- url: /_ah/task/.*
script: taskutils.app
login: admin

This rule creates a generic handler for @task to defer work to background push tasks.

Add it at the top of the handler list (to make sure other rules don’t override it).

Importing task

You can import task into your modules like this:

from taskutils import task

Using task as a decorator

You can take any function and make it run in a separate task, like this:

def myfunction():
... do stuff ...

Just call the function normally, eg:


You can use @task on any function, including nested functions, recursive functions, recursive nested functions, the sky is the limit. This is possible because of use of yccloudpickle as the underlying serialisation library.

Your function can also have arguments, including other functions:

def myouterfunction(mapf):    @task
def myinnerfunction(objects):
for object in objects:
...get some list of lists of objects...
for objects in objectslist:
def dosomethingwithobject(object):
... do something with an object ...

The functions and arguments are being serialised and deserialised for you behind the scenes.

When enqueuing a background task, the App Engine Task and TaskQueue libraries can take a set of parameters. You can pass these to the decorator:

@task(queue="myqueue", countdown=5)
def anotherfunction():
... do stuff ...

Details of the arguments allowed for Tasks are available here, under class google.appengine.api.taskqueue.Task(payload=None, **kwargs).

Using task as a factory

You can also use task to decorate a function on the fly, like this:

def somefunction(a, b):
... does something ...
somefunctionintask = task(somefunction, queue="myqueue")

Then you can call the function returned by task when you are ready:

somefunctionintask(1, 2)

You could do both of these steps at once, too:

task(somefunction, queue="myqueue")(1, 2)


Pass transactional=True to have your task launch transactionally. eg:

def myserioustransactionaltask():


If you’d like access to headers in your function (a dictionary of headers passed to your task, it’s a web request after all), set includeheaders=True in your call to @task. You’ll also need to accept the headers argument in your function.

def myfunctionwithheaders(amount, headers):
... stuff ...

App Engine passes useful information to your task in headers, for example X-Appengine-TaskRetryCount.

other bits

When using deferred, all your calls are logged as /_ah/queue/deferred. But @task uses a url of the form /_ah/task/<module>/<function>, eg:


which makes debugging a lot easier.


Thanks for reading this far. If you’re a Python App Engine coder, and you use deferred, my hope is that you can see how taskutils.task can make your code cleaner and your life easier.

I’d love feedback! Please tell me what you like and what you don’t.

Also, thanks to Shay Erlichmen and Mark Cummins for useful input. Thanks also to the Fresh Planet folks who make this library; I stole a bunch of your code!

And finally, thanks to Google. I’ve been critical of deferred, but I’ve been using it for years and loving it. You guys rock.

The Infinite Machine

Idiosyncratic Incantations in Python for Google App Engine

 by the author.

Emlyn O'Regan

Written by

I make things out of bits. Great and terrible things, tiny bits.

The Infinite Machine

Idiosyncratic Incantations in Python for Google App Engine

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade