django-ztask 0.1.5
Django ZTask - A simple background task scheduler for Django
Keywords: django zeromq 0mq background task

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 order
2. 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_ztask
    
If you are not using [South](http://south.aeracode.org/) in your Django project, it is strongly recommended you do. If you
are 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 pyzmq
    pip install -e git+git@github.com:dmgctrl/django-ztask.git#egg=django_ztask

Add `django_ztask` to your `INSTALLED_APPS` setting in `settings.py`

    INSTALLED_APPS = (
        ...,
        'django_ztask',
    )

Then run `syncdb`

    python manage.py syncdb
    

Running the server
==================

Run django-ztask using the manage.py command:

    python manage.py ztaskd


Command-line arguments
----------------------

The `ztaskd` command takes a series of command-line arguments:

- `--noreload`
  
  By default, `ztaskd` will use the built-in Django reloader 
  to reload the server whenever a change is made to a python file. Passing
  in `--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 passed 
  in, `INFO` is used by default.

- `-f` or `--logfile`
  
  The file to log messages to. By default, all messages are logged
  to `stdout`

- `--replayfailed`
  
  If a command has failed more times than allowed in the 
  `ZTASKD_RETRY_COUNT` (see below for more), the task is
  logged as failed. Passing in `--replayfailed` will cause all 
  failed tasks to be re-run.


Settings
--------

There are several settings that you can put in your `settings.py` file in 
your Django project. These are the settings and their defaults

    ZTASKD_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 = False

If set to `True`, all `.async` and `.after` tasks will be run in-process and
not sent to the `ztaskd` process. Good for task debugging.

    ZTASKD_DISABLED = False

If set, all tasks will be logged, but not executed. This setting is often 
used during testing runs. If you set `ZTASKD_DISABLED` before running 
`python manage.py test`, tasks will be logged, but not executed.

    ZTASKD_RETRY_COUNT = 5

The number of times a task should be reattempted before it is considered failed.

    ZTASKD_RETRY_AFTER = 5

The 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 first
starts. 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 to 
the following in to your `rc.local` file. This example has been tested on 
Ubuntu 10.04 and Ubuntu 10.10:

    #!/bin/bash -e
    pushd /var/www/path/to/site
    sudo -u www-data python manage.py ztaskd --noreload -f /var/log/ztaskd.log &
    popd


Making 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 object 
to a task, you intead pass along the model's ID or primary key, and re-get 
the object in the task function.

The @task Decorator
-------------------

    from django_ztask.decorators import task

The `@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 asyncronously 
  on 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_print
        
    if __name__ == '__main__':
        
        # Call the function directly
        print_this('Hello world!')
        
        # Call the function asynchronously
        print_this.async('This will print to the ztaskd log')
        
        # Call the function asynchronously
        # after a 5 second delay
        print_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 cache 
is cleared. Since django-ztask doesn't concern itself with Middleware, you must put Johnny Cache's query cache
middleware 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 server 
        is started or reloaded
        '''
        from johnny import middleware
        middleware.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)