-----
About
-----

**django-future** is a Django app for scheduling jobs on specified times.

**django-future** allows you to schedule invocation of callables at a given
time.  The job queue is stored in the database and can be managed through the
admin interface.  Queued jobs are run by invoking an external django management
command.

-----
Usage
-----

You need to have **django-future** installed. A recent version should be
available from PyPI.

To schedule jobs from your code, use the ``schedule_job()`` function:

    >>> from django_future import schedule_job
    >>> import datetime

    >>> schedule_job(datetime.datetime(2010, 10, 10),
    ...              'myproject.myapp.handlers.dosomething')

------------
Running jobs
------------

Scheduled jobs will not start automagically.  The job queue must regularly
be processed by invoking the Django management command
``runscheduledjobs``.  You will probably want to run this command regularly,
perhaps in a cron job, to ensure that scheduled jobs are run in a timely
manner.

Each job is run in a separate database transaction.  If the handler raises
an error, the transaction is rolled back.

By default, job entries for completed jobs are marked as finished, but not
deleted from the database.  If you do not want to keep them, use the ``-d``
parameter to ``runscheduledjobs`` and they will be deleted upon successful
completion.

If a job handler raises an error, the queue processor will abort and
show the traceback.  If you do not want to abort the processing in such a case
use the ``-i`` parameter.  Either way, if an exception occurs, the traceback
will be stored on the job entry in the database.

----------------
Scheduling times
----------------

There are several ways to indicate the time the job should be executed.
You can use a straight datetime (as above), but you can also specify an offset
from the present.  The offset can be a specified as a timedelta:

    >>> schedule_job(datetime.timedelta(days=5), 'myproject.myapp.x')

or it can be a string:

    >>> schedule_job('5d', 'myproject.myapp.x')

An expiry time (one week by default) may also be specified so that old jobs
will not be run by accident.

    >>> schedule_job('5d', 'myproject.myapp.x', expires='7d')

The expiry date is calculated relative to the scheduled time.

----------
Parameters
----------

You can pass parameters to jobs:

    >>> schedule_job('5d', 'myproject.myapp.x',
    ...              args=[1, 2], kwargs={'foo': 'bar'})

The parameters will be passed on to the callable.  Note that the parameters
have to be picklable.

You can also associate a job with a database object:

    >>> schedule_job('5d', 'myproject.myapp.x',
    ...              content_object=some_model_instance)

If specified, the content object will be passed in to the callable as the first
parameter.

If you decorate your handler using ``job_as_parameter``, the active job will be
passed as a parameter.  Example:

    >>> from django_future import job_as_parameter

    >>> @job_as_parameter
    ... def handler(job):
    ...     do_stuff()

------------
Rescheduling
------------

Some jobs may need to be repeated.  You can achieve this by scheduling a new
job in the handler of a job, but it is more convenient to use the ``reschedule``
method on jobs. ``reschedule`` has the same signature as ``schedule_job``, but
copies attributes of the current job.

    >>> @job_as_parameter
    ... def handler(job, n=5):
    ...     job.reschedule('3d', kwargs={'n': 6})

When you pass a relative time value to ``reschedule()``, the new scheduled time
is calculated by adding the offset to the time at the moment you call
``reschedule()``.

-------
Caveats
-------

The job runner does not do locking.  If you run it again while a previous run
is still active, some jobs may be executed twice because of race conditions.

Exceptions raised by jobs will simply crash the job runner with a traceback.

--------
Feedback
--------

There is a `home page <http://github.com/shrubberysoft/django-future>`_ with
instructions on how to access the code repository.

Send feedback and suggestions to team@shrubberysoft.com.
