# Gonk
## Setup
### Install the library:
```bash
pip install gonk
```
You can add contribution add-ons:
For Mercure support:
```shell
pip install gonk[mercure]
```
For Django Rest Framework support:
```shell
pip install gonk[drf]
```
Or both of them:
```shell
pip install gonk[drf,mercure]
```
### Add the application to `INSTALLED_APPS` in Django `settings`:
```python
INSTALLED_APPS = [
# ...
'gonk',
]
```
### Launch migrations:
```bash
python manage.py migrate
```
## Usage
### Create taskrunner
```python
# taskrunners.py
from gonk.taskrunners import TaskRunner
from gonk.decorators import register, register_beat
from celery.schedules import crontab
# Register taskrunner
@register('my_taskrunner')
class MyTaskRunner(TaskRunner):
def revert(self):
# Specific implementation
def run(self):
# Specific implementation
# Register scheduled taskrunner
@register_beat('scheduled_taskrunner', crontab(minute='*'))
class ScheduledTaskRunner(TaskRunner):
def revert(self):
# Specific implementation
def run(self):
# Specific implementation
```
We have to import the taskrunner within every app.
The best way to do so is in `apps.py`
```python
class MyAppConfig(AppConfig):
# ...
def ready(self):
from . import taskrunners
```
### Launch task
```python
from gonk.tasks import Task
args = {}
Task.create_task('my_taskrunner', args)
```
### Revert task
```python
from gonk.tasks import Task
t = Task.objects.last()
t.revert()
```
### Cancel task
```python
from gonk.tasks import Task
t = Task.objects.last()
terminate: bool = False
t.cancel(terminate=terminate)
```
### Checkpoints
You can add checkpoints to register transcendent events within the task. Every checkpoint can send a notification
to the user to get feedback of the status and progress of the task.
```python
# taskrunners.py
from gonk.taskrunners import TaskRunner
class MyTaskRunner(TaskRunner):
def run(self):
# Specific implementation
self.task.log_status('STARTED', checkpoint=False)
self.task.log_status('Checkpoint 1', checkpoint=True)
self.task.log_status('FINISHED')
```
### Command to list registered taskrunners
We can list the registered taskrunner with the command `list_taskrunners`.
```bash
python manage.py list_taskrunners
```
### Command to launch tasks manually
We can create tasks using the command `create_tasks`.
```bash
python manage.py create_task --help
usage: manage.py create_task [-h] [--input INPUT] [--raw-input RAW_INPUT] [--queue QUEUE] [--when WHEN] [--version] [-v {0,1,2,3}] [--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color]
[--skip-checks]
task_type
positional arguments:
task_type Task type identifier
options:
-h, --help show this help message and exit
--input INPUT File input -- can be redirected from standard output
--raw-input RAW_INPUT
Raw string input -- Must be in json format
--queue QUEUE Celery queue name in which the task will be run
--when WHEN Scheduled task run date -- ISO Format
```
**Examples:**
```bash
python manage.py create_task <task_type> --raw-input='{}'
cat file.json | python manage.py create_task <task_type> --queue="celery" --input -
```
## Setup
| Environment variable | Type | Description |
| -------- | ----------- | ----------- |
| KEEP_TASK_HISTORY_DAYS | int | Number of days to keep the tasks |
| DEFAULT_NOTIFICATION_EMAIL | str | Default e-mail to notify |
## Django Rest Framework
> To use Django Rest Framework extension we have to install with the `drf` extra.
In our project `urls.py` we have to add the Gonk urls:
```python
from django.urls import path, include
urlpatterns = [
# ...
path('tasks/', include('gonk.contrib.rest_framework.urls')),
]
```
## Notifications with Mercure
> To use Mercure extension we have to install with the `mercure` extra.
To send notifications with Mercure we have to setup the following environment variables:
| Variable | Type | Description |
| -------- | ----------- | ----------- |
| MERCURE_HUB_URL | str | Mercure service URL |
| MERCURE_JWT_KEY | str | Mercure's JWT Token to publish events |
```python
# taskrunners.py
from gonk.taskrunners import TaskRunner
from gonk.contrib.notifications.mercure import MercureNotificationMixin
class MyTaskRunner(MercureNotificationMixin, TaskRunner):
# Specific implementation
```
## Development
### Clone repository
```bash
git clone git@github.com:kasfactory/gonk.git && cd gonk
```
### Install poetry
```bash
pip install poetry
```
### Install dependencies
```bash
poetry install
```
### Run docker-compose
```bash
docker-compose up -d
```
### Launch celery worker
```bash
poetry run celery -A test_app worker
```
### Launch celery beat
```bash
poetry run celery -A test_app beat
```
> At this point, we have to ensure that `gonk.tasks.to_run`, `gonk.tasks.to_revert` and
> `gonk.tasks.to_schedule` tasks are detected
## Credits
### Authors
- [Francisco Javier LendÃnez](https://github.com/FJLendinez/)
- [Pablo Moreno](https://github.com/pablo-moreno/)
Raw data
{
"_id": null,
"home_page": "https://github.com/kasfactory/gonk",
"name": "gonk",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "celery,tasks",
"author": "Francisco Javier Lendinez Tirado",
"author_email": "lendinez@kasfactory.net",
"download_url": "https://files.pythonhosted.org/packages/a5/46/caf8bcb600fd76c3463bce59e4a1609ee47277f101e5160c5844719384fb/gonk-0.5.4.tar.gz",
"platform": null,
"description": "# Gonk\n\n![gonk](https://c.tenor.com/T0z4i7XQhUkAAAAd/gonk-gonk-droid.gif \"Gonk\")\n\n## Setup\n\n### Install the library:\n\n```bash\npip install gonk\n```\n\nYou can add contribution add-ons:\n\nFor Mercure support:\n\n```shell\npip install gonk[mercure]\n```\n\nFor Django Rest Framework support:\n\n```shell\npip install gonk[drf]\n```\n\nOr both of them:\n\n```shell\npip install gonk[drf,mercure]\n```\n\n### Add the application to `INSTALLED_APPS` in Django `settings`:\n\n```python\nINSTALLED_APPS = [\n # ...\n 'gonk',\n]\n```\n\n### Launch migrations:\n\n```bash\npython manage.py migrate\n```\n\n## Usage\n\n### Create taskrunner\n\n```python\n# taskrunners.py\nfrom gonk.taskrunners import TaskRunner\nfrom gonk.decorators import register, register_beat\nfrom celery.schedules import crontab\n\n\n# Register taskrunner\n@register('my_taskrunner')\nclass MyTaskRunner(TaskRunner):\n def revert(self):\n # Specific implementation\n \n def run(self):\n # Specific implementation\n\n\n# Register scheduled taskrunner\n@register_beat('scheduled_taskrunner', crontab(minute='*'))\nclass ScheduledTaskRunner(TaskRunner):\n def revert(self):\n # Specific implementation\n \n def run(self):\n # Specific implementation\n```\n\nWe have to import the taskrunner within every app.\nThe best way to do so is in `apps.py`\n\n```python\nclass MyAppConfig(AppConfig):\n # ...\n\n def ready(self):\n from . import taskrunners\n```\n\n\n### Launch task\n\n```python\nfrom gonk.tasks import Task\n\nargs = {}\nTask.create_task('my_taskrunner', args)\n```\n\n### Revert task\n\n```python\nfrom gonk.tasks import Task\n\nt = Task.objects.last()\nt.revert()\n```\n\n### Cancel task\n\n```python\nfrom gonk.tasks import Task\n\nt = Task.objects.last()\nterminate: bool = False\nt.cancel(terminate=terminate)\n```\n\n### Checkpoints\n\nYou can add checkpoints to register transcendent events within the task. Every checkpoint can send a notification\nto the user to get feedback of the status and progress of the task.\n\n```python\n# taskrunners.py\nfrom gonk.taskrunners import TaskRunner\n\n\nclass MyTaskRunner(TaskRunner):\n def run(self):\n # Specific implementation\n self.task.log_status('STARTED', checkpoint=False)\n self.task.log_status('Checkpoint 1', checkpoint=True)\n self.task.log_status('FINISHED')\n```\n\n### Command to list registered taskrunners\n\nWe can list the registered taskrunner with the command `list_taskrunners`.\n\n```bash\npython manage.py list_taskrunners\n```\n\n### Command to launch tasks manually\n\nWe can create tasks using the command `create_tasks`.\n\n```bash\npython manage.py create_task --help\nusage: manage.py create_task [-h] [--input INPUT] [--raw-input RAW_INPUT] [--queue QUEUE] [--when WHEN] [--version] [-v {0,1,2,3}] [--settings SETTINGS] [--pythonpath PYTHONPATH] [--traceback] [--no-color] [--force-color]\n [--skip-checks]\n task_type\n\npositional arguments:\n task_type Task type identifier\n\noptions:\n -h, --help show this help message and exit\n --input INPUT File input -- can be redirected from standard output\n --raw-input RAW_INPUT\n Raw string input -- Must be in json format\n --queue QUEUE Celery queue name in which the task will be run\n --when WHEN Scheduled task run date -- ISO Format\n\n```\n\n**Examples:**\n\n```bash\npython manage.py create_task <task_type> --raw-input='{}'\ncat file.json | python manage.py create_task <task_type> --queue=\"celery\" --input -\n```\n\n## Setup\n\n| Environment variable | Type | Description |\n| -------- | ----------- | ----------- |\n| KEEP_TASK_HISTORY_DAYS | int | Number of days to keep the tasks |\n| DEFAULT_NOTIFICATION_EMAIL | str | Default e-mail to notify |\n\n## Django Rest Framework\n\n> To use Django Rest Framework extension we have to install with the `drf` extra. \n\nIn our project `urls.py` we have to add the Gonk urls:\n\n```python\nfrom django.urls import path, include\n\nurlpatterns = [\n # ...\n path('tasks/', include('gonk.contrib.rest_framework.urls')),\n]\n```\n\n## Notifications with Mercure\n\n> To use Mercure extension we have to install with the `mercure` extra. \n\n\nTo send notifications with Mercure we have to setup the following environment variables:\n\n| Variable | Type | Description |\n| -------- | ----------- | ----------- |\n| MERCURE_HUB_URL | str | Mercure service URL |\n| MERCURE_JWT_KEY | str | Mercure's JWT Token to publish events |\n\n```python\n# taskrunners.py\nfrom gonk.taskrunners import TaskRunner\nfrom gonk.contrib.notifications.mercure import MercureNotificationMixin\n\n\nclass MyTaskRunner(MercureNotificationMixin, TaskRunner):\n # Specific implementation\n\n```\n\n## Development\n\n### Clone repository\n```bash\ngit clone git@github.com:kasfactory/gonk.git && cd gonk\n```\n\n### Install poetry\n\n```bash\npip install poetry\n```\n\n### Install dependencies\n\n```bash\npoetry install\n```\n\n### Run docker-compose\n\n```bash\ndocker-compose up -d\n```\n\n### Launch celery worker\n\n```bash\npoetry run celery -A test_app worker\n```\n\n### Launch celery beat\n\n```bash\npoetry run celery -A test_app beat\n```\n\n> At this point, we have to ensure that `gonk.tasks.to_run`, `gonk.tasks.to_revert` and \n> `gonk.tasks.to_schedule` tasks are detected\n\n\n## Credits\n\n### Authors\n\n- [Francisco Javier Lend\u00ednez](https://github.com/FJLendinez/)\n- [Pablo Moreno](https://github.com/pablo-moreno/)\n\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Celery tasks for Django made easy",
"version": "0.5.4",
"project_urls": {
"Homepage": "https://github.com/kasfactory/gonk"
},
"split_keywords": [
"celery",
"tasks"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "acfd020082439a34f3e6e20e30af4089ffaf9fbdd7402d4f3885258719bc710b",
"md5": "75b6786fecb567947db53b84d83a8960",
"sha256": "dd06d7fa1fb567c7347cdc51e4a0ca79aa6c1f34dad737d494009925fa55de53"
},
"downloads": -1,
"filename": "gonk-0.5.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "75b6786fecb567947db53b84d83a8960",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 18587,
"upload_time": "2023-09-13T14:33:46",
"upload_time_iso_8601": "2023-09-13T14:33:46.061950Z",
"url": "https://files.pythonhosted.org/packages/ac/fd/020082439a34f3e6e20e30af4089ffaf9fbdd7402d4f3885258719bc710b/gonk-0.5.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a546caf8bcb600fd76c3463bce59e4a1609ee47277f101e5160c5844719384fb",
"md5": "4012ce545301bb6539e2a9fbf1ddac42",
"sha256": "f616d3100daab98c9eb7aa7809a566275970fea7ce2ad1f728db0072efd6399e"
},
"downloads": -1,
"filename": "gonk-0.5.4.tar.gz",
"has_sig": false,
"md5_digest": "4012ce545301bb6539e2a9fbf1ddac42",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 13186,
"upload_time": "2023-09-13T14:33:48",
"upload_time_iso_8601": "2023-09-13T14:33:48.034903Z",
"url": "https://files.pythonhosted.org/packages/a5/46/caf8bcb600fd76c3463bce59e4a1609ee47277f101e5160c5844719384fb/gonk-0.5.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-13 14:33:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kasfactory",
"github_project": "gonk",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gonk"
}
JSON
