Metadata-Version: 1.0
Name: django-future
Version: 0.2.1
Summary: Scheduled jobs in Django
Home-page: http://github.com/shrubberysoft/django-future
Author: Shrubbery Software
Author-email: team@shrubberysoft.com
License: UNKNOWN
Description: -----
        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 <http://github.com/shrubberysoft/django-future>`_ with
        instructions on how to access the code repository.
        
        Send feedback and suggestions to team@shrubberysoft.com.
        
        -------
        Changes
        -------
        
        Changes in version 0.2.1
        ========================
        
        * Fixed a bug in start_scheduled_jobs parameters (thanks to Maciek Szczesniak).
        
        Changes in version 0.2.0
        ========================
        
        * Store the string value returned by the job.
        
        Changes in version 0.1.9
        ========================
        
        * When rescheduling, the new date is calculated from the scheduled date of the
        current job rather than the start of the actual run.
        * Implemented check for concurrent job processors properly.
        * Status of expired jobs is now set to 'expired'.
        
        Changes in version 0.1.8
        ========================
        
        * Updated admin interface: colored status, filtering by date.
        * Reused django-picklefield implementation for storing job arguments instead of
        the homebrewn pickle field.
        
        Changes in version 0.1.7
        ========================
        
        * Doctests are now part of the source distribution.
        
        
        Changes in version 0.1.6
        ========================
        
        * Minor packaging and formatting changes.
        
        
        Changes in version 0.1.5
        ========================
        
        * Basic protection against concurrent job processors.
        * Added ``--ignore-errors`` option.
        
        
        Changes in version 0.1.4
        ========================
        
        * Transaction support.
        * Added ``-d`` option to ``runscheduledjobs`` command.
        * Better test coverage.
        
        
        Changes in version 0.1.3
        ========================
        
        * Fix pickled field implementation.
        * Job rescheduling made easy.
        
        
        Changes in version 0.1.1
        ========================
        
        * Renamed to ``django-future``.
        
        
        Changes in version 0.1
        ======================
        
        * First public release.
        
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: License :: OSI Approved :: MIT License
