### Supervisor Configuration Example

Source: https://github.com/koed00/django-q/blob/master/docs/cluster.md

Example configuration for managing the cluster with Supervisor.

```default
[program:django-q]
command = python manage.py qcluster
stopasgroup = true
```

--------------------------------

### Install Django Q

Source: https://github.com/koed00/django-q/blob/master/docs/install.md

Install the latest version of the package using pip.

```bash
$ pip install django-q
```

--------------------------------

### Cluster Startup Logs

Source: https://github.com/koed00/django-q/blob/master/docs/cluster.md

Example output showing the cluster initialization and worker readiness.

```default
10:57:40 [Q] INFO Q Cluster-31781 starting.
10:57:40 [Q] INFO Process-1:1 ready for work at 31784
10:57:40 [Q] INFO Process-1:2 ready for work at 31785
10:57:40 [Q] INFO Process-1:3 ready for work at 31786
10:57:40 [Q] INFO Process-1:4 ready for work at 31787
10:57:40 [Q] INFO Process-1:5 ready for work at 31788
10:57:40 [Q] INFO Process-1:6 ready for work at 31789
10:57:40 [Q] INFO Process-1:7 ready for work at 31790
10:57:40 [Q] INFO Process-1:8 ready for work at 31791
10:57:40 [Q] INFO Process-1:9 monitoring at 31792
10:57:40 [Q] INFO Process-1 guarding cluster at 31783
10:57:40 [Q] INFO Process-1:10 pushing tasks at 31793
10:57:40 [Q] INFO Q Cluster-31781 running.
```

--------------------------------

### Install Optional Dependencies

Source: https://github.com/koed00/django-q/blob/master/docs/install.md

Install various optional packages for specific brokers, performance, or additional features.

```bash
$ pip install redis
```

```bash
$ pip install psutil
```

```bash
$ pip install hiredis
```

```bash
$ pip install boto3
```

```bash
$ pip install iron-mq
```

```bash
$ pip install pymongo
```

```bash
$ pip install rollbar
```

```bash
$ pip install croniter
```

--------------------------------

### Circus Configuration Example

Source: https://github.com/koed00/django-q/blob/master/docs/cluster.md

Example configuration for managing the cluster with Circus.

```default
[circus]
check_delay = 5
endpoint = tcp://127.0.0.1:5555
pubsub_endpoint = tcp://127.0.0.1:5556
stats_endpoint = tcp://127.0.0.1:5557

[watcher:django_q]
cmd = python manage.py qcluster
numprocesses = 1
copy_env = True
```

--------------------------------

### Install Redis client library

Source: https://github.com/koed00/django-q/blob/master/docs/brokers.md

Required dependency for the Redis broker.

```bash
pip install redis
```

--------------------------------

### Configure Q_CLUSTER and async_task

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Example configuration for the Q_CLUSTER dictionary in settings.py and an asynchronous task invocation in example.py.

```python
# settings.py
Q_CLUSTER = {
   'retry': 5
   'workers': 4,
   'orm': 'default',
}

# example.py

from django_q.tasks import async_task

async_task('time.sleep', 22)
```

--------------------------------

### Install IronMQ client library

Source: https://github.com/koed00/django-q/blob/master/docs/brokers.md

Required dependency for the IronMQ broker.

```bash
pip install iron-mq
```

--------------------------------

### Start Cluster Monitor

Source: https://github.com/koed00/django-q/blob/master/docs/monitor.md

Launches the live cluster monitor interface via the Django management command.

```default
$ python manage.py qmonitor
```

--------------------------------

### Start Django Q Cluster

Source: https://github.com/koed00/django-q/blob/master/docs/cluster.md

Command to initiate the cluster process using Django's manage.py.

```default
$ python manage.py qcluster
```

--------------------------------

### Install Sentry error reporter

Source: https://github.com/koed00/django-q/blob/master/docs/install.md

Installs the Sentry error reporting add-on for Django Q.

```bash
$ pip install django-q[sentry]
```

--------------------------------

### Run Management Commands

Source: https://github.com/koed00/django-q/blob/master/README.rst

Commands for starting, monitoring, and checking the status of the cluster.

```bash
$ python manage.py qcluster
```

```bash
$ python manage.py qmonitor
```

```bash
$ python manage.py qmemory
```

```bash
$ python manage.py qinfo
```

--------------------------------

### Simple numeric output

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

A basic numeric output example.

```python
1
2
```

--------------------------------

### CPU Affinity Configuration Examples

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Illustrates how worker processes are distributed across CPU cores based on different affinity settings and total processor counts.

```default
# processor affinity example.

4 processors, 4 workers, cpu_affinity: 1

worker 1 cpu [0]
worker 2 cpu [1]
worker 3 cpu [2]
worker 4 cpu [3]

4 processors, 4 workers, cpu_affinity: 2

worker 1 cpu [0, 1]
worker 2 cpu [2, 3]
worker 3 cpu [0, 1]
worker 4 cpu [2, 3]

8 processors, 8 workers, cpu_affinity: 3

worker 1 cpu [0, 1, 2]
worker 2 cpu [3, 4, 5]
worker 3 cpu [6, 7, 0]
worker 4 cpu [1, 2, 3]
worker 5 cpu [4, 5, 6]
worker 6 cpu [7, 0, 1]
worker 7 cpu [2, 3, 4]
worker 8 cpu [5, 6, 7]
```

