Schedules
=========
.. py:currentmodule:: django_q

Schedule
--------

Schedules are regular Django models.
You can manage them through the :ref:`admin_page` or directly from your code with the :func:`schedule` function or the :class:`Schedule` model:

.. code:: python

    from django_q import Schedule, schedule

    # Use the schedule wrapper
    schedule('math.copysign',
             2, -2,
             hook='hooks.print_result',
             schedule_type=Schedule.DAILY)

    # Or create the object directly
    Schedule.objects.create(func='math.copysign',
                            hook='hooks.print_result',
                            args='2,-2',
                            schedule_type=Schedule.DAILY
                            )


Management Commands
-------------------

If you want to schedule regular Django management commands, you can use the :mod:`django.core.management` module to make a wrapper function which you can schedule in Django Q::

    # tasks.py
    from django.core import management

    # wrapping `manage.py clearsessions`
    def clear_sessions_command():
        return management.call_command('clearsessions')

    # now you can schedule it to run every hour
    from django_q import schedule

    schedule('tasks.clear_sessions_command', schedule_type='H')



Reference
---------

..  py:function:: schedule(func, *args, hook=None, schedule_type='O', repeats=-1, next_run=now() , **kwargs)

    Creates a schedule

    :param str func: the function to schedule. Dotted strings only.
    :param args: arguments for the scheduled function.
    :param str hook: optional result hook function. Dotted strings only.
    :param str schedule_type: (O)nce, (H)ourly, (D)aily, (W)eekly, (M)onthly, (Q)uarterly, (Y)early or :attr:`Schedule.TYPE`
    :param int repeats: Number of times to repeat schedule. -1=Always, 0=Never, n =n.
    :param datetime next_run: Next or first scheduled execution datetime.
    :param kwargs: optional keyword arguments for the scheduled function.

.. class:: Schedule

    A database model for task schedules.

    .. py:attribute:: id

    Primary key

    .. py:attribute:: func

    The function to be scheduled

    .. py:attribute:: hook

    Optional hook function to be called after execution.

    .. py:attribute:: args

    Positional arguments for the function.

    .. py:attribute:: kwargs

    Keyword arguments for the function

    .. py:attribute:: schedule_type

    The type of schedule. Follows :attr:`Schedule.TYPE`

    .. py:attribute:: TYPE

    :attr:`ONCE`, :attr:`HOURLY`, :attr:`DAILY`, :attr:`WEEKLY`, :attr:`MONTHLY`, :attr:`QUARTERLY`, :attr:`YEARLY`


    .. py:attribute:: repeats

    Number of times to repeat the schedule. -1=Always, 0=Never, n =n.
    When set to -1, this will keep counting down.

    .. py:attribute:: next_run

    Datetime of the next scheduled execution.

    .. py:attribute:: task

    Id of the last task generated by this schedule.

    .. py:method:: last_run()

    Admin link to the last executed task.

    .. py:method:: success()

    Returns the success status of the last executed task.

    .. py:attribute:: ONCE

    `'O'` the schedule will only run once.
    If it has a negative :attr:`repeats` it will be deleted after it has run.
    If you want to keep the result, set :attr:`repeats` to a positive number.

    .. py:attribute:: HOURLY

    `'H'` the scheduled task will run every hour after its first run.

    .. py:attribute:: DAILY

    `'D'` the scheduled task will run every day at the time of its first run.

    .. py:attribute:: WEEKLY

    `'W'` the task will run every week on they day and time of the first run.

    .. py:attribute:: MONTHLY

    `'M'` the tasks runs every month on they day and time of the last run.

    .. note::

        Months are tricky. If you schedule something on the 31st of the month and the next month has only 30 days or less, the task will run on the last day of the next month.
        It will however continue to run on that day, e.g. the 28th, in subsequent months.

    .. py:attribute:: QUARTERLY

    `'Q'` this task runs once every 3 months on the day and time of the last run.

    .. py:attribute:: YEARLY

    `'Y'` only runs once a year. The same caution as with months apply;
    If you set this to february 29th, it will run on february 28th in the following years.