agronholm / agronholm/apscheduler
Improved documentation around "day_of_week" 0/1 confusion
- Vorherrschende Sprache
- Python
- Sterne
- 7.6k
- Forks
- 783
- Ø Merge
- 4 T. 8 Std.
- Gemergte PRs (30 T.)
- 5
Beschreibung
### 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.
Beitragsleitfaden
Bewertung
Dieses Issue wurde noch nicht bewertet.