Skip to content

Commit

Permalink
docs
Browse files Browse the repository at this point in the history
  • Loading branch information
cunla committed Nov 21, 2024
1 parent 2da0bdf commit bec98bf
Show file tree
Hide file tree
Showing 5 changed files with 46 additions and 33 deletions.
14 changes: 9 additions & 5 deletions docs/changelog.md
Original file line number Diff line number Diff line change
@@ -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 🌈

Expand Down
2 changes: 1 addition & 1 deletion docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
59 changes: 34 additions & 25 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -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]

---

Expand All @@ -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).
Expand All @@ -34,27 +56,14 @@ 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.

* 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
Expand Down Expand Up @@ -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
[django-rq]:https://github.com/rq/django-rq
2 changes: 1 addition & 1 deletion docs/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
},
},
Expand Down
2 changes: 1 addition & 1 deletion scheduler/queues.py
Original file line number Diff line number Diff line change
Expand Up @@ -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", {}),
)


Expand Down

0 comments on commit bec98bf

Please sign in to comment.