search

agronholm / apscheduler

Task scheduling library for Python
MIT License
5.93k stars 690 forks source link

Improved documentation around "day_of_week" 0/1 confusion #931

Open charlienewey-odin opened 1 week ago

charlienewey-odin commented 1 week ago

Things to check first

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. 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.

agronholm commented 6 days ago

The 4.0 series of releases already changed 0 to mean Sunday. I could not do that in 3.x since it would have broken backwards compatibility. Do you need a documentation update for the 3.x series then?