From bec98bff3dabe43024ae1e461ed49401545b6a94 Mon Sep 17 00:00:00 2001 From: Daniel M Date: Thu, 21 Nov 2024 08:02:50 -0500 Subject: [PATCH] docs --- docs/changelog.md | 14 ++++++---- docs/configuration.md | 2 +- docs/index.md | 59 +++++++++++++++++++++++++------------------ docs/installation.md | 2 +- scheduler/queues.py | 2 +- 5 files changed, 46 insertions(+), 33 deletions(-) diff --git a/docs/changelog.md b/docs/changelog.md index c839514..84e0445 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,13 +1,17 @@ # Changelog -## v2.2.0 🌈 +## v3.0.0 🌈 + +### Breaking Changes + +- Renamed `REDIS_CLIENT_KWARGS` configuration to `CLIENT_KWARGS`. ### 🚀 Features -- Created a new `Task` model representing all kind of scheduled tasks. - - In future versions, `CronTask`, `ScheduledTask` and `RepeatableTask` will be removed. - - `Task` model has a `task_type` field to differentiate between the types of tasks. - - Old tasks in the database will be migrated to the new `Task` model automatically. +- Created a new `Task` model representing all kind of scheduled tasks. + - In future versions, `CronTask`, `ScheduledTask` and `RepeatableTask` will be removed. + - `Task` model has a `task_type` field to differentiate between the types of tasks. + - Old tasks in the database will be migrated to the new `Task` model automatically. ## v2.1.1 🌈 diff --git a/docs/configuration.md b/docs/configuration.md index fb05ec8..da5c5a9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -20,7 +20,7 @@ SCHEDULER_QUEUES = { 'USERNAME': 'some-user', 'PASSWORD': 'some-password', 'DEFAULT_TIMEOUT': 360, - 'REDIS_CLIENT_KWARGS': { # Eventual additional Redis connection arguments + 'CLIENT_KWARGS': { # Eventual additional Redis connection arguments 'ssl_cert_reqs': None, }, 'TOKEN_VALIDATION_METHOD': None, # Method to validate auth-header diff --git a/docs/index.md b/docs/index.md index 24f3275..9c35786 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,8 @@ # Django tasks Scheduler -[![Django CI][1]][2] -![badge][3] -[![badge][4]][5] +[![Django CI][badge]][2] +![badge][coverage] +[![badge][pypi-downloads]][pypi] --- @@ -11,6 +11,28 @@ This allows remembering scheduled tasks, their parameters, etc. ## Terminology +### Scheduled Task + +Starting v3.0.0, django-tasks-scheduler is using a single `Task` model with different task types, the task types are: + +- `ONCE` - Run the task once at a scheduled time. +- `REPEATABLE` - Run the task multiple times (limited number of times or infinite times) based on a time interval. +- `CRON` - Run a task indefinitely based on a cron string schedule. + +This enables having one admin view for all scheduled tasks, and having one table in the database to maintain the task +reduces the number of overall queries. +An `Task` instance contains all relevant information about a task to enable the users to schedule using django-admin and +track their status. + +Previously, there were three different models for ScheduledTask. These exist for legacy purposes and are scheduled to +be removed. + +* `Scheduled Task` - Run a task once, on a specific time (can be immediate). +* `Repeatable Task` - Run a task multiple times (limited number of times or infinite times) based on an interval +* `Cron Task` - Run a task multiple times (limited number of times or infinite times) based on a cron string + +Scheduled tasks are scheduled when the django application starts, and after a scheduled task is executed. + ### Queue A queue of messages between processes (main django-app process and worker usually). @@ -34,7 +56,7 @@ This is a subprocess of worker. Once a worker listening to the queue becomes available, the job will be executed -### Scheduled Task Execution +### Scheduled Job Execution A scheduler checking the queue periodically will check whether the time the job should be executed has come, and if so, it will queue it. @@ -42,19 +64,6 @@ it will queue it. * A job is considered scheduled if it is queued to be executed, or scheduled to be executed. * If there is no scheduler, the job will not be queued to run. -### Scheduled Task - -django models storing information about jobs. So it is possible to schedule using -django-admin and track their status. - -There are three types of ScheduledTask. - -* `Scheduled Task` - Run a job once, on a specific time (can be immediate). -* `Repeatable Task` - Run a job multiple times (limited number of times or infinite times) based on an interval -* `Cron Task` - Run a job multiple times (limited number of times or infinite times) based on a cron string - -Scheduled jobs are scheduled when the django application starts, and after a scheduled task is executed. - ## Scheduler sequence diagram ```mermaid @@ -121,24 +130,24 @@ sequenceDiagram ## Reporting issues or Features requests -Please report issues via [GitHub Issues][6] . +Please report issues via [GitHub Issues][issues] . --- ## Acknowledgements -A lot of django-admin views and their tests were adopted from [django-rq][7]. +A lot of django-admin views and their tests were adopted from [django-rq][django-rq]. -[1]:https://github.com/django-commons/django-tasks-scheduler/actions/workflows/test.yml/badge.svg +[badge]:https://github.com/django-commons/django-tasks-scheduler/actions/workflows/test.yml/badge.svg [2]:https://github.com/django-commons/django-tasks-scheduler/actions/workflows/test.yml -[3]:https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/cunla/b756396efb895f0e34558c980f1ca0c7/raw/django-tasks-scheduler-4.json +[coverage]:https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/cunla/b756396efb895f0e34558c980f1ca0c7/raw/django-tasks-scheduler-4.json -[4]:https://img.shields.io/pypi/dm/django-tasks-scheduler +[pypi-downloads]:https://img.shields.io/pypi/dm/django-tasks-scheduler -[5]:https://pypi.org/project/django-tasks-scheduler/ +[pypi]:https://pypi.org/project/django-tasks-scheduler/ -[6]:https://github.com/django-commons/django-tasks-scheduler/issues +[issues]:https://github.com/django-commons/django-tasks-scheduler/issues -[7]:https://github.com/rq/django-rq \ No newline at end of file +[django-rq]:https://github.com/rq/django-rq \ No newline at end of file diff --git a/docs/installation.md b/docs/installation.md index 6a2db1d..13573b0 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -26,7 +26,7 @@ 'USERNAME': 'some-user', 'PASSWORD': 'some-password', 'DEFAULT_TIMEOUT': 360, - 'REDIS_CLIENT_KWARGS': { # Eventual additional Redis connection arguments + 'CLIENT_KWARGS': { # Eventual additional Redis connection arguments 'ssl_cert_reqs': None, }, }, diff --git a/scheduler/queues.py b/scheduler/queues.py index df65ce7..15abbd9 100644 --- a/scheduler/queues.py +++ b/scheduler/queues.py @@ -76,7 +76,7 @@ def _get_broker_connection(config, use_strict_broker=False): password=config.get("PASSWORD"), ssl=config.get("SSL", False), ssl_cert_reqs=config.get("SSL_CERT_REQS", "required"), - **config.get("REDIS_CLIENT_KWARGS", {}), + **config.get("CLIENT_KWARGS", {}), )