--------------------------------

### Procfile Entry

Source: https://github.com/koed00/django-q/blob/master/docs/cluster.md

Configuration line for starting the cluster within a Procfile.

```default
worker: python manage.py qcluster
```

--------------------------------

### Install Rollbar error reporter

Source: https://github.com/koed00/django-q/blob/master/docs/install.md

Installs the Rollbar error reporting add-on for Django Q.

```bash
$ pip install django-q[rollbar]
```

--------------------------------

### Chain result output

Source: https://github.com/koed00/django-q/blob/master/docs/chain.md

Example output returned by the chain result method.

```python
[-1.0, 1]
```

--------------------------------

### Cluster Stop Procedure Logs

Source: https://github.com/koed00/django-q/blob/master/docs/cluster.md

Example output showing the graceful shutdown sequence of the cluster.

```default
16:44:12 [Q] INFO Q Cluster-31781 stopping.
16:44:12 [Q] INFO Process-1 stopping cluster processes
16:44:13 [Q] INFO Process-1:10 stopped pushing tasks
16:44:13 [Q] INFO Process-1:6 stopped doing work
16:44:13 [Q] INFO Process-1:4 stopped doing work
16:44:13 [Q] INFO Process-1:1 stopped doing work
16:44:13 [Q] INFO Process-1:5 stopped doing work
16:44:13 [Q] INFO Process-1:7 stopped doing work
16:44:13 [Q] INFO Process-1:3 stopped doing work
16:44:13 [Q] INFO Process-1:8 stopped doing work
16:44:13 [Q] INFO Process-1:2 stopped doing work
16:44:14 [Q] INFO Process-1:9 stopped monitoring results
16:44:15 [Q] INFO Q Cluster-31781 has stopped.
```

--------------------------------

### Execute Shell Commands with Subprocess

Source: https://github.com/koed00/django-q/blob/master/docs/examples.md

Use async_task to run shell commands via the subprocess module. This example demonstrates basic file operations and listing directory contents.

```python
from django_q.tasks import async_task, result

# make a backup copy of setup.py
async_task('subprocess.call', ['cp', 'setup.py', 'setup.py.bak'])

# call ls -l and dump the output
task_id=async_task('subprocess.check_output', ['ls', '-l'])

# get the result
dir_list = result(task_id)
```

--------------------------------

### Using q_options for task configuration

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Shows how to pass task configuration options as a dictionary using the q_options keyword.

```default
# Async options in a dict

opts = {'hook': 'hooks.print_result',
        'group': 'math',
        'timeout': 30}

async_task('math.modf', 2.5, q_options=opts)
```

--------------------------------

### Instantiate and run an AsyncTask

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Demonstrates creating an AsyncTask instance, modifying parameters, and executing the task to retrieve results.

```python
# AsyncTask class instance example
from django_q.tasks import AsyncTask

# instantiate an async task
a = AsyncTask('math.floor', 1.5, group='math')

# you can set or change keywords afterwards
a.cached = True

# run it
a.run()

# wait indefinitely for the result and print it
print(a.result(wait=-1))

# change the args
a.args = (2.5,)

# run it again
a.run()

# wait max 10 seconds for the result and print it

print(a.result(wait=10))
```

--------------------------------

### Run Migrations

Source: https://github.com/koed00/django-q/blob/master/docs/install.md

Execute Django migrations to initialize the required database tables.

```bash
$ python manage.py migrate
```

--------------------------------

### result(task_id, wait=0, cached=False)

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Gets the result of a previously executed task.

```APIDOC
## result

### Description
Gets the result of a previously executed task.

### Parameters
- **task_id** (str) - Required - The uuid or name of the task
- **wait** (int) - Optional - Optional milliseconds to wait for a result. -1 for indefinite
- **cached** (bool) - Optional - Run this against the cache backend

### Returns
- **object** - The result of the executed task
```

--------------------------------

### Manage task schedules programmatically

Source: https://github.com/koed00/django-q/blob/master/docs/schedules.md

Demonstrates various ways to create schedules using the schedule wrapper, direct model creation, q_options, cron expressions, and cluster constraints.

```python
# Use the schedule wrapper
from django_q.tasks import schedule

schedule('math.copysign',
         2, -2,
         hook='hooks.print_result',
         schedule_type='D')

# Or create the object directly
from django_q.models import Schedule

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

# In case you want to use q_options
# Specify the broker by using the property broker_name in q_options
schedule('math.sqrt',
         9,
         hook='hooks.print_result',
         q_options={'timeout': 30, 'broker_name': 'broker_1'},
         schedule_type=Schedule.HOURLY)

# Run a schedule every 5 minutes, starting at 6 today
# for 2 hours
import arrow

schedule('math.hypot',
         3, 4,
         schedule_type=Schedule.MINUTES,
         minutes=5,
         repeats=24,
         next_run=arrow.utcnow().replace(hour=18, minute=0))

# Use a cron expression
schedule('math.hypot',
         3, 4,
         schedule_type=Schedule.CRON,
         cron = '0 22 * * 1-5')


# Restrain a schedule to a specific cluster
schedule('math.hypot',
         3, 4,
         schedule_type=Schedule.DAILY,
         cluster='my_cluster')
```

--------------------------------

### Offloading tasks with async_task

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Demonstrates how to offload tasks, retrieve results, and use hooks for task completion.

