pass day_or croniter argument to CronClock & CronSchedule

[sp1thas]

Summary

The purpose of this PR is to allow to day_or croniter on CronClock and CronSchedule instantiation.

Changes

This PR changes the CronClockSchema and CronScheduleSchema by adding the new day_or field. day_or has been added to CronClock.__init__ and CronSchedule. Some tests for have also been added.

Importance

This change makes every cron clock more configurable, therefore, the whole procedure of scheduling can become more flexible.

This PR was inspired by the following case:

Let's suppose that we have a scheduler with multiple clocks. We want to add a clock that creates events every first Thursday of the month, this periodicity can be achived by this cron: 0 0 1-7 * 4.

Unfortunately, this cron will not work out of the box:

>>> import datetime
>>> import croniter
>>> cron = croniter.croniter('0 0 1-7 * 4')
>>> cron.get_next(datetime.datetime)
datetime.datetime(2020, 11, 1, 0, 0)
>>> cron.get_next(datetime.datetime)
datetime.datetime(2020, 11, 2, 0, 0)
>>> cron.get_next(datetime.datetime)
datetime.datetime(2020, 11, 3, 0, 0)

because of legacy/problematic behavior: so link.

To fix this issue, day_or=False should be pass on initialization.

>>> cron = croniter.croniter('0 0 1-7 * 4', day_or=False)
>>> cron.get_next(datetime.datetime)
datetime.datetime(2020, 11, 5, 0, 0)
>>> cron.get_next(datetime.datetime)
datetime.datetime(2020, 12, 3, 0, 0)

Checklist

This PR:

• adds new tests (if appropriate)
• adds a change file in the changes/ directory (if appropriate)
• updates docstrings for any new functions or function arguments, including docs/outline.toml for API reference docs (if appropriate)

[jcrist]

Thanks @sp1thas. Looking at the croniter docs, it looks like the only kwarg to croniter that it makes sense for us to expose is day_or - perhaps adding that as a top-level kwarg to CronClock/CronSchedule would make more sense than exposing all of cron-iter's kwargs?

Other than that, this seems fine to me. cc'ing @cicdw for a 2nd glance-over just to be sure (schedules also need to be supported by cloud, so there's some extra nuance here when making changes to them).

[cicdw]

Yup this can be supportable by Cloud (once the serializer changes have been released) with no additional work needed as all of the work is handled by the (de)serialization of the schedule / clock itself.

I think I agree with you @jcrist that day_or might be better than general kwargs; if they ever introduce new kwargs it could cause confusion between the version of croniter running in Cloud vs locally so an explicit list seems better (and allows people to discover the functionality easier).

[codecov]

Codecov Report

Merging #3612 into master will increase coverage by 0.01%.
The diff coverage is 100.00%.

[jcrist]

Thanks! This looks good to me.