0
# Huey
1

2
Huey is a lightweight task queue library for Python that provides a clean and simple API for asynchronous task execution. It supports multiple storage backends including Redis, SQLite, file-system, and in-memory storage, making it highly versatile for different deployment scenarios.
3

4
## Package Information
5

6
- **Package Name**: huey
7
- **Language**: Python
8
- **Installation**: `pip install huey`
9

10
## Core Imports
11

12
```python
13
from huey import RedisHuey, SqliteHuey, MemoryHuey, FileHuey
14
from huey import crontab
15
from huey.exceptions import CancelExecution, RetryTask
16
```
17

18
## Basic Usage
19

20
```python
21
from huey import RedisHuey, crontab
22

23
# Create a huey instance with Redis storage
24
huey = RedisHuey('my-app')
25

26
# Define a simple task
27
@huey.task()
28
def add_numbers(a, b):
29
    return a + b
30

31
# Define a periodic task
32
@huey.periodic_task(crontab(minute='0', hour='2'))
33
def nightly_report():
34
    generate_nightly_report()
35

36
# Enqueue and get results
37
result = add_numbers(5, 3)
38
print(result())  # Gets result when ready
39

40
# Schedule task for later execution
41
result = add_numbers.schedule((10, 20), delay=60)  # Run in 60 seconds
42
```
43

44
## Architecture
45

46
Huey's architecture consists of several key components:
47

48
- **Huey Instance**: Central coordinator managing task queues, storage, and execution
49
- **Storage Backends**: Pluggable storage implementations (Redis, SQLite, file, memory)
50
- **Task Decorators**: Function decorators that convert regular functions into queueable tasks
51
- **Consumer Process**: Separate worker process that executes queued tasks
52
- **Result Handling**: Optional result storage and retrieval system
53
- **Scheduling System**: Support for delayed and periodic task execution
54

55
## Capabilities
56

57
### Core Task Queue Operations
58

59
The primary task queue functionality including task creation, enqueueing, result handling, and basic queue management operations.
60

61
```python { .api }
62
class Huey:
63
    def task(self, retries=0, retry_delay=0, priority=None, context=False, 
64
             name=None, expires=None, **kwargs): ...
65
    def enqueue(self, task): ...
66
    def dequeue(self): ...
67
    def pending_count(self): ...
68
    def flush(self): ...
69
```
70

71
[Core Task Queue](./core-task-queue.md)
72

73
### Task Scheduling and Periodic Tasks
74

75
Advanced scheduling capabilities including delayed execution, periodic tasks with cron-like syntax, and task pipeline management.
76

77
```python { .api }
78
def periodic_task(self, validate_datetime, retries=0, retry_delay=0,
79
                  priority=None, context=False, name=None, expires=None, **kwargs): ...
80
def crontab(minute='*', hour='*', day='*', month='*', day_of_week='*', strict=False): ...
81
```
82

83
[Scheduling](./scheduling.md)
84

85
### Result Management
86

87
Comprehensive result handling including result storage, retrieval, blocking operations, timeouts, and result groups for batch operations.
88

89
```python { .api }
90
class Result:
91
    def get(self, blocking=False, timeout=None, backoff=1.15, max_delay=1.0,
92
            revoke_on_timeout=False, preserve=False): ...
93
    def is_revoked(self): ...
94
    def revoke(self, revoke_once=True): ...
95
    def reschedule(self, eta=None, delay=None, expires=None, priority=None,
96
                   preserve_pipeline=True): ...
97
```
98

99
[Result Management](./result-management.md)
100

101
### Task Lifecycle and Hooks
102

103
Task lifecycle management including pre/post execution hooks, startup/shutdown hooks, signal handling, and task pipeline chaining.
104

105
```python { .api }
106
def pre_execute(self, name=None): ...
107
def post_execute(self, name=None): ...
108
def on_startup(self, name=None): ...
109
def on_shutdown(self, name=None): ...
110
def signal(self, *signals): ...
111
```
112

113
[Task Lifecycle](./task-lifecycle.md)
114

115
### Storage Backends
116

117
Multiple storage backend implementations with their specific configurations and capabilities for different deployment scenarios.
118

119
```python { .api }
120
class RedisHuey(Huey): ...
121
class SqliteHuey(Huey): ...
122
class MemoryHuey(Huey): ...
123
class FileHuey(Huey): ...
124
class PriorityRedisHuey(Huey): ...
125
```
126

127
[Storage Backends](./storage-backends.md)
128

129
### Task Locking and Concurrency
130

131
Task locking mechanisms, concurrency control, and synchronization features to prevent duplicate task execution and manage shared resources.
132

133
```python { .api }
134
class TaskLock:
135
    def is_locked(self): ...
136
    def clear(self): ...
137
def lock_task(self, lock_name): ...
138
def is_locked(self, lock_name): ...
139
```
140

141
[Locking and Concurrency](./locking-concurrency.md)
142

143
### Exception Handling
144

145
Exception classes for task control flow, error handling, and task execution management.
146

147
```python { .api }
148
class CancelExecution(Exception):
149
    def __init__(self, retry=None, *args, **kwargs): ...
150

151
class RetryTask(Exception):
152
    def __init__(self, msg=None, eta=None, delay=None, *args, **kwargs): ...
153
```
154

155
[Exception Handling](./exception-handling.md)
156

157
## Types
158

159
```python { .api }
160
class Task:
161
    def __init__(self, args=None, kwargs=None, id=None, eta=None, retries=None,
162
                 retry_delay=None, priority=None, expires=None,
163
                 on_complete=None, on_error=None, expires_resolved=None): ...
164
    
165
    @property
166
    def data(self): ...
167
    
168
    def create_id(self): ...
169
    def resolve_expires(self, utc=True): ...
170
    def extend_data(self, data): ...
171
    def execute(self): ...
172
    def then(self, task, *args, **kwargs): ...
173
    def error(self, task, *args, **kwargs): ...
174

175
class TaskWrapper:
176
    def schedule(self, args=None, kwargs=None, eta=None, delay=None,
177
                 priority=None, retries=None, retry_delay=None, expires=None,
178
                 id=None): ...
179
    def map(self, it): ...
180
    def s(self, *args, **kwargs): ...
181
    def call_local(self, *args, **kwargs): ...
182

183
class Consumer:
184
    def __init__(self, huey, workers=1, periodic=True, initial_delay=0.1,
185
                 backoff=1.15, max_delay=10.0, scheduler_interval=1,
186
                 worker_type='thread', check_worker_health=True,
187
                 health_check_interval=10, flush_locks=False,
188
                 extra_locks=None): ...
189
    def start(self): ...
190
    def stop(self, graceful=False): ...
191
    def run(self): ...
192
    def flush_locks(self, *names): ...
193
```