0
# Job Management
1

2
Core functionality for creating, enqueueing, and managing background jobs in Django-RQ. This includes job decoration, direct enqueueing, and job lifecycle management.
3

4
## Capabilities
5

6
### Job Decorator
7

8
Transform regular Python functions into RQ tasks using the `@job` decorator.
9

10
```python { .api }
11
def job(func_or_queue, connection=None, *args, **kwargs):
12
    """
13
    Decorator to create RQ tasks from functions.
14
    
15
    Args:
16
        func_or_queue: Function to decorate or queue name/instance
17
        connection: Redis connection (optional)
18
        *args, **kwargs: RQ job options (timeout, result_ttl, etc.)
19
    
20
    Returns:
21
        Decorated function with .delay() and .enqueue() methods
22
    """
23
```
24

25
Usage examples:
26

27
```python
28
from django_rq import job
29

30
# Default queue
31
@job
32
def simple_task():
33
    return "Task completed"
34

35
# Specific queue
36
@job('high')
37
def priority_task():
38
    return "High priority task"
39

40
# With options
41
@job('default', timeout=3600)
42
def long_task():
43
    return "Long running task"
44

45
# Execute jobs
46
simple_task.delay()
47
priority_task.delay()
48
long_task.delay()
49
```
50

51
### Direct Job Enqueueing
52

53
Enqueue functions directly without decoration.
54

55
```python { .api }
56
def enqueue(func, *args, **kwargs):
57
    """
58
    Enqueue a job to the default queue.
59
    
60
    Args:
61
        func: Function to execute
62
        *args: Positional arguments for func
63
        **kwargs: Keyword arguments for func
64
    
65
    Returns:
66
        Job: RQ Job instance
67
    """
68
```
69

70
Usage example:
71

72
```python
73
import django_rq
74

75
def my_function(arg1, arg2):
76
    return arg1 + arg2
77

78
# Enqueue to default queue
79
job = django_rq.enqueue(my_function, 10, 20)
80
print(f"Job ID: {job.id}")
81
```
82

83
### Worker Management
84

85
Create and configure RQ workers for processing jobs.
86

87
```python { .api }
88
def get_worker(*queue_names, job_class=None, queue_class=None, worker_class=None, **kwargs):
89
    """
90
    Create an RQ worker for specified queues.
91
    
92
    Args:
93
        *queue_names: Names of queues to process
94
        job_class: Custom job class (optional)
95
        queue_class: Custom queue class (optional) 
96
        worker_class: Custom worker class (optional)
97
        **kwargs: Additional worker options
98
    
99
    Returns:
100
        Worker: RQ Worker instance
101
    """
102

103
def get_worker_class(worker_class=None):
104
    """
105
    Get worker class from settings or return default.
106
    
107
    Args:
108
        worker_class: Override worker class
109
        
110
    Returns:
111
        type: Worker class
112
    """
113

114
def get_exception_handlers():
115
    """
116
    Get custom exception handlers from settings.
117
    
118
    Returns:
119
        list: Exception handler functions
120
    """
121
```
122

123
Usage examples:
124

125
```python
126
import django_rq
127

128
# Worker for default queue
129
worker = django_rq.get_worker()
130
worker.work(burst=True)  # Process all jobs then exit
131

132
# Worker for multiple queues
133
worker = django_rq.get_worker('high', 'default', 'low')
134
worker.work()  # Run continuously
135

136
# Worker with custom classes
137
from myapp.workers import CustomWorker
138
worker = django_rq.get_worker('default', worker_class=CustomWorker)
139
```
140

141
### Job Class Configuration
142

143
Configure custom job classes for specialized job handling.
144

145
```python { .api }
146
def get_job_class(job_class=None):
147
    """
148
    Get job class from settings or return default.
149
    
150
    Args:
151
        job_class: Override job class (class or import path)
152
        
153
    Returns:
154
        type: Job class
155
    """
156
```
157

158
## Job Lifecycle
159

160
Jobs in Django-RQ follow the standard RQ lifecycle with Django-specific enhancements:
161

162
1. **Creation**: Jobs created via `@job` decorator or `enqueue()`
163
2. **Enqueueing**: Jobs added to Redis queue (with optional autocommit support)
164
3. **Processing**: Workers pick up and execute jobs
165
4. **Completion**: Results stored (with configurable TTL)
166
5. **Cleanup**: Automatic cleanup based on configuration
167

168
## Error Handling
169

170
Django-RQ provides comprehensive error handling:
171

172
- Custom exception handlers via `RQ_EXCEPTION_HANDLERS` setting
173
- Job retry mechanisms through RQ's built-in retry support
174
- Failed job registries for debugging and reprocessing
175
- Integration with Sentry for error monitoring
176

177
## Performance Considerations
178

179
- Use `autocommit=False` for batch job enqueueing within Django transactions
180
- Configure appropriate `DEFAULT_TIMEOUT` values for long-running jobs
181
- Use `burst=True` for testing and finite job processing
182
- Consider custom worker classes for specialized job processing needs