diff --git a/docs/admin.rst b/docs/admin.rst index b4c57a4..821cd28 100644 --- a/docs/admin.rst +++ b/docs/admin.rst @@ -41,14 +41,14 @@ Repeats If you want a schedule to only run a finite amount of times, e.g. every hour for the next 24 hours, you can do that using the :attr:`Schedule.repeats` attribute. In this case you would set the schedule type to :attr:`Schedule.HOURLY` and the repeats to `24`. Every time the schedule runs the repeats count down until it hits zero and schedule is no longer run. -When you set repeats to `-1` the schedule will continue indefinitely and the repeats will still count down. This can be used as an indicator of how many times the schedule has been executed. +When you set repeats to ``-1`` the schedule will continue indefinitely and the repeats will still count down. This can be used as an indicator of how many times the schedule has been executed. An exception to this are schedules of type :attr:`Schedule.ONCE`. Negative repeats for this schedule type will cause it to be deleted from the database. This behavior is useful if you have many delayed actions which you do not necessarily need a result for. A positive number will keep the ONCE schedule, but it will not run again. .. note:: - To run a `Once` schedule again, change the repeats to something other than `0`. Set a new run time before you do this or let it execute immediately. + To run a ``ONCE`` schedule again, change the repeats to something other than `0`. Set a new run time before you do this or let it execute immediately. Next run diff --git a/docs/cluster.rst b/docs/cluster.rst index 43d257d..8e1c43f 100644 --- a/docs/cluster.rst +++ b/docs/cluster.rst @@ -4,7 +4,7 @@ Cluster .. py:currentmodule:: django_q Django Q uses Python's multiprocessing module to manage a pool of workers that will handle your tasks. -Start your cluster using Django's `manage.py` command:: +Start your cluster using Django's ``manage.py`` command:: $ python manage.py qcluster @@ -26,7 +26,7 @@ You should see the cluster starting :: 10:57:40 [Q] INFO Q Cluster-31781 running. -Stopping the cluster with ctrl-c or either the `SIGTERM` and `SIGKILL` signals, will initiate the :ref:`stop_procedure`:: +Stopping the cluster with ctrl-c or either the ``SIGTERM`` and ``SIGKILL`` signals, will initiate the :ref:`stop_procedure`:: 16:44:12 [Q] INFO Q Cluster-31781 stopping. 16:44:12 [Q] INFO Process-1 stopping cluster processes @@ -50,7 +50,7 @@ You can have multiple clusters on multiple machines, working on the same queue a - They connect to the same Redis server. - They use the same cluster name. See :ref:`configuration` -- They share the same `SECRET_KEY` +- They share the same ``SECRET_KEY`` Using a Procfile ---------------- @@ -80,7 +80,7 @@ An example :file:`circus.ini` :: Note that we only start one process. It is not a good idea to run multiple instances of the cluster in the same environment since this does nothing to increase performance and in all likelihood will diminish it. -Control your cluster using the `workers`, `recycle` and `timeout` settings in your :ref:`configuration` +Control your cluster using the ``workers``, ``recycle`` and ``timeout`` settings in your :ref:`configuration` Architecture ------------ diff --git a/docs/index.rst b/docs/index.rst index a4241e4..6cc3d28 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,7 +16,7 @@ Features - Scheduled and repeated tasks - Encrypted and compressed packages - Failure and success database -- Result hooks +- Result hooks and groups - Django Admin integration - PaaS compatible with multiple instances - Multi cluster monitor diff --git a/docs/install.rst b/docs/install.rst index 747e373..3ad40a3 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -6,7 +6,7 @@ Installation $ pip install django-q -- Add :mod:`django_q` to `INSTALLED_APPS` in your projects :file:`settings.py`:: +- Add :mod:`django_q` to ``INSTALLED_APPS`` in your projects :file:`settings.py`:: INSTALLED_APPS = ( # other apps @@ -18,14 +18,14 @@ Installation $ python manage.py migrate - Make sure you have a `Redis `__ server running - somewhere + somewhere and know how to connect to it. .. _configuration: Configuration ------------- -Configuration is handled via the `Q_CLUSTER` dictionary in your :file:`settings.py` +Configuration is handled via the ``Q_CLUSTER`` dictionary in your :file:`settings.py` .. code:: python @@ -133,7 +133,7 @@ of the cache connection you want to use:: .. tip:: - Django Q uses your `SECRET_KEY` to encrypt task packages and prevent task crossover. So make sure you have it set up in your Django settings. + Django Q uses your ``SECRET_KEY`` to encrypt task packages and prevent task crossover. So make sure you have it set up in your Django settings. cpu_affinity ~~~~~~~~~~~~ @@ -175,7 +175,7 @@ As a rule of thumb; cpu_affinity 1 favors repetitive short running tasks, while .. note:: - The `cpu_affinity` setting requires the optional :ref:`psutil ` module. + The ``cpu_affinity`` setting requires the optional :ref:`psutil ` module. Requirements ------------ @@ -185,7 +185,7 @@ Django Q is tested for Python 2.7 and 3.4 - `Django `__ Django Q aims to use as much of Django's standard offerings as possible - The code is tested against Django version `1.7.8` and `1.8.2`. + The code is tested against Django version `1.7.9` and `1.8.3`. - `Django-picklefield `__ @@ -207,6 +207,7 @@ Django Q is tested for Python 2.7 and 3.4 Django Q uses Redis as a centralized hub between your Django instances and your Q clusters. + Optional ~~~~~~~~ .. _psutil: diff --git a/docs/tasks.rst b/docs/tasks.rst index d040a8e..c18a4aa 100644 --- a/docs/tasks.rst +++ b/docs/tasks.rst @@ -41,15 +41,15 @@ The function to call after the task has been executed. This function gets passed group """"" -A group label. Check :ref:`groups` for group functions +A group label. Check :ref:`groups` for group functions. save """" -Overrides the result backend's save setting. +Overrides the result backend's save setting for this task. timeout """"""" -Overrides the cluster's timeout setting. +Overrides the cluster's timeout setting for this task. sync """" @@ -61,7 +61,7 @@ A redis connection. In case you want to control your own connections. q_options """"""""" -None of the option keywords get passed on to the function. +None of the option keywords get passed on to the task function. As an alternative you can also put them in a single keyword dict named ``q_options``. This enables you to use these keywords for your function call:: @@ -79,7 +79,7 @@ Please not that this will override any other option keywords. Groups ------ -You can group together results by passing :func:`async` the optional `group` keyword: +You can group together results by passing :func:`async` the optional ``group`` keyword: .. code-block:: python @@ -111,7 +111,7 @@ Instead of :func:`result_group` you can also use :func:`fetch_group` to return a # only use the successes results = fetch_group('modf') if failure_count: - results.exclude(success=False) + results = results.exclude(success=False) results = [task.result for task in successes] # this is the same as @@ -126,13 +126,13 @@ Getting results by using :func:`result_group` is of course much faster than usin .. note:: - Although :func:`fetch_group` returns a queryset, due to the nature of the PickleField , calling `Queryset.values` on it will return a list of encoded results. + Although :func:`fetch_group` returns a queryset, due to the nature of the PickleField , calling ``Queryset.values`` on it will return a list of encoded results. Use list comprehension or an iterator instead. Synchronous testing ------------------- -:func:`async` can be instructed to execute a task immediately by setting the optional keyword `sync=True`. +:func:`async` can be instructed to execute a task immediately by setting the optional keyword ``sync=True``. The task will then be injected straight into a worker and the result saved by a monitor instance:: from django_q import async, fetch @@ -157,7 +157,7 @@ Connection pooling ------------------ Django Q tries to pass redis connections around its parts as much as possible to save you from running out of connections. -When you are making individual calls to :func:`async` a lot though, it can help to set up a redis connection to pass to :func:`async`: +When you are making individual calls to :func:`async` a lot though, it can help to set up a redis connection to reuse for :func:`async`: .. code:: python @@ -217,7 +217,7 @@ Reference Returns the results of a task group :param str group_id: the group identifier - :param bool failures: set this to `True` to include failed results + :param bool failures: set this to ``True`` to include failed results :returns: a list of results :rtype: list @@ -226,7 +226,7 @@ Reference Returns a list of tasks in a group :param str group_id: the group identifier - :param bool failures: set this to `False` to exclude failed tasks + :param bool failures: set this to ``False`` to exclude failed tasks :returns: a list of Tasks :rtype: list @@ -235,7 +235,7 @@ Reference Counts the number of task results in a group. :param str group_id: the group identifier - :param bool failures: counts the number of failures if `True` + :param bool failures: counts the number of failures if ``True`` :returns: the number of tasks or failures in a group :rtype: int @@ -244,7 +244,7 @@ Reference Deletes a group label from the database. :param str group_id: the group identifier - :param bool tasks: also deletes the associated tasks if `True` + :param bool tasks: also deletes the associated tasks if ``True`` :returns: the numbers of tasks affected :rtype: int @@ -263,7 +263,7 @@ Reference .. note:: This is for convenience and can be used as a parameter for most functions that take a `task_id`. - Keep in mind however that it is not guaranteed to be unique if you store very large amounts of tasks in the database. + Keep in mind that it is not guaranteed to be unique if you store very large amounts of tasks in the database. .. py:attribute:: func @@ -314,7 +314,7 @@ Reference .. py:classmethod:: get_result_group(group_id, failures=False) Returns a list of results from a task group. - Set failures to `True` to include failed results. + Set failures to ``True`` to include failed results. .. py:classmethod:: get_task(task_id) @@ -323,22 +323,22 @@ Reference .. py:classmethod:: get_task_group(group_id, failures=True) Gets a queryset of tasks with this group id. - Set failures to `False` to exclude failed tasks. + Set failures to ``False`` to exclude failed tasks. .. py:classmethod:: get_group_count(group_id, failures=False) Returns a count of the number of tasks results in a group. - Returns the number of failures when `failures=True` + Returns the number of failures when ``failures=True`` .. py:classmethod:: delete_group(group_id, objects=False) Deletes a group label only, by default. - If `objects=True` it will also delete the tasks in this group from the database. + If ``objects=True`` it will also delete the tasks in this group from the database. .. py:class:: Success - A proxy model of :class:`Task` with the queryset filtered on :attr:`Task.success` is True. + A proxy model of :class:`Task` with the queryset filtered on :attr:`Task.success` is ``True``. .. py:class:: Failure - A proxy model of :class:`Task` with the queryset filtered on :attr:`Task.success` is False. \ No newline at end of file + A proxy model of :class:`Task` with the queryset filtered on :attr:`Task.success` is ``False``. \ No newline at end of file