```python
from django_q.tasks import async_task, result

# create the task
async_task('math.copysign', 2, -2)

# or with import and storing the id
import math.copysign

task_id = async_task(copysign, 2, -2)

# get the result
task_result = result(task_id)

# result returns None if the task has not been executed yet
# you can wait for it
task_result = result(task_id, 200)

# but in most cases you will want to use a hook:

async_task('math.modf', 2.5, hook='hooks.print_result')

# hooks.py
def print_result(task):
    print(task.result)
```

--------------------------------

### Run Test Suite

Source: https://github.com/koed00/django-q/blob/master/README.rst

Commands to set up the environment and execute tests using pytest and Docker Compose.

```bash
# Create virtual environment
python -m venv venv

# Install requirements
venv/bin/pip install -r requirements.txt

# Install test dependencies
venv/bin/pip install pytest pytest-django

# Install django-q
venv/bin/python setup.py develop

# Run required services (you need to have docker-compose installed)
docker-compose -f test-services-docker-compose.yaml up -d

# Run tests
venv/bin/pytest

# Stop the services required by tests (when you no longer plan to run tests)
docker-compose -f test-services-docker-compose.yaml down
```

--------------------------------

### Configure Django Settings

Source: https://github.com/koed00/django-q/blob/master/docs/install.md

Add django_q to the INSTALLED_APPS tuple in your Django settings file.

```python
INSTALLED_APPS = (
    # other apps
    'django_q',
)
```

--------------------------------

### Configure Disque broker nodes

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Sets up a list of Disque nodes for the broker to connect to randomly.

```default
# example disque connection
Q_CLUSTER = {
    'name': 'DisqueBroker',
    'workers': 4,
    'timeout': 60,
    'retry': 60,
    'disque_nodes': ['127.0.0.1:7711', '127.0.0.1:7712']
}
```

--------------------------------

### AsyncTask(func, *args, **kwargs)

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Initializes a new task wrapper for the specified function with provided arguments and keyword options.

```APIDOC
## AsyncTask(func, *args, **kwargs)

### Description
A class wrapper for the async_task function used to define and manage task execution.

### Parameters
- **func** (object) - Required - The task function to execute
- **args** (tuple) - Optional - The arguments for the task function
- **kwargs** (dict) - Optional - Keyword arguments for the task function, including async_task options
```

--------------------------------

### Configure Custom Broker Class

Source: https://github.com/koed00/django-q/blob/master/docs/brokers.md

Register the custom broker by setting the broker_class path in the Q_CLUSTER configuration dictionary.

```python
# example Custom broker class connection

Q_CLUSTER = {
    'name': 'Custom',
    'workers': 8,
    'timeout': 60,
    'broker_class: 'myapp.broker.CustomBroker'
}
```

--------------------------------

### Queueing Emails with async_task and schedule

Source: https://github.com/koed00/django-q/blob/master/docs/examples.md

Demonstrates sending an immediate email via async_task and scheduling a follow-up email using the schedule function.

```python
# Welcome mail with follow up example
from datetime import timedelta
from django.utils import timezone
from django_q.tasks import async_task, schedule
from django_q.models import Schedule


def welcome_mail(user):
    msg = 'Welcome to our website'
    # send this message right away
    async_task('django.core.mail.send_mail',
            'Welcome',
            msg,
            'from@example.com',
            [user.email])
    # and this follow up email in one hour
    msg = 'Here are some tips to get you started...'
    schedule('django.core.mail.send_mail',
             'Follow up',
             msg,
             'from@example.com',
             [user.email],
             schedule_type=Schedule.ONCE,
             next_run=timezone.now() + timedelta(hours=1))

    # since the `repeats` defaults to -1
    # this schedule will erase itself after having run
```

--------------------------------

### Implement a Custom Broker

Source: https://github.com/koed00/django-q/blob/master/docs/brokers.md

Create a new broker class by inheriting from django_q.brokers.Broker and overriding the info method.

```python
# example Custom broker.py
from django_q.brokers import Broker

class CustomBroker(Broker):
    def info(self):
        return 'My Custom Broker'
```

--------------------------------

### Access group functions from task instance

Source: https://github.com/koed00/django-q/blob/master/docs/group.md

Demonstrates managing a group directly from a retrieved task instance.

```python
from django_q.tasks import fetch

task = fetch('winter-speaker-alpha-ceiling')
if  task.group_count() > 100:
    print(task.group_result())
    task.group_delete()
    print('Deleted group {}'.format(task.group))
```

--------------------------------

### Define Q_CLUSTER Configuration

Source: https://github.com/koed00/django-q/blob/master/README.rst

Optional configuration dictionary for the cluster settings in settings.py.

```python
# settings.py example
Q_CLUSTER = {
    'name': 'myproject',
    'workers': 8,
    'recycle': 500,
    'timeout': 60,
    'compress': True,
    'cpu_affinity': 1,
    'save_limit': 250,
    'queue_limit': 500,
    'label': 'Django Q',
    'redis': {
        'host': '127.0.0.1',
        'port': 6379,
        'db': 0, }
}
```

--------------------------------

### Configure Redis broker via URI

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Uses a connection string URI to configure the Redis broker.

```default
Q_CLUSTER = {
    'redis': 'redis://h:asdfqwer1234asdf@ec2-111-1-1-1.compute-1.amazonaws.com:111'
}
```

--------------------------------

### Configure Redis broker settings

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Defines the default connection parameters for a Redis broker in the Q_CLUSTER dictionary.

