django-future 0.2.3

About

django-future is a Django application 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.

When the job processor is started, it checks for concurrently active job processors. If any active jobs are found, the new instance of the job processor will not continue and will raise an error, so you do not need to worry about overlapping parallel job runs.

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.

If a job returns a value, the unicode representation of that value will also 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):
...     do_something()
...     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 scheduled time of the original job, not to the time the job was actually executed.

Feedback

There is a home page with instructions on how to access the code repository.

Send feedback and suggestions to team@shrubberysoft.com.

Changes