Django application to manage common django management tasks
*asynchronously*, via the Django admin interface, using [`Redis Queue`](https://github.com/rq/rq).
> **_NOTE:_** Right now, **django-eztaskmanager** is built to play nice with RQ (Redis Queue).
It does the job, and does it well. But I know some of you out there swear by Celery, and I hear you.
It's on my radar and I'm knee-deep in code working to get it integrated.
So, keep an eye out for updates!
**eztaskmanager** is a port and an evolution of our previous
[django-uwsgi-taskmanager](https://github.com/openpolis/django-uwsgi-taskmanager), so thanks to the authors there.
Main **features**:
- use standard django management commands as tasks *templates*,
- import available management commands through a meta-management command, as possible templates for tasks,
- start and stop tasks manually via admin,
- schedule point and periodic tasks via django admin,
- use RQ (rq + rq-scheduler) or Celery (celery + celery-beat) for queue management,
- check or download the generated reports/logs,
- live logs streaming view, with filters on errors and warnings for tasks debugging,
- get notifications via Slack or email when a task succeeds or fails.
See full documentation at http://django-eztaskmanager.rtfd.io/
## Installation
1. Install the app with `pip`:
- via PyPI:
`pip install django-eztaskmanager`
- or via GitHub:
`pip install git+https://github.com/openpolis/django-eztaskmanager.git`
2. Add "eztaskmanager" to your `INSTALLED_APPS` setting like this:
```python
INSTALLED_APPS = [
"django.contrib.admin",
# ...
"eztaskmanager",
]
```
3. Run `python manage.py migrate` to create the taskmanager tables.
4. Run `python manage.py collectcommands --excludecore` to import taskmanager commands.
5. Include the taskmanager URLConf (for the log viewers) in your project `urls.py` like this _(optional)_:
```python
from django.contrib import admin
from django.urls import include, path
urlpatterns = [
path("admin/", admin.site.urls),
path('eztaskmanager/', include('eztaskmanager.urls'))
]
```
6. Set parameters in your settings file as below _(optional)_:
```python
# eztaskmanager
# EZTASKMANAGER_QUEUE_SERVICE_TYPE = 'RQ'
# EZTASKMANAGER_N_LINES_IN_REPORT_LOG = 10
# EZTASKMANAGER_N_REPORTS_INLINE = 10
# EZTASKMANAGER_SHOW_LOGVIEWER_LINK = True
# EZTASKMANAGER_USE_FILTER_COLLAPSE = True
# EZTASKMANAGER_NOTIFICATION_HANDLERS = {}
# EZTASKMANAGER_BASE_URL = None
EZTASKMANAGER_NOTIFICATION_HANDLERS = {
"email-errors": {
"class": "eztaskmanager.services.notifications.EmailNotificationHandler",
"level": "failure",
"from_email": "admin@example.com",
"recipients": ["admin@example.com", ],
},
}
EZTASKMANAGER_N_LINES_IN_REPORT_LOG = 5
```
## Usage
You just need to install `django-eztaskmanager` in your Django Project and run `collectcommands` as described.
Django ezaskmanager will collect all the commands and make them available for asynchronous scheduling in the admin.
If you need a new asynchronous task, just write a standard custom Django command
using `eztaskmanager.services.logger.LogEnabledCommand` in places of `django.core.management.base.BaseCommand`,
and synchronize the app. Then go to the admin page and schedule it.
You can disable commands from the admin, and let users (with limited permissions) schedule only the available ones.
> **NOTE**: RQ or Celery workers and schedulers (rq-scheduler or celery-beat) need to be up and running
## Enabling notifications
To enable Slack notifications support for failing tasks, you have to first install the
required packages, which are not included by default. To do that, just:
pip install django-eztaskmanager[notifications]
This will install the `django-eztaskmanager` package from PyPI, including the optional dependencies
required to make Slack notifications work.
Email notifications are instead handled using Django [`django.core.mail`](https://docs.djangoproject.com/en/5.0/topics/email/)
module, so no further dependencies are needed and they should work out of the box, given you have at
least one [email backend](https://docs.djangoproject.com/en/5.0/topics/email/#email-backends) properly
configured.
Then, you have to configure the following settings:
- `EZTASKMANAGER_NOTIFICATIONS_SLACK_TOKEN`, which must be set with you own Slack token as string.
- `EZTASKMANAGER_NOTIFICATIONS_SLACK_CHANNELS`, a list of strings representing the names or ids of the channels which will receive the notifications.
- `EZTASKMANAGER_NOTIFICATIONS_EMAIL_FROM`, the "from address" you want your outgoing notification emails to use.
- `EZTASKMANAGER_NOTIFICATIONS_EMAIL_RECIPIENTS`, a list of strings representing the recipients of the notifications.
### The demo tutorial (RQ)
Following this tutorial, it will be possible to install, configure and use **eztaskmanager** for a
simple demo django project running in developer mode, with the RQ engine.
Clone the project from github onto your hard disk:
```bash
git clone https://github.com/openpolis/django-eztaskmanager
cd django-eztaskmanager
```
There is a basic Django project under the ``demoproject`` directory, set to use ``eztaskmanager``.
```
demoproject/
├── demoproject/
│ ├── __init__.py
│ └── asgi.py
│ ├── settings.py
│ ├── test_settings.py
│ ├── urls.py
│ └── wsgi.py
├── manage.py
├── static/
└── docker-compose-local.yml
```
#### Try the demo project
As a **pre-requisite**, a Redis server should be up and running on the default port 6379.
Follow the instructions_, or if you use docker_, just run ``docker compose -f docker-compose-local.yml``.
Enter the ``demoproject`` directory, then create and activate the virtual environments:
```bash
$ cd demoproject
$ mkdir -p venv
$ python3 -m venv venv
$ source venv/bin/activate
```
Install **eztaskmanager**, this will install all needed dependencies (django, redis, django-rq, rq-scheduler,...):
```bash
(venv) $ pip install django-eztaskmanager
```
Then execute this commands to setup the server in development mode, the rq worker and the scheduler:
```bash
(venv) $ python manage.py migrate # create tables in the DB (default sqlite will do)
(venv) $ python manage.py createsuperuser # take note of username and password for login
(venv) $ python manage.py collectcommands --excludecore # collect basic commands from the eztaskmanager package
(venv) $ python manage.py runserver # django app server on port 8000
(venv) $ python manage.py rqworker # rq worker to execute enqueued tasks
(venv) $ python manage.py rqscheduler --verbosity=3 # rq scheduler to enqueue periodic tasks
```
Visit http://127.0.0.1:8000/admin/
## Copyright
Django eztaskmanager is an application to manage common django management tasks
*asynchronously*, via the Django admin interface, using Redis Queue.
Copyright (c) 2024 Guglielmo Celata (django-eztaskmanager)
Copyright (C) 2019-2020 Gabriele Giaccari, Gabriele Lucci, Guglielmo Celata, Paolo Melchiorre (django-uwsgi-taskmanager)
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
Raw data
{
"_id": null,
"home_page": "https://github.com/openpolis/django-eztaskmanager.git",
"name": "django-eztaskmanager",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "async, cron, django, commands, manager, queues, task, timer, scheduling, rq, celery",
"author": "Guglielmo Celata",
"author_email": "guglielmo@openpolis.it",
"download_url": "https://files.pythonhosted.org/packages/c9/69/a3575c17b57e8f9481af4cd6f08d525cf44652662cce29ac62e5d7de90b5/django_eztaskmanager-0.3.1.tar.gz",
"platform": null,
"description": "\nDjango application to manage common django management tasks\n*asynchronously*, via the Django admin interface, using [`Redis Queue`](https://github.com/rq/rq).\n\n> **_NOTE:_** Right now, **django-eztaskmanager** is built to play nice with RQ (Redis Queue).\n It does the job, and does it well. But I know some of you out there swear by Celery, and I hear you.\n It's on my radar and I'm knee-deep in code working to get it integrated.\n So, keep an eye out for updates!\n\n**eztaskmanager** is a port and an evolution of our previous \n[django-uwsgi-taskmanager](https://github.com/openpolis/django-uwsgi-taskmanager), so thanks to the authors there.\n\nMain **features**:\n\n- use standard django management commands as tasks *templates*,\n- import available management commands through a meta-management command, as possible templates for tasks,\n- start and stop tasks manually via admin,\n- schedule point and periodic tasks via django admin,\n- use RQ (rq + rq-scheduler) or Celery (celery + celery-beat) for queue management,\n- check or download the generated reports/logs,\n- live logs streaming view, with filters on errors and warnings for tasks debugging,\n- get notifications via Slack or email when a task succeeds or fails.\n\nSee full documentation at http://django-eztaskmanager.rtfd.io/\n\n## Installation\n\n1. Install the app with `pip`:\n\n - via PyPI:\n\n `pip install django-eztaskmanager`\n\n - or via GitHub:\n\n `pip install git+https://github.com/openpolis/django-eztaskmanager.git`\n\n2. Add \"eztaskmanager\" to your `INSTALLED_APPS` setting like this:\n\n ```python\n \n INSTALLED_APPS = [\n \"django.contrib.admin\",\n # ...\n \"eztaskmanager\",\n ]\n ```\n\n3. Run `python manage.py migrate` to create the taskmanager tables.\n\n4. Run `python manage.py collectcommands --excludecore` to import taskmanager commands.\n\n5. Include the taskmanager URLConf (for the log viewers) in your project `urls.py` like this _(optional)_:\n\n ```python\n\n from django.contrib import admin\n from django.urls import include, path\n \n urlpatterns = [\n path(\"admin/\", admin.site.urls),\n path('eztaskmanager/', include('eztaskmanager.urls'))\n ]\n ```\n\n6. Set parameters in your settings file as below _(optional)_:\n\n ```python\n\n # eztaskmanager\n # EZTASKMANAGER_QUEUE_SERVICE_TYPE = 'RQ'\n # EZTASKMANAGER_N_LINES_IN_REPORT_LOG = 10\n # EZTASKMANAGER_N_REPORTS_INLINE = 10\n # EZTASKMANAGER_SHOW_LOGVIEWER_LINK = True\n # EZTASKMANAGER_USE_FILTER_COLLAPSE = True\n # EZTASKMANAGER_NOTIFICATION_HANDLERS = {}\n # EZTASKMANAGER_BASE_URL = None\n EZTASKMANAGER_NOTIFICATION_HANDLERS = {\n \"email-errors\": {\n \"class\": \"eztaskmanager.services.notifications.EmailNotificationHandler\",\n \"level\": \"failure\",\n \"from_email\": \"admin@example.com\",\n \"recipients\": [\"admin@example.com\", ],\n },\n }\n EZTASKMANAGER_N_LINES_IN_REPORT_LOG = 5\n ```\n\n## Usage\n\nYou just need to install `django-eztaskmanager` in your Django Project and run `collectcommands` as described.\nDjango ezaskmanager will collect all the commands and make them available for asynchronous scheduling in the admin.\n\nIf you need a new asynchronous task, just write a standard custom Django command \nusing `eztaskmanager.services.logger.LogEnabledCommand` in places of `django.core.management.base.BaseCommand`, \nand synchronize the app. Then go to the admin page and schedule it.\n\nYou can disable commands from the admin, and let users (with limited permissions) schedule only the available ones.\n\n> **NOTE**: RQ or Celery workers and schedulers (rq-scheduler or celery-beat) need to be up and running\n\n## Enabling notifications\n\nTo enable Slack notifications support for failing tasks, you have to first install the\nrequired packages, which are not included by default. To do that, just:\n\n pip install django-eztaskmanager[notifications]\n \nThis will install the `django-eztaskmanager` package from PyPI, including the optional dependencies\nrequired to make Slack notifications work. \n\nEmail notifications are instead handled using Django [`django.core.mail`](https://docs.djangoproject.com/en/5.0/topics/email/) \nmodule, so no further dependencies are needed and they should work out of the box, given you have at\nleast one [email backend](https://docs.djangoproject.com/en/5.0/topics/email/#email-backends) properly\nconfigured.\n\nThen, you have to configure the following settings:\n\n- `EZTASKMANAGER_NOTIFICATIONS_SLACK_TOKEN`, which must be set with you own Slack token as string.\n- `EZTASKMANAGER_NOTIFICATIONS_SLACK_CHANNELS`, a list of strings representing the names or ids of the channels which will receive the notifications.\n- `EZTASKMANAGER_NOTIFICATIONS_EMAIL_FROM`, the \"from address\" you want your outgoing notification emails to use.\n- `EZTASKMANAGER_NOTIFICATIONS_EMAIL_RECIPIENTS`, a list of strings representing the recipients of the notifications.\n\n### The demo tutorial (RQ)\nFollowing this tutorial, it will be possible to install, configure and use **eztaskmanager** for a\nsimple demo django project running in developer mode, with the RQ engine.\n\nClone the project from github onto your hard disk:\n\n```bash\n git clone https://github.com/openpolis/django-eztaskmanager\n cd django-eztaskmanager\n```\n\nThere is a basic Django project under the ``demoproject`` directory, set to use ``eztaskmanager``.\n\n```\n demoproject/\n \u251c\u2500\u2500 demoproject/\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 __init__.py\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 asgi.py\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 settings.py\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 test_settings.py\n \u2502\u00a0\u00a0 \u251c\u2500\u2500 urls.py\n \u2502\u00a0\u00a0 \u2514\u2500\u2500 wsgi.py\n \u251c\u2500\u2500 manage.py\n \u251c\u2500\u2500 static/\n \u2514\u2500\u2500 docker-compose-local.yml\n```\n\n#### Try the demo project\n\nAs a **pre-requisite**, a Redis server should be up and running on the default port 6379.\nFollow the instructions_, or if you use docker_, just run ``docker compose -f docker-compose-local.yml``.\n\nEnter the ``demoproject`` directory, then create and activate the virtual environments:\n\n```bash\n $ cd demoproject\n $ mkdir -p venv\n $ python3 -m venv venv\n $ source venv/bin/activate\n```\n\nInstall **eztaskmanager**, this will install all needed dependencies (django, redis, django-rq, rq-scheduler,...):\n\n```bash\n (venv) $ pip install django-eztaskmanager\n```\n\nThen execute this commands to setup the server in development mode, the rq worker and the scheduler:\n\n```bash\n (venv) $ python manage.py migrate # create tables in the DB (default sqlite will do)\n (venv) $ python manage.py createsuperuser # take note of username and password for login\n (venv) $ python manage.py collectcommands --excludecore # collect basic commands from the eztaskmanager package\n (venv) $ python manage.py runserver # django app server on port 8000\n (venv) $ python manage.py rqworker # rq worker to execute enqueued tasks\n (venv) $ python manage.py rqscheduler --verbosity=3 # rq scheduler to enqueue periodic tasks\n```\n\nVisit http://127.0.0.1:8000/admin/\n\n\n## Copyright\n\nDjango eztaskmanager is an application to manage common django management tasks\n*asynchronously*, via the Django admin interface, using Redis Queue.\n\n Copyright (c) 2024 Guglielmo Celata (django-eztaskmanager)\n Copyright (C) 2019-2020 Gabriele Giaccari, Gabriele Lucci, Guglielmo Celata, Paolo Melchiorre (django-uwsgi-taskmanager)\n\n This program is free software: you can redistribute it and/or modify\n it under the terms of the GNU Affero General Public License as\n published by the Free Software Foundation, either version 3 of the\n License, or (at your option) any later version.\n\n This program is distributed in the hope that it will be useful,\n but WITHOUT ANY WARRANTY; without even the implied warranty of\n MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\n GNU Affero General Public License for more details.\n\n You should have received a copy of the GNU Affero General Public License\n along with this program. If not, see <https://www.gnu.org/licenses/>.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django application that allows the management of scheduled, long, asynchronous tasks.",
"version": "0.3.1",
"project_urls": {
"Documentation": "https://django-eztaskmanager.readthedocs.io",
"Homepage": "https://github.com/openpolis/django-eztaskmanager.git",
"Repository": "https://github.com/openpolis/django-eztaskmanager.git"
},
"split_keywords": [
"async",
" cron",
" django",
" commands",
" manager",
" queues",
" task",
" timer",
" scheduling",
" rq",
" celery"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3e9f0d93710d3881a40070e16bdd828d60698a7b2c7621cb2b72557374972574",
"md5": "e5400ff2ac43eb14259b106d93d44ea9",
"sha256": "5e99873e5644db1cb3cd07c936ff77f9ea4cb1798171f360ce7991a5ef5f6723"
},
"downloads": -1,
"filename": "django_eztaskmanager-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e5400ff2ac43eb14259b106d93d44ea9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 172044,
"upload_time": "2024-04-09T14:46:10",
"upload_time_iso_8601": "2024-04-09T14:46:10.020172Z",
"url": "https://files.pythonhosted.org/packages/3e/9f/0d93710d3881a40070e16bdd828d60698a7b2c7621cb2b72557374972574/django_eztaskmanager-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c969a3575c17b57e8f9481af4cd6f08d525cf44652662cce29ac62e5d7de90b5",
"md5": "2daa69e4178a8504ee09503aa7367edb",
"sha256": "dfd0880e3ba479cf0eb4bb093e9d0c874b7c529f7c1df6c632db207a2a574a9e"
},
"downloads": -1,
"filename": "django_eztaskmanager-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "2daa69e4178a8504ee09503aa7367edb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 164843,
"upload_time": "2024-04-09T14:46:11",
"upload_time_iso_8601": "2024-04-09T14:46:11.845604Z",
"url": "https://files.pythonhosted.org/packages/c9/69/a3575c17b57e8f9481af4cd6f08d525cf44652662cce29ac62e5d7de90b5/django_eztaskmanager-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-09 14:46:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "openpolis",
"github_project": "django-eztaskmanager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "django-eztaskmanager"
}
JSON