```default
# redis defaults
Q_CLUSTER = {
    'redis': {
        'host': 'localhost',
        'port': 6379,
        'db': 0,
        'password': None,
        'socket_timeout': None,
        'charset': 'utf-8',
        'errors': 'strict',
        'unix_socket_path': None
    }
}
```

--------------------------------

### Group tasks and retrieve results

Source: https://github.com/koed00/django-q/blob/master/docs/group.md

Demonstrates creating a group of tasks and waiting for a specific number of results.

```python
# result group example
from django_q.tasks import async_task, result_group

for i in range(4):
    async_task('math.modf', i, group='modf')

# wait until the group has 4 results
result = result_group('modf', count=4)
print(result)
```

```python
[(0.0, 0.0), (0.0, 1.0), (0.0, 2.0), (0.0, 3.0)]
```

--------------------------------

### schedule(func, *args, name=None, hook=None, schedule_type='O', minutes=None, repeats=-1, next_run=now(), q_options=None, **kwargs)

Source: https://github.com/koed00/django-q/blob/master/docs/schedules.md

Creates a new task schedule. This function allows you to define a function to be executed at specific intervals or times.

```APIDOC
## schedule(func, *args, name=None, hook=None, schedule_type='O', minutes=None, repeats=-1, next_run=now(), q_options=None, **kwargs)

### Description
Creates a schedule for a function to be executed by the task cluster.

### Parameters
- **func** (str) - Required - The function to schedule (dotted string).
- **args** (list) - Optional - Arguments for the scheduled function.
- **name** (str) - Optional - An optional name for your schedule.
- **hook** (str) - Optional - Optional result hook function (dotted string).
- **schedule_type** (str) - Optional - O(nce), M(I)nutes, H(ourly), D(aily), W(eekly), M(onthly), Q(uarterly), Y(early) or C(ron).
- **minutes** (int) - Optional - Number of minutes for the Minutes type.
- **cron** (str) - Optional - Cron expression for the Cron type.
- **repeats** (int) - Optional - Number of times to repeat schedule. -1=Always, 0=Never, n=n.
- **next_run** (datetime) - Optional - Next or first scheduled execution datetime.
- **cluster** (str) - Optional - Optional cluster name.
- **q_options** (dict) - Optional - Options passed to async_task for this schedule.
- **kwargs** (dict) - Optional - Optional keyword arguments for the scheduled function.
```

--------------------------------

### Configure MongoDB broker connection

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Define the Q_CLUSTER dictionary with MongoDB connection details and cluster settings.

```default
# example MongoDB broker connection

Q_CLUSTER = {
    'name': 'MongoDB',
    'workers': 8,
    'timeout': 60,
    'retry': 70,
    'queue_limit': 100,
    'mongo': {
            'host': '127.0.0.1',
            'port': 27017
    }
}
```

--------------------------------

### Configure Tynd Disque broker

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Configures Disque broker settings using environment variables, suitable for Heroku deployments.

```default
# example Tynd Disque connection
import os

Q_CLUSTER = {
    'name': 'TyndBroker',
    'workers': 8,
    'timeout': 30,
    'retry': 60,
    'bulk': 10,
    'disque_nodes': os.environ['TYND_DISQUE_NODES'].split(','),
    'disque_auth': os.environ['TYND_DISQUE_AUTH']
}
```

--------------------------------

### class Chain

Source: https://github.com/koed00/django-q/blob/master/docs/chain.md

A wrapper class for managing and executing sequential task chains.

```APIDOC
## class Chain(chain=None, group=None, cached=Conf.CACHED, sync=Conf.SYNC)

### Description
A sequential chain of tasks that acts as a convenient wrapper for async_chain.

### Methods
- **append(func, *args, **kwargs)**: Append a task to the chain. Returns the current number of tasks (int).
- **run()**: Start queueing the chain to the worker cluster. Returns the group id (str).
- **result(wait=0)**: Return the full list of results from the chain when it finishes. Blocks until timeout or result.
- **fetch(failures=True, wait=0)**: Get the task result objects from the chain when it finishes. Blocks until timeout or result.
- **current()**: Get the index of the currently executing chain element.
- **length()**: Get the length of the chain.
```

--------------------------------

### Display Cluster Summary

Source: https://github.com/koed00/django-q/blob/master/docs/monitor.md

Prints a one-off summary of cluster statistics or current configuration.

```default
$ python manage.py qinfo
```

```default
$ python manage.py qinfo --config
```

--------------------------------

### AsyncTask.run()

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Sends the configured task to a worker cluster for execution.

```APIDOC
## AsyncTask.run()

### Description
Send the task to a worker cluster for execution.
```

--------------------------------

### async_task(func, *args, hook=None, group=None, timeout=None, save=None, sync=False, cached=False, broker=None, q_options=None, **kwargs)

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Puts a task in the cluster queue for execution.

```APIDOC
## async_task

### Description
Puts a task in the cluster queue. Returns the uuid of the task.

### Parameters
- **func** (object) - Required - The task function to execute
- **args** (tuple) - Optional - The arguments for the task function
- **hook** (object) - Optional - Optional function to call after execution
- **group** (str) - Optional - An optional group identifier
- **timeout** (int) - Optional - Overrides global cluster timeout
- **save** (bool) - Optional - Overrides global save setting for this task
- **ack_failure** (bool) - Optional - Overrides the global ack_failures setting
- **sync** (bool) - Optional - If set to True, async_task will simulate a task execution
- **cached** (bool/int) - Optional - Output the result to the cache backend
- **broker** (object) - Optional - Optional broker connection
- **q_options** (dict) - Optional - Options dict, overrides option keywords
- **kwargs** (dict) - Optional - Keyword arguments for the task function

### Returns
- **str** - The uuid of the task
```

