1Metadata-Version: 2.1 2Name: celery-progress 3Version: 0.1.1 4Summary: Drop in, configurable, dependency-free progress bars for your Django/Celery applications. 5Home-page: https://github.com/czue/celery-progress 6Author: Cory Zue 7Author-email: cory@coryzue.com 8License: MIT License 9Platform: UNKNOWN 10Classifier: Environment :: Web Environment 11Classifier: Framework :: Django 12Classifier: Framework :: Django :: 1.11 13Classifier: Framework :: Django :: 2.0 14Classifier: Intended Audience :: Developers 15Classifier: License :: OSI Approved :: MIT License 16Classifier: Operating System :: OS Independent 17Classifier: Programming Language :: Python 18Classifier: Programming Language :: Python :: 3.5 19Classifier: Programming Language :: Python :: 3.6 20Classifier: Programming Language :: Python :: 3.7 21Classifier: Programming Language :: Python :: 3.8 22Classifier: Programming Language :: Python :: 3.9 23Classifier: Topic :: Internet :: WWW/HTTP 24Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content 25Description-Content-Type: text/markdown 26Provides-Extra: websockets 27Provides-Extra: redis 28Provides-Extra: rabbitmq 29License-File: LICENSE 30 31# Celery Progress Bars for Django 32 33Drop in, dependency-free progress bars for your Django/Celery applications. 34 35Super 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 42Starting 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 46If 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 48Then install this library: 49 50```bash 51pip install celery-progress 52``` 53 54## Usage 55 56### Prerequisites 57 58First add `celery_progress` to your `INSTALLED_APPS` in `settings.py`. 59 60Then add the following url config to your main `urls.py`: 61 62```python 63from django.urls import re_path, include 64re_path(r'^celery-progress/', include('celery_progress.urls')), # the endpoint is configurable 65``` 66 67### Recording Progress 68 69In your task you should add something like this: 70 71```python 72from celery import shared_task 73from celery_progress.backend import ProgressRecorder 74import time 75 76@shared_task(bind=True) 77def 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 87You 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 95In the view where you call the task you need to get the task ID like so: 96 97**views.py** 98```python 99def progress_view(request): 100 result = my_task.delay(10) 101 return render(request, 'display_progress.html', context={'task_id': result.task_id}) 102``` 103 104Then 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%;"> </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 127document.addEventListener("DOMContentLoaded", function () { 128 var progressUrl = "{% url 'celery_progress:task_status' task_id %}"; 129 CeleryProgressBar.initProgressBar(progressUrl); 130}); 131``` 132 133or 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 145If you'd like you can also display the result of your task on the front end. 146 147To do that follow the steps below. Result handling can also be customized. 148 149#### Initialize the result block: 150 151This 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 158But more likely you will want to customize how the result looks, which can be done as below: 159 160```javascript 161// JQuery 162var progressUrl = "{% url 'celery_progress:task_status' task_id %}"; 163 164function 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 179The `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 202The `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 |  | 207| error | #dc4f63 |  | 208| progress | #68a9ef |  | 209| ignored | #7a7a7a |  | 210 211# WebSocket Support 212 213Additionally, this library offers WebSocket support using [Django Channels](https://channels.readthedocs.io/en/latest/) 214courtesy of [EJH2](https://github.com/EJH2/). 215 216A working example project leveraging WebSockets is [available here](https://github.com/EJH2/cp_ws-example). 217 218To use WebSockets, install with `pip install celery-progress[websockets,redis]` or 219`pip install celery-progress[websockets,rabbitmq]` (depending on broker dependencies). 220 221See `WebSocketProgressRecorder` and `websockets.js` for details. 222 223 224