Package: pycronius
pycroniusPycronius is a fully-tested, benchmarked utility for efficiently matching datetime objects and cron rules.For example, a business might have various sets of opening and closing hours (e.g. weekday and weekend),
and sets of exceptions to this rule (e.g. holidays).With pycronius we could answer questions such as whether or not the business is open right now,
tomorrow at 9am, Christmas at 4pm, etc.Another perfectly reasonable example is the more traditional crontab, although this was not the original motivation.Why cron strings?Because they are compact, simple, and widely used.Alright, cool, now show me some codefrompycroniusimportSchedulerrules=[("open","* 7-19 * * * *"),("closed","* 0-6 * * * *"),("closed","* 20-23 * * * *")]exceptions=[("closed","* 0-8 * * 6-7 *"),("closed","* 17-23 * * 6-7 *"),("closed","* * 25 12 * *"),("closed","* * 4 7 * *")]scheduler=Scheduler(rules,exceptions,2010,2020)printscheduler.get_matching_rules(datetime(2014,12,19,12,0))# -> ["open"]CronRange stringsAs those familiar with cron strings are already aware, one drawback of cron strings is that they are really
inconvenient for representing periods that begin or end on anything other than exactly the hour.
With the standard cron string this requires defining multiple strings to handle on contiguous block of time.
For example, say our hypothetical business opens at 7:30 and closes at 19:00.  We would need the following strings:("closed", "* 0-6 * * * *")("closed", "0-30 7 * * * *")("open", "30-59 7 * * * *")("open", "* 8-18 * * * *")("closed", "* 19-23 * * * *")Since one of the motivating use cases was managing opening hours, pycronius supports strings where
the first two fields are the start and stop time in HH:MM format, and the last four are in the traditional style.
Now the example above can be represented like this:("closed", "0:00 7:29 * * * *")("open", "7:30 19:00 * * * *")("closed", "19:01 23:59 * * * *")Using these strings requires no additional configuration, and they can be mixed with traditional strings at will.Scheduler DocumentationInitializationTheSchedulerclass takes four parameters:rulesA list of tuples that look like (id (a hashable object), cron string) e.g. (1, "* * * * * *"), where the fields are either
"minute hour day-of-month month day-of-week year" or "start-time stop-time day-of-month month day-of-week year".For traditional cron string, each field is separated by a space, and can consist of either:digit (e.g."12")asterisk (wildcard, e.g."*")Additionally these can be separated by the following in the standard way:"-"(range, inclusive on both end-points, e.g."2000-2020")"/"(interval repetition, e.g. "*/6", or"1-30/2")","(concatenate field defintions, e.g."*/3,*/2")Rules can overlap, which simply means that multiple rules match for a single datetime.
It is up to the user to define the appropriate cron rules for their application.exceptionsTheexceptionsargument has the same type and syntax as therulesargument, however the semantics are different.
These are meant to be exceptions to the rules defined inrules, e.g. the business is closed on Christmas.
If such an exception is defined, then even if the business would normally be open,Scheduler.get_matching_rules()will return closed for any datetime on December 25th.If there are multiple exceptions defined for the same time,Scheduler.get_matching_rules()will return the first
one it encounters, which is not defined.  Unfortunately, the current version of pycronius does not check for overlapping
exceptions, but since this will almost certainly lead to unpredictable behavior, for now, the user is strongly urged
not to define such exceptions.start_yearandstop_yearThese are YYYY format integers, and are used bound the year field for wildcard and wildcard intervals.Every other field has these boundaries pre-defined (e.g. 24 hours per day), however in general, years have
no such boundary, so it is best to define this on a per-application basis.UsageAfter initializing a Scheduler instance, you can get the matching rules for a datetime object withScheduler.get_matching_rules(datetime_object).  This will return a list of ids as defined inrulesandexceptions.  This is a list because it is possible that more than one rule matches a given datetime objectOther considerationsexceptionsthat are defined as all minutes/hours of a certain date (e.g. "* * 4 7 * 2015") are handled in a
special, optimized way.Even with the HH:MM style strings, there are some rule types which pycronius is still pretty bad at modeling,
e.g. third friday of every month.  Luckily it is not so hard to add subclasses ofrules.BasicCronRuleto
handle extra use cases.