Package: django-ztask
IMPORTANT: READ ME==================In version 0.1.4, we are introducing two major changes:1. Tasks now have a "created" datetime field. This was added to make sure `--replayfailed` replayed tasks in the appropriate order2. Introduced [South](http://south.aeracode.org/) migrations.IF YOU HAVE ALREADY INSTALLED django-ztask - you can "fake" the first migration, and then run the second migration:./manage.py migrate django_ztask --fake 0001./manage.py migrate django_ztaskIf you are not using [South](http://south.aeracode.org/) in your Django project, it is strongly recommended you do. If youare not, you will have to add the "created" field to your database manually.Installing==========Download and install 0MQ version 2.1.3 or better from [http://www.zeromq.org](http://www.zeromq.org)Install pyzmq and django_ztaskd using PIP:pip install pyzmqpip install -e git+git@github.com:dmgctrl/django-ztask.git#egg=django_ztaskAdd `django_ztask` to your `INSTALLED_APPS` setting in `settings.py`INSTALLED_APPS = (...,'django_ztask',)Then run `syncdb`python manage.py syncdbRunning the server==================Run django-ztask using the manage.py command:python manage.py ztaskdCommand-line arguments----------------------The `ztaskd` command takes a series of command-line arguments:- `--noreload`By default, `ztaskd` will use the built-in Django reloaderto reload the server whenever a change is made to a python file. Passingin `--noreload` will prevent it from listening for changed files.(Good to use in production.)- `-l` or `--loglevel`Choose from the standard `CRITICAL`, `ERROR`, `WARNING`,`INFO`, `DEBUG`, or `NOTSET`. If this argument isn't passedin, `INFO` is used by default.- `-f` or `--logfile`The file to log messages to. By default, all messages are loggedto `stdout`- `--replayfailed`If a command has failed more times than allowed in the`ZTASKD_RETRY_COUNT` (see below for more), the task islogged as failed. Passing in `--replayfailed` will cause allfailed tasks to be re-run.Settings--------There are several settings that you can put in your `settings.py` file inyour Django project. These are the settings and their defaultsZTASKD_URL = 'tcp://127.0.0.1:5555'By default, `ztaskd` will run over TCP, listening on 127.0.0.1 port 5555.ZTASKD_ALWAYS_EAGER = FalseIf set to `True`, all `.async` and `.after` tasks will be run in-process andnot sent to the `ztaskd` process. Good for task debugging.ZTASKD_DISABLED = FalseIf set, all tasks will be logged, but not executed. This setting is oftenused during testing runs. If you set `ZTASKD_DISABLED` before running`python manage.py test`, tasks will be logged, but not executed.ZTASKD_RETRY_COUNT = 5The number of times a task should be reattempted before it is considered failed.ZTASKD_RETRY_AFTER = 5The number, in seconds, to wait in-between task retries.ZTASKD_ON_LOAD = ()This is a list of callables - either classes or functions - that are called when the server firststarts. This is implemented to support several possible Django setup scenarios when launching`ztask` - for an example, see the section below called **Implementing with Johnny Cache**.Running in production---------------------A recommended way to run in production would be to put something similar tothe following in to your `rc.local` file. This example has been tested onUbuntu 10.04 and Ubuntu 10.10:#!/bin/bash -epushd /var/www/path/to/sitesudo -u www-data python manage.py ztaskd --noreload -f /var/log/ztaskd.log &popdMaking functions in to tasks============================Decorators and function extensions make tasks able to run.Unlike some solutions, tasks can be in any file anywhere.When the file is imported, `ztaskd` will register the task for running.**Important note: all functions and their arguments must be able to be pickled.**([Read more about pickling here](http://docs.python.org/tutorial/inputoutput.html#the-pickle-module))It is a recommended best practice that instead of passing a Django model objectto a task, you intead pass along the model's ID or primary key, and re-getthe object in the task function.The @task Decorator-------------------from django_ztask.decorators import taskThe `@task()` decorator will turn any normal function in to a`django_ztask` task if called using one of the function extensions.Function extensions-------------------Any function can be called in one of three ways:- `func(*args, *kwargs)`Calling a function normally will bypass the decorator and call the function directly- `func.async(*args, **kwargs)`Calling a function with `.async` will cause the function task to be called asyncronouslyon the ztaskd server. For backwards compatability, `.delay` will do the same thing as `.async`, but is deprecated.- `func.after(seconds, *args, **kwargs)`This will cause the task to be sent to the `ztaskd` server, which will wait `seconds`seconds to execute.Example-------from django_ztask.decorators import task@task()def print_this(what_to_print):print what_to_printif __name__ == '__main__':# Call the function directlyprint_this('Hello world!')# Call the function asynchronouslyprint_this.async('This will print to the ztaskd log')# Call the function asynchronously# after a 5 second delayprint_this.after(5, 'This will print to the ztaskd log')Implementing with Johnny Cache==============================Because [Johnny Cache](http://packages.python.org/johnny-cache/) monkey-patches all the Django query compilers,any changes to models in django-ztask that aren't properly patched won't reflect on your site until the cacheis cleared. Since django-ztask doesn't concern itself with Middleware, you must put Johnny Cache's query cachemiddleware in as a callable in the `ZTASKD_ON_LOAD` setting.ZTASKD_ON_LOAD = ('johnny.middleware.QueryCacheMiddleware',...)If you wanted to do this and other things, you could write your own function, and pass that in to`ZTASKD_ON_LOAD`, as in this example:**myutilities.py**def ztaskd_startup_stuff():'''Stuff to run every time the ztaskd serveris started or reloaded'''from johnny import middlewaremiddleware.QueryCacheMiddleware()... # Other setup stuff**settings.py**ZTASKD_ON_LOAD = ('myutilities.ztaskd_startup_stuff',...)TODOs and BUGS==============See: [http://github.com/dmgctrl/django-ztask/issues](http://github.com/dmgctrl/django-ztask/issues)