Debian Codegraph @

PKG-INFO

raw
1 Metadata-Version: 2.1
2 Name: celery-progress
3 Version: 0.1.1
4 Summary: Drop in, configurable, dependency-free progress bars for your Django/Celery applications.
5 Home-page: https://github.com/czue/celery-progress
6 Author: Cory Zue
7 Author-email: [email protected]
8 License: MIT License
9 Platform: UNKNOWN
10 Classifier: Environment :: Web Environment
11 Classifier: Framework :: Django
12 Classifier: Framework :: Django :: 1.11
13 Classifier: Framework :: Django :: 2.0
14 Classifier: Intended Audience :: Developers
15 Classifier: License :: OSI Approved :: MIT License
16 Classifier: Operating System :: OS Independent
17 Classifier: Programming Language :: Python
18 Classifier: Programming Language :: Python :: 3.5
19 Classifier: Programming Language :: Python :: 3.6
20 Classifier: Programming Language :: Python :: 3.7
21 Classifier: Programming Language :: Python :: 3.8
22 Classifier: Programming Language :: Python :: 3.9
23 Classifier: Topic :: Internet :: WWW/HTTP
24 Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
25 Description-Content-Type: text/markdown
26 Provides-Extra: websockets
27 Provides-Extra: redis
28 Provides-Extra: rabbitmq
29 License-File: LICENSE
30
31 # Celery Progress Bars for Django
32
33 Drop in, dependency-free progress bars for your Django/Celery applications.
34
35 Super simple setup. Lots of customization available.
36
37 ## Demo
38
39 [Celery Progress Bar demo on Build With Django](https://buildwithdjango.com/projects/celery-progress/)
40
41 ### Github demo application: build a download progress bar for Django
42 Starting with Celery can be challenging, [eeintech](https://github.com/eeintech) built a complete [Django demo application](https://github.com/eeintech/django-celery-progress-demo) along with a [step-by-step guide](https://eeinte.ch/stream/progress-bar-django-using-celery/) to get you started on building your own progress bar!
43
44 ## Installation
45
46 If you haven't already, make sure you have properly [set up celery in your project](https://docs.celeryproject.org/en/stable/getting-started/first-steps-with-celery.html#first-steps).
47
48 Then install this library:
49
50 ```bash
51 pip install celery-progress
52 ```
53
54 ## Usage
55
56 ### Prerequisites
57
58 First add `celery_progress` to your `INSTALLED_APPS` in `settings.py`.
59
60 Then add the following url config to your main `urls.py`:
61
62 ```python
63 from django.urls import re_path, include
64 re_path(r'^celery-progress/', include('celery_progress.urls')), # the endpoint is configurable
65 ```
66
67 ### Recording Progress
68
69 In your task you should add something like this:
70
71 ```python
72 from celery import shared_task
73 from celery_progress.backend import ProgressRecorder
74 import time
75
76 @shared_task(bind=True)
77 def my_task(self, seconds):
78 progress_recorder = ProgressRecorder(self)
79 result = 0
80 for i in range(seconds):
81 time.sleep(1)
82 result += i
83 progress_recorder.set_progress(i + 1, seconds)
84 return result
85 ```
86
87 You can add an optional progress description like this:
88
89 ```python
90 progress_recorder.set_progress(i + 1, seconds, description='my progress description')
91 ```
92
93 ### Displaying progress
94
95 In the view where you call the task you need to get the task ID like so:
96
97 **views.py**
98 ```python
99 def progress_view(request):
100 result = my_task.delay(10)
101 return render(request, 'display_progress.html', context={'task_id': result.task_id})
102 ```
103
104 Then in the page you want to show the progress bar you just do the following.
105
106 #### Add the following HTML wherever you want your progress bar to appear:
107
108 **display_progress.html**
109 ```html
110 <div class='progress-wrapper'>
111 <div id='progress-bar' class='progress-bar' style="background-color: #68a9ef; width: 0%;">&nbsp;</div>
112 </div>
113 <div id="progress-bar-message">Waiting for progress to start...</div>
114 ```
115
116 #### Import the javascript file.
117
118 **display_progress.html**
119 ```html
120 <script src="{% static 'celery_progress/celery_progress.js' %}"></script>
121 ```
122
123 #### Initialize the progress bar:
124
125 ```javascript
126 // vanilla JS version
127 document.addEventListener("DOMContentLoaded", function () {
128 var progressUrl = "{% url 'celery_progress:task_status' task_id %}";
129 CeleryProgressBar.initProgressBar(progressUrl);
130 });
131 ```
132
133 or
134
135 ```javascript
136 // JQuery
137 $(function () {
138 var progressUrl = "{% url 'celery_progress:task_status' task_id %}";
139 CeleryProgressBar.initProgressBar(progressUrl)
140 });
141 ```
142
143 ### Displaying the result of a task
144
145 If you'd like you can also display the result of your task on the front end.
146
147 To do that follow the steps below. Result handling can also be customized.
148
149 #### Initialize the result block:
150
151 This is all that's needed to render the result on the page.
152
153 **display_progress.html**
154 ```html
155 <div id="celery-result"></div>
156 ```
157
158 But more likely you will want to customize how the result looks, which can be done as below:
159
160 ```javascript
161 // JQuery
162 var progressUrl = "{% url 'celery_progress:task_status' task_id %}";
163
164 function customResult(resultElement, result) {
165 $( resultElement ).append(
166 $('<p>').text('Sum of all seconds is ' + result)
167 );
168 }
169
170 $(function () {
171 CeleryProgressBar.initProgressBar(progressUrl, {
172 onResult: customResult,
173 })
174 });
175 ```
176
177 ## Customization
178
179 The `initProgressBar` function takes an optional object of options. The following options are supported:
180
181 | Option | What it does | Default Value |
182 |--------|--------------|---------------|
183 | pollInterval | How frequently to poll for progress (in milliseconds) | 500 |
184 | progressBarId | Override the ID used for the progress bar | 'progress-bar' |
185 | progressBarMessageId | Override the ID used for the progress bar message | 'progress-bar-message' |
186 | progressBarElement | Override the *element* used for the progress bar. If specified, progressBarId will be ignored. | document.getElementById(progressBarId) |
187 | progressBarMessageElement | Override the *element* used for the progress bar message. If specified, progressBarMessageId will be ignored. | document.getElementById(progressBarMessageId) |
188 | resultElementId | Override the ID used for the result | 'celery-result' |
189 | resultElement | Override the *element* used for the result. If specified, resultElementId will be ignored. | document.getElementById(resultElementId) |
190 | onProgress | function to call when progress is updated | onProgressDefault |
191 | onSuccess | function to call when progress successfully completes | onSuccessDefault |
192 | onError | function to call on a known error with no specified handler | onErrorDefault |
193 | onRetry | function to call when a task attempts to retry | onRetryDefault |
194 | onIgnored | function to call when a task result is ignored | onIgnoredDefault |
195 | onTaskError | function to call when progress completes with an error | onError |
196 | onNetworkError | function to call on a network error (ignored by WebSocket) | onError |
197 | onHttpError | function to call on a non-200 response (ignored by WebSocket) | onError |
198 | onDataError | function to call on a response that's not JSON or has invalid schema due to a programming error | onError |
199 | onResult | function to call when returned non empty result | CeleryProgressBar.onResultDefault |
200 | barColors | dictionary containing color values for various progress bar states. Colors that are not specified will defer to defaults | barColorsDefault |
201
202 The `barColors` option allows you to customize the color of each progress bar state by passing a dictionary of key-value pairs of `state: #hexcode`. The defaults are shown below.
203
204 | State | Hex Code | Image Color |
205 |-------|----------|:-------------:|
206 | success | #76ce60 | ![#76ce60](https://placehold.it/15/76ce60/000000?text=+) |
207 | error | #dc4f63 | ![#dc4f63](https://placehold.it/15/dc4f63/000000?text=+) |
208 | progress | #68a9ef | ![#68a9ef](https://placehold.it/15/68a9ef/000000?text=+) |
209 | ignored | #7a7a7a | ![#7a7a7a](https://placehold.it/15/7a7a7a/000000?text=+) |
210
211 # WebSocket Support
212
213 Additionally, this library offers WebSocket support using [Django Channels](https://channels.readthedocs.io/en/latest/)
214 courtesy of [EJH2](https://github.com/EJH2/).
215
216 A working example project leveraging WebSockets is [available here](https://github.com/EJH2/cp_ws-example).
217
218 To use WebSockets, install with `pip install celery-progress[websockets,redis]` or
219 `pip install celery-progress[websockets,rabbitmq]` (depending on broker dependencies).
220
221 See `WebSocketProgressRecorder` and `websockets.js` for details.
222
223