{ "info": { "author": "Cory Zue", "author_email": "cory@coryzue.com", "bugtrack_url": null, "classifiers": [ "Environment :: Web Environment", "Framework :: Django", "Framework :: Django :: 1.11", "Framework :: Django :: 2.0", "Intended Audience :: Developers", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Topic :: Internet :: WWW/HTTP", "Topic :: Internet :: WWW/HTTP :: Dynamic Content" ], "description": "# Celery Progress Bars for Django\n\nDrop in, dependency-free progress bars for your Django/Celery applications.\n\nSuper simple setup. Lots of customization available.\n\n## Demo\n\n[Celery Progress Bar demo on Build With Django](https://buildwithdjango.com/projects/celery-progress/)\n\n### Github demo application: build a download progress bar for Django\nStarting 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!\n\n## Installation\n\nIf 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).\n\nThen install this library:\n\n```bash\npip install celery-progress\n```\n\n## Usage\n\n### Prerequisites\n\nFirst add `celery_progress` to your `INSTALLED_APPS` in `settings.py`.\n\nThen add the following url config to your main `urls.py`:\n\n```python\nfrom django.urls import re_path, include\nre_path(r'^celery-progress/', include('celery_progress.urls')), # the endpoint is configurable\n```\n\n### Recording Progress\n\nIn your task you should add something like this:\n\n```python\nfrom celery import shared_task\nfrom celery_progress.backend import ProgressRecorder\nimport time\n\n@shared_task(bind=True)\ndef my_task(self, seconds):\n progress_recorder = ProgressRecorder(self)\n result = 0\n for i in range(seconds):\n time.sleep(1)\n result += i\n progress_recorder.set_progress(i + 1, seconds)\n return result\n```\n\nYou can add an optional progress description like this:\n\n```python\n progress_recorder.set_progress(i + 1, seconds, description='my progress description')\n```\n\n### Displaying progress\n\nIn the view where you call the task you need to get the task ID like so:\n\n**views.py**\n```python\ndef progress_view(request):\n result = my_task.delay(10)\n return render(request, 'display_progress.html', context={'task_id': result.task_id})\n```\n\nThen in the page you want to show the progress bar you just do the following.\n\n#### Add the following HTML wherever you want your progress bar to appear:\n\n**display_progress.html**\n```html\n
').text('Sum of all seconds is ' + result)\n );\n}\n\n$(function () {\n CeleryProgressBar.initProgressBar(progressUrl, {\n onResult: customResult,\n })\n});\n```\n\n## Customization\n\nThe `initProgressBar` function takes an optional object of options. The following options are supported:\n\n| Option | What it does | Default Value |\n|--------|--------------|---------------|\n| pollInterval | How frequently to poll for progress (in milliseconds) | 500 |\n| progressBarId | Override the ID used for the progress bar | 'progress-bar' |\n| progressBarMessageId | Override the ID used for the progress bar message | 'progress-bar-message' |\n| progressBarElement | Override the *element* used for the progress bar. If specified, progressBarId will be ignored. | document.getElementById(progressBarId) |\n| progressBarMessageElement | Override the *element* used for the progress bar message. If specified, progressBarMessageId will be ignored. | document.getElementById(progressBarMessageId) |\n| resultElementId | Override the ID used for the result | 'celery-result' |\n| resultElement | Override the *element* used for the result. If specified, resultElementId will be ignored. | document.getElementById(resultElementId) |\n| onProgress | function to call when progress is updated | onProgressDefault |\n| onSuccess | function to call when progress successfully completes | onSuccessDefault |\n| onError | function to call on a known error with no specified handler | onErrorDefault |\n| onRetry | function to call when a task attempts to retry | onRetryDefault |\n| onIgnored | function to call when a task result is ignored | onIgnoredDefault |\n| onTaskError | function to call when progress completes with an error | onError |\n| onNetworkError | function to call on a network error (ignored by WebSocket) | onError |\n| onHttpError | function to call on a non-200 response (ignored by WebSocket) | onError |\n| onDataError | function to call on a response that's not JSON or has invalid schema due to a programming error | onError |\n| onResult | function to call when returned non empty result | CeleryProgressBar.onResultDefault |\n| barColors | dictionary containing color values for various progress bar states. Colors that are not specified will defer to defaults | barColorsDefault |\n| defaultMessages | dictionary containing default messages that can be overridden | see below |\n\nThe `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.\n\n| State | Hex Code | Image Color | \n|-------|----------|:-------------:|\n| success | #76ce60 |  |\n| error | #dc4f63 |  |\n| progress | #68a9ef |  |\n| ignored | #7a7a7a |  |\n\nThe `defaultMessages` option allows you to override some default messages in the UI. At the moment these are:\n\n| Message Id | When Shown | Default Value |\n|-------|----------|:-------------:|\n| waiting | Task is waiting to start | 'Waiting for task to start...'\n| started | Task has started but reports no progress | 'Task started...'\n\n# WebSocket Support\n\nAdditionally, this library offers WebSocket support using [Django Channels](https://channels.readthedocs.io/en/latest/)\ncourtesy of [EJH2](https://github.com/EJH2/).\n\nA working example project leveraging WebSockets is [available here](https://github.com/EJH2/cp_ws-example).\n\nTo use WebSockets, install with `pip install celery-progress[websockets,redis]` or\n`pip install celery-progress[websockets,rabbitmq]` (depending on broker dependencies).\n\nSee `WebSocketProgressRecorder` and `websockets.js` for details.\n\n# Securing the get_progress endpoint\nBy default, anyone can see the status and result of any task by accessing `/celery-progress/