--------------------------------

### Generate reports asynchronously with hooks

Source: https://github.com/koed00/django-q/blob/master/docs/examples.md

Demonstrates triggering a report generation task and using a hook to handle the result or failure.

```python
# Report generation with hook example
from django_q.tasks import async_task

# views.py
# user requests a report.
def create_report(request):
    async_task('tasks.create_html_report',
            request.user,
            hook='tasks.email_report')
```

```python
# tasks.py
from django_q.tasks import async_task

# report generator
def create_html_report(user):
    html_report = 'We had a great quarter!'
    return html_report

# report mailer
def email_report(task):
    if task.success:
        # Email the report
        async_task('django.core.mail.send_mail',
                'The report you requested',
                task.result,
                'from@example.com',
                task.args[0].email)
    else:
        # Tell the admins something went wrong
        async_task('django.core.mail.mail_admins',
                'Report generation failed',
                task.result)
```

--------------------------------

### AsyncTask.fetch(wait=0)

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Returns the full Task result instance.

```APIDOC
## AsyncTask.fetch(wait=0)

### Description
Returns the full Task result instance.

### Parameters
- **wait** (int) - Optional - The number of milliseconds to wait for a result. -1 for indefinite
```

--------------------------------

### brokers.get_broker()

Source: https://github.com/koed00/django-q/blob/master/docs/brokers.md

Retrieves an instance of the currently configured Broker.

```APIDOC
### brokers.get_broker()

Returns a Broker instance based on the current configuration.
```

--------------------------------

### async_task(func, *args, **kwargs)

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Offloads a task to the cluster for asynchronous execution.

```APIDOC
## async_task(func, *args, **kwargs)

### Description
Offloads a task to the cluster for asynchronous execution. The function can be called with a string path to a function or a function object.

### Parameters
- **func** (str/callable) - Required - The function to execute.
- **args** (list) - Optional - Positional arguments for the function.
- **hook** (str) - Optional - Function to call after task execution, receiving the Task object.
- **group** (str) - Optional - A group label for the task.
- **save** (bool) - Optional - Overrides the result backend's save setting.
- **timeout** (int) - Optional - Overrides the cluster's timeout setting.
- **ack_failure** (bool) - Optional - Overrides the cluster's ack_failures setting.
- **sync** (bool) - Optional - Simulates synchronous execution.
- **cached** (bool/int) - Optional - Redirects result to cache backend with optional timeout.
- **broker** (object) - Optional - A custom broker instance.
- **task_name** (str) - Optional - Overwrites the auto-generated task name.
- **q_options** (dict) - Optional - A dictionary containing any of the above options.
```

--------------------------------

### Configure Django Q Cluster

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Define the Q_CLUSTER dictionary in settings.py to customize cluster settings like worker count, recycling, and Redis connection parameters.

```python
# settings.py example
Q_CLUSTER = {
    'name': 'myproject',
    'workers': 8,
    'recycle': 500,
    'timeout': 60,
    'compress': True,
    'save_limit': 250,
    'queue_limit': 500,
    'cpu_affinity': 1,
    'label': 'Django Q',
    'redis': {
        'host': '127.0.0.1',
        'port': 6379,
        'db': 0, }
}
```

--------------------------------

### Configure Amazon SQS Broker

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Credentials can be provided via config or standard boto3 methods. Bulk settings are limited to 1-10 with a 256kb payload limit.

```default
# example SQS broker connection

Q_CLUSTER = {
    'name': 'SQSExample',
    'workers': 4,
    'timeout': 60,
    'retry': 90,
    'queue_limit': 100,
    'bulk': 5,
    'sqs': {
        'aws_region': 'us-east-1',  # optional
        'aws_access_key_id': 'ac-Idr.....YwflZBaaxI',  # optional
        'aws_secret_access_key': '500f7b....b0f302e9'  # optional
    }
}
```

--------------------------------

### Fetch and filter group tasks

Source: https://github.com/koed00/django-q/blob/master/docs/group.md

Shows how to use fetch_group to retrieve task objects and filter them by success status.

```python
# fetch group example
from django_q.tasks import fetch_group, count_group, result_group

# count the number of failures
failure_count = count_group('modf', failures=True)

# only use the successes
results = fetch_group('modf')
if failure_count:
    results = results.exclude(success=False)
results =  [task.result for task in successes]

# this is the same as
results = fetch_group('modf', failures=False)
results =  [task.result for task in successes]

# and the same as
results = result_group('modf') # filters failures by default
```

--------------------------------

### Cached task execution

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Shows how to cache task results for a specific duration and convert them to persistent database records.

```default
# simple cached example
from django_q.tasks import async_task, result

# cache the result for 10 seconds
id = async_task('math.floor', 100, cached=10)

# wait max 50ms for the result to appear in the cache
result(id, wait=50, cached=True)

# or fetch the task object
task = fetch(id, cached=True)

# and then save it to the database
task.save()
```

--------------------------------

