agronholm / agronholm/apscheduler
Improved documentation around "day_of_week" 0/1 confusion
- 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.