agronholm / agronholm/apscheduler

Improved documentation around "day_of_week" 0/1 confusion

Ouverte
#931 1 commentaire 4 réactions 0 personnes assignées Voir sur GitHub
enhancement
Langage dominant
Python
Étoiles
7.6k
Forks
783
Merge moyen
4 j 8 h
PR mergées (30 j)
5

Description

### Things to check first

- [X] I have searched the existing issues and didn't find my feature already requested there

### Feature description

I think the `day_of_week` field mapping between days and integers in the `CronTrigger` class is confusing and violates the [principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). The `CronTrigger` is clearly named after the `cron` Unix tool, which, by convention, uses the integer `0` to refer to Sunday - however, the `apscheduler` implementation uses `0` as Monday. This nuance is not very clearly documented and this causes confusion to people migrating from e.g. `cron`.

While the decision to use `0` as Monday is not _strictly_ a bug in itself (although given the choice, I would have taken a different approach when implementing the class), I personally found the documentation to be unclear and the subsequent application behaviour to be confusing. I had to resort to reading the code to validate the `CronTrigger`'s behaviour when I was debugging a task.

I plan to add a PR to improve the docs if I get some time.

### Use case

Having clearer documentation of potential "expectation violations" will help reduce the friction experienced by developers when using the `CronTrigger` class.

Guide de contribution

Ouvrir le guide de contribution

Évaluation

Cette issue n'a pas encore été évaluée.

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.