### Configure IronMQ Broker

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Connection settings for IronMQ. All standard connection keywords are supported.

```default
# example IronMQ connection

Q_CLUSTER = {
    'name': 'IronBroker',
    'workers': 8,
    'timeout': 30,
    'retry': 60,
    'queue_limit': 50,
    'bulk': 10,
    'iron_mq': {
        'host': 'mq-aws-us-east-1.iron.io',
        'token': 'Et1En7.....0LuW39Q',
        'project_id': '500f7b....b0f302e9'
    }
}
```

--------------------------------

### class Iter(func=None, args=None, kwargs=None, cached=Conf.CACHED, sync=Conf.SYNC, broker=None)

Source: https://github.com/koed00/django-q/blob/master/docs/iterable.md

An async task wrapper for iterable arguments, providing methods to append arguments and manage task execution.

```APIDOC
## Iter Class Methods

### append(*args)
Append arguments to the iter set. Returns the current set count.
- **args** (tuple) - Required - The arguments for a single execution
- **Returns** (int) - The current set count

### run()
Start queueing the tasks to the worker cluster.
- **Returns** (str) - The task result id

### result(wait=0)
Return the full list of results.
- **wait** (int) - Optional - How many milliseconds to wait for a result
- **Returns** (list) - An unsorted list of results

### fetch(wait=0)
Get the task result objects.
- **wait** (int) - Optional - How many milliseconds to wait for a result
- **Returns** (list) - An unsorted list of task objects

### length()
Get the length of the arguments list.
- **Returns** (int) - Length of the argument list
```

--------------------------------

### Perform Parzen-window estimation with task groups

Source: https://github.com/koed00/django-q/blob/master/docs/examples.md

Uses async_task with a group label to distribute calculations and result_group to aggregate the output.

```python
# Group example with Parzen-window estimation
import numpy

from django_q.tasks import async_task, result_group, delete_group

# the estimation function
def parzen_estimation(x_samples, point_x, h):
    k_n = 0
    for row in x_samples:
        x_i = (point_x - row[:, numpy.newaxis]) / h
        for row in x_i:
            if numpy.abs(row) > (1 / 2):
                break
        else:
            k_n += 1
    return h, (k_n / len(x_samples)) / (h ** point_x.shape[1])

# create 100 calculations and return the collated result
def parzen_async():
    # clear the previous results
    delete_group('parzen', cached=True)
    mu_vec = numpy.array([0, 0])
    cov_mat = numpy.array([[1, 0], [0, 1]])
    sample = numpy.random. \
        multivariate_normal(mu_vec, cov_mat, 10000)
    widths = numpy.linspace(1.0, 1.2, 100)
    x = numpy.array([[0], [0]])
    # async_task them with a group label to the cache backend
    for w in widths:
        async_task(parzen_estimation, sample, x, w,
                group='parzen', cached=True)
    # return after 100 results
    return result_group('parzen', count=100, cached=True)
```

--------------------------------

### Execute sequential tasks with Chain class

Source: https://github.com/koed00/django-q/blob/master/docs/chain.md

Uses the Chain class to build and run a sequence of tasks, providing a more convenient interface than the functional approach.

```python
# Chain async
from django_q.tasks import Chain

# create a chain that uses the cache backend
chain = Chain(cached=True)

# add some tasks
chain.append('math.copysign', 1, -1)
chain.append('math.floor', 1)

# run it
chain.run()

print(chain.result())
```

--------------------------------

### Configure Django ORM Broker

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Uses the Django database as a message broker. Performance can be improved by using a separate database backend.

```default
# example ORM broker connection

Q_CLUSTER = {
    'name': 'DjangORM',
    'workers': 4,
    'timeout': 90,
    'retry': 120,
    'queue_limit': 50,
    'bulk': 10,
    'orm': 'default'
}
```

```default
# example ORM broker connection with replica database

Q_CLUSTER = {
        ...
        'orm': 'default',
        'has_replica': True
    }
```

--------------------------------

### Using the Iter Class

Source: https://github.com/koed00/django-q/blob/master/docs/iterable.md

The Iter class provides a wrapper for managing iterable tasks, allowing for incremental argument appending and execution.

```python
from django_q.tasks import Iter

i = Iter('math.copysign')

# add some arguments
i.append(1, -1)
i.append(2, -1)
i.append(3, -1)

# run it
i.run()

# get the results
print(i.result())
```

```python
[-1.0, -2.0, -3.0]
```

--------------------------------

### async_chain(chain, group=None, cached=Conf.CACHED, sync=Conf.SYNC, broker=None)

Source: https://github.com/koed00/django-q/blob/master/docs/chain.md

Asynchronously executes a sequence of tasks.

```APIDOC
## async_chain(chain, group=None, cached=Conf.CACHED, sync=Conf.SYNC, broker=None)

### Description
Asynchronously executes a list of tasks in sequence.

### Parameters
- **chain** (list) - Required - A list of tasks in the format [(func,(args),{kwargs}), (func,(args),{kwargs})].
- **group** (str) - Optional - An optional group name.
- **cached** (bool) - Optional - Run this against the cache backend.
- **sync** (bool) - Optional - Execute this inline instead of asynchronous.
```

--------------------------------

### Execute Shell Commands with Python 3.5+ Subprocess

Source: https://github.com/koed00/django-q/blob/master/docs/examples.md

Utilize subprocess.run for Python 3.5+ compatibility, which returns a CompletedProcess object. Capturing output requires passing the PIPE constant.

