0
# Utilities
1
2
Utility functions for search, template formatting, and general operations supporting Flower's monitoring and management capabilities.
3
4
## Capabilities
5
6
### Search Utilities
7
8
Advanced search functionality for finding tasks and filtering data.
9
10
```python { .api }
11
def parse_search_terms(raw_search_value):
12
"""
13
Parse search query string into structured search terms.
14
15
Args:
16
raw_search_value (str): Raw search query string
17
18
Returns:
19
list: Parsed search terms with field specifications
20
21
Supports field-specific searches like 'name:my_task state:FAILURE'
22
and general text searches across task content.
23
"""
24
25
def satisfies_search_terms(task, search_terms):
26
"""
27
Check if task matches search criteria.
28
29
Args:
30
task (dict): Task object to check
31
search_terms (list): Parsed search terms
32
33
Returns:
34
bool: True if task matches all search terms
35
"""
36
37
def stringified_dict_contains_value(key, value, str_dict):
38
"""
39
Search for value in stringified dictionary.
40
41
Args:
42
key (str): Dictionary key to search
43
value (str): Value to find
44
str_dict (str): Stringified dictionary content
45
46
Returns:
47
bool: True if value found in specified key
48
"""
49
50
def preprocess_search_value(raw_value):
51
"""
52
Clean and normalize search values.
53
54
Args:
55
raw_value (str): Raw search value
56
57
Returns:
58
str: Cleaned search value
59
"""
60
61
def task_args_contains_search_args(task_args, search_args):
62
"""
63
Check if task arguments contain search terms.
64
65
Args:
66
task_args (list): Task arguments to search
67
search_args (list): Search terms to find
68
69
Returns:
70
bool: True if arguments contain search terms
71
"""
72
```
73
74
### Template Utilities
75
76
Formatting and display utilities for the web interface.
77
78
```python { .api }
79
def format_time(time, tz):
80
"""
81
Format timestamp with timezone.
82
83
Args:
84
time (float): Unix timestamp
85
tz (str): Timezone identifier
86
87
Returns:
88
str: Formatted time string
89
"""
90
91
def humanize(obj, type, length):
92
"""
93
Humanize various object types for display.
94
95
Args:
96
obj: Object to humanize
97
type (str): Object type hint
98
length (int): Maximum display length
99
100
Returns:
101
str: Human-readable representation
102
"""
103
104
# Template constants
105
KEYWORDS_UP = ['PENDING', 'SUCCESS', 'FAILURE', 'RETRY', 'REVOKED']
106
KEYWORDS_DOWN = ['null', 'none', 'undefined']
107
UUID_REGEX = r'[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
108
```
109
110
### General Utilities
111
112
Common utility functions for configuration and operations.
113
114
```python { .api }
115
def gen_cookie_secret():
116
"""
117
Generate secure cookie secret.
118
119
Returns:
120
str: Base64-encoded random secret suitable for cookies
121
"""
122
123
def bugreport(app):
124
"""
125
Generate bug report information.
126
127
Args:
128
app: Celery application instance
129
130
Returns:
131
str: Formatted bug report with system and configuration info
132
"""
133
134
def abs_path(path):
135
"""
136
Convert relative path to absolute path.
137
138
Args:
139
path (str): File path (relative or absolute)
140
141
Returns:
142
str: Absolute path
143
"""
144
145
def prepend_url(url, prefix):
146
"""
147
Add URL prefix for reverse proxy setups.
148
149
Args:
150
url (str): Original URL
151
prefix (str): URL prefix to prepend
152
153
Returns:
154
str: URL with prefix added
155
"""
156
157
def strtobool(val):
158
"""
159
Convert string to boolean value.
160
161
Args:
162
val (str): String value to convert
163
164
Returns:
165
bool: Boolean representation
166
167
Recognizes: 'true', 'false', 'yes', 'no', '1', '0' (case-insensitive)
168
"""
169
```
170
171
## Usage Examples
172
173
### Search Operations
174
175
```python
176
from flower.utils.search import parse_search_terms, satisfies_search_terms
177
178
# Parse complex search query
179
search_query = "name:my_task state:FAILURE error database"
180
search_terms = parse_search_terms(search_query)
181
182
# Filter tasks based on search
183
matching_tasks = []
184
for task in all_tasks:
185
if satisfies_search_terms(task, search_terms):
186
matching_tasks.append(task)
187
188
# Search in task arguments
189
task_args = [1, 2, "database_connection", {"host": "db.example.com"}]
190
search_args = ["database", "connection"]
191
if task_args_contains_search_args(task_args, search_args):
192
print("Task arguments contain search terms")
193
```
194
195
### Template Formatting
196
197
```python
198
from flower.utils.template import format_time, humanize
199
from datetime import datetime
200
201
# Format timestamp
202
timestamp = datetime.now().timestamp()
203
formatted = format_time(timestamp, 'UTC')
204
print(f"Task received: {formatted}")
205
206
# Humanize objects
207
large_data = {"key": "value"} * 1000
208
humanized = humanize(large_data, 'dict', 100)
209
print(f"Task args: {humanized}")
210
```
211
212
### Configuration Utilities
213
214
```python
215
from flower.utils import gen_cookie_secret, abs_path, strtobool
216
217
# Generate secure cookie secret
218
secret = gen_cookie_secret()
219
print(f"Cookie secret: {secret}")
220
221
# Convert relative paths
222
config_file = abs_path("../config/flower.conf")
223
print(f"Config file: {config_file}")
224
225
# String to boolean conversion
226
debug_mode = strtobool(os.environ.get('DEBUG', 'false'))
227
persistent_storage = strtobool(os.environ.get('PERSISTENT', 'true'))
228
```
229
230
### Bug Reporting
231
232
```python
233
from flower.utils import bugreport
234
235
# Generate bug report
236
report = bugreport(celery_app)
237
print("Bug Report:")
238
print(report)
239
240
# Bug report includes:
241
# - Flower version
242
# - Celery version
243
# - Python version
244
# - Platform information
245
# - Broker configuration
246
# - Registered tasks
247
# - Configuration options
248
```
249
250
## Search Query Syntax
251
252
The search system supports advanced query syntax:
253
254
### Field-Specific Searches
255
```
256
name:my_task # Search in task name
257
state:FAILURE # Filter by task state
258
worker:celery@host1 # Filter by worker
259
uuid:task-id-123 # Search by task ID
260
```
261
262
### Text Searches
263
```
264
database error # Search across all text fields
265
"connection timeout" # Exact phrase search
266
error OR timeout # Boolean OR operation
267
```
268
269
### Combined Searches
270
```
271
name:import_data state:FAILURE database
272
state:SUCCESS runtime:>10
273
worker:celery@worker1 name:process_*
274
```
275
276
## Template Variables
277
278
Template utilities provide variables for web interface templates:
279
280
```python
281
template_vars = {
282
'time_formatter': format_time,
283
'humanizer': humanize,
284
'KEYWORDS_UP': KEYWORDS_UP,
285
'KEYWORDS_DOWN': KEYWORDS_DOWN,
286
'UUID_REGEX': UUID_REGEX,
287
}
288
```
289
290
## Error Handling
291
292
Utilities include robust error handling:
293
294
```python
295
# Safe search term parsing
296
try:
297
terms = parse_search_terms(user_query)
298
except ValueError as e:
299
print(f"Invalid search query: {e}")
300
terms = []
301
302
# Safe boolean conversion
303
try:
304
value = strtobool(env_var)
305
except ValueError:
306
value = False # Default fallback
307
308
# Safe path conversion
309
try:
310
path = abs_path(relative_path)
311
except (OSError, ValueError):
312
path = None # Handle invalid paths
313
```
314
315
## Performance Considerations
316
317
- Search operations can be expensive with large datasets
318
- Use appropriate limits when searching through many tasks
319
- Consider caching formatted values for frequently accessed data
320
- Monitor memory usage with large humanized objects
321
- Pre-compile regex patterns for repeated searches