```python
from django_q.tasks import async_task, result

# make a backup copy of setup.py
tid = async_task('subprocess.run', ['cp', 'setup.py', 'setup.py.bak'])

# get the result
r=result(tid, 500)
# we can now look at the original arguments
>>> r.args
['cp', 'setup.py', 'setup.py.bak']
# and the returncode
>>> r.returncode
0

# to capture the output we'll need a pipe
from subprocess import PIPE

# call ls -l and pipe the output
tid = async_task('subprocess.run', ['ls', '-l'], stdout=PIPE)
# get the result
res = result(tid, 500)
# print the output
print(res.stdout)
```

--------------------------------

### Use group functions on AsyncTask object

Source: https://github.com/koed00/django-q/blob/master/docs/group.md

Shows how to perform group operations using the AsyncTask interface.

```python
from django_q.tasks import AsyncTask

# add a task to the math group and run it cached
a = AsyncTask('math.floor', 2.5, group='math', cached=True)

# wait until this tasks group has 10 results
result = a.result_group(count=10)
```

--------------------------------

### Schedule wrapped management commands

Source: https://github.com/koed00/django-q/blob/master/docs/schedules.md

Schedule a custom wrapper function that executes a management command.

```python
# 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.tasks import schedule

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

--------------------------------

### Cached group task execution

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Demonstrates running multiple tasks under a group label using the cache backend for performance.

```default
# cached group example
from django_q.tasks import async_task, result_group
from django_q.brokers import get_broker

# set up a broker instance for better performance
broker = get_broker()

# Async a hundred functions under a group label
for i in range(100):
    async_task('math.frexp',
            i,
            group='frexp',
            cached=True,
            broker=broker)

# wait max 50ms for one hundred results to return
result_group('frexp', wait=50, count=100, cached=True)
```

--------------------------------

### Execute sequential tasks with async_chain

Source: https://github.com/koed00/django-q/blob/master/docs/chain.md

Uses the async_chain function to queue a list of tasks for sequential execution.

```python
# async a chain of tasks
from django_q.tasks import async_chain, result_group

# the chain must be in the format
# [(func,(args),{kwargs}),(func,(args),{kwargs}),..]
group_id = async_chain([('math.copysign', (1, -1)),
                          ('math.floor', (1,))])

# get group result
result_group(group_id, count=2)
```

--------------------------------

### Triggering Async Tasks from Model Signals

Source: https://github.com/koed00/django-q/blob/master/docs/examples.md

Shows how to use a pre_save signal to trigger an asynchronous task when a user's email changes.

```python
# Message on object change
from django.contrib.auth.models import User
from django.db.models.signals import pre_save
from django.dispatch import receiver
from django_q.tasks import async_task

# set up the pre_save signal for our user
@receiver(pre_save, sender=User)
def email_changed(sender, instance, **kwargs):
    try:
        user = sender.objects.get(pk=instance.pk)
    except sender.DoesNotExist:
        pass  # new user
    else:
        # has his email changed?
        if not user.email == instance.email:
            # tell everyone
            async_task('tasks.inform_everyone', instance)
```

--------------------------------

### Stat.get_all(broker=None)

Source: https://github.com/koed00/django-q/blob/master/docs/monitor.md

Retrieves a list of Stat objects for all active clusters.

```APIDOC
## Stat.get_all(broker=None)

### Description
Returns a list of Stat objects representing all currently active clusters.

### Parameters
- **broker** (object) - Optional - An optional broker connection instance.

### Returns
- **list[Stat]** (list) - A list of Stat instances for all active clusters.
```

--------------------------------

### Task Implementation for Signal Notifications

Source: https://github.com/koed00/django-q/blob/master/docs/examples.md

Provides two approaches for the task triggered by the signal: one using mass mail and one using individual async tasks.

```python
# tasks.py
def inform_everyone(user):
    mails = []
    for u in User.objects.exclude(pk=user.pk):
        msg = f"Dear {u.username}, {user.username} has a new email address: {user.email}"
        mails.append(('New email', msg,
                      'from@example.com', [u.email]))
    return send_mass_mail(mails)
```

```python
# or do it async again
def inform_everyone_async(user):
    for u in User.objects.exclude(pk=user.pk):
        msg = f"Dear {u.username}, {user.username} has a new email address: {user.email}"
        async_task('django.core.mail.send_mail',
                'New email', msg, 'from@example.com', [u.email])
```

--------------------------------

### Optimize broker connections with pooling

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Reuse a single broker instance when making multiple calls to async_task to reduce connection overhead.

```python
# broker connection economy example
from django_q.tasks import async_task
from django_q.brokers import get_broker

broker = get_broker()
for i in range(50):
    async_task('math.modf', 2.5, broker=broker)
```

--------------------------------

### Broker Class Methods

Source: https://github.com/koed00/django-q/blob/master/docs/brokers.md

Methods available on the Broker class for interacting with the message queue.

```APIDOC
### Broker Methods

- **async_task(task)**: Sends a task package to the broker queue and returns a tracking id if available.
- **dequeue()**: Gets packages from the broker and returns a list of tuples with a tracking id and the package.
- **acknowledge(id)**: Notifies the broker that the task has been processed.
- **fail(id)**: Tells the broker that the message failed to be processed by the cluster.
- **delete(id)**: Instructs the broker to delete this message from the queue.
- **purge_queue()**: Empties the current queue of all messages.
- **delete_queue()**: Deletes the current queue from the broker.
- **queue_size()**: Returns the amount of messages in the brokers queue.
- **lock_size()**: Optional method that returns the number of messages currently awaiting acknowledgement.
- **ping()**: Returns True if the broker can be reached.
- **info()**: Shows the name and version of the currently configured broker.
```

--------------------------------

### Execute a synchronous task

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Use sync=True to execute a task immediately for debugging purposes. This blocks until the task is finished and saved.

```python
from django_q.tasks import async_task, fetch

# create a synchronous task
task_id = async_task('my.buggy.code', sync=True)

# the task will then be available immediately
task = fetch(task_id)

# and can be examined
if not task.success:
    print('An error occurred: {}'.format(task.result))
```

```bash
An error occurred: ImportError("No module named 'my'",)
```

--------------------------------

### fetch_group(group_id, failures=True, wait=0, count=None, cached=False)

Source: https://github.com/koed00/django-q/blob/master/docs/group.md

Returns a list of tasks in a group.

```APIDOC
## fetch_group(group_id, failures=True, wait=0, count=None, cached=False)

### Description
Returns a list of tasks in a group.

### Parameters
- **group_id** (str) - Required - The group identifier
- **failures** (bool) - Optional - Set this to False to exclude failed tasks
- **wait** (int) - Optional - Optional milliseconds to wait for a task or count. -1 for indefinite
- **count** (int) - Optional - Block until there are this many tasks in the group
- **cached** (bool) - Optional - Run this against the cache backend

### Response
- **Return type** (list) - A list of Task objects
```

--------------------------------

### AsyncTask.fetch_group(failures=True, wait=0, count=None)

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Returns a list of task results from the task's group.

```APIDOC
## AsyncTask.fetch_group(failures=True, wait=0, count=None)

### Description
Returns a list of task results from this task’s group.

### Parameters
- **failures** (bool) - Optional - Set this to False to exclude failed tasks
- **wait** (int) - Optional - Optional milliseconds to wait for a task or count. -1 for indefinite
- **count** (int) - Optional - Block until there are this many tasks in the group
```

--------------------------------

### queue_size()

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Returns the size of the broker queue.

```APIDOC
## queue_size

### Description
Returns the size of the broker queue. Note that this does not count tasks currently being processed.

### Returns
- **int** - The amount of task packages in the broker
```

--------------------------------

### Configure Error Reporter for Django Q

Source: https://github.com/koed00/django-q/blob/master/docs/configure.md

Define the error_reporter dictionary within the Q_CLUSTER configuration to integrate with services like Rollbar.

```default
# error_reporter config--rollbar example
Q_CLUSTER = {
    'error_reporter': {
        'rollbar': {
            'access_token': '32we33a92a5224jiww8982',
            'environment': 'Django-Q'
        }
    }
}
```

--------------------------------

### fetch(task_id, wait=0, cached=False)

Source: https://github.com/koed00/django-q/blob/master/docs/tasks.md

Returns a previously executed task object.

```APIDOC
## fetch

### Description
Returns a previously executed task object.

### Parameters
- **task_id** (str) - Required - The uuid or name of the task
- **wait** (int) - Optional - Optional milliseconds to wait for a result. -1 for indefinite
- **cached** (bool) - Optional - Run this against the cache backend

### Returns
- **Task** - A task object
```

--------------------------------

### async_iter(func, args_iter, **kwargs)

Source: https://github.com/koed00/django-q/blob/master/docs/iterable.md

Runs iterable arguments against the cache backend and returns a single collated result. This function queues individual tasks for each item in the iterable.

```APIDOC
## async_iter(func, args_iter, **kwargs)

### Description
Runs iterable arguments against the cache backend and returns a single collated result. Accepts the same options as async_task() except hook.

### Parameters
- **func** (object) - Required - The task function to execute
- **args** (iterable) - Required - An iterable containing arguments for the task function
- **kwargs** (dict) - Optional - Keyword arguments for the task function

### Returns
- **str** - The uuid of the task
```

--------------------------------

### Perform real-time Haystack indexing

Source: https://github.com/koed00/django-q/blob/master/docs/examples.md

Uses model signals to trigger asynchronous indexing tasks, preventing delays during model save operations.

```python
# Real time Haystack indexing
from .models import Document
from django.db.models.signals import post_save
from django.dispatch import receiver
from django_q.tasks import async_task

# hook up the post save handler
@receiver(post_save, sender=Document)
def document_changed(sender, instance, **kwargs):
    async_task('tasks.index_object', sender, instance, save=False)
    # turn off result saving to not flood your database
```

```python
# tasks.py
from haystack import connection_router, connections

def index_object(sender, instance):
    # get possible backends
    backends = connection_router.for_write(instance=instance)

    for backend in backends:
        # get the index for this model
        index = connections[backend].get_unified_index()\
            .get_index(sender)
        # update it
        index.update_object(instance, using=backend)
```

--------------------------------

### Execute Django Management Commands

Source: https://github.com/koed00/django-q/blob/master/docs/examples.md

Run Django management commands directly using the call_command function via async_task or schedule.

```python
from django_q.tasks import async_task, schedule

async_task('django.core.management.call_command','clearsessions')

# or clear those sessions every hour

schedule('django.core.management.call_command',
     'clearsessions',
     schedule_type='H')
```