| #!/usr/bin/env python |
| # |
| # Copyright 2007 Google Inc. |
| # |
| # Licensed under the Apache License, Version 2.0 (the "License"); |
| # you may not use this file except in compliance with the License. |
| # You may obtain a copy of the License at |
| # |
| # http://www.apache.org/licenses/LICENSE-2.0 |
| # |
| # Unless required by applicable law or agreed to in writing, software |
| # distributed under the License is distributed on an "AS IS" BASIS, |
| # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| # See the License for the specific language governing permissions and |
| # limitations under the License. |
| # |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| """Implementation of scheduling for Groc format schedules. |
| |
| A Groc schedule looks like '1st,2nd monday 9:00', or 'every 20 mins'. This |
| module takes a parsed schedule (produced by Antlr) and creates objects that |
| can produce times that match this schedule. |
| |
| A parsed schedule is one of two types - an Interval or a Specific Time. |
| See the class docstrings for more. |
| |
| Extensions to be considered: |
| |
| allowing a comma separated list of times to run |
| """ |
| |
| |
| |
| import calendar |
| import datetime |
| |
| try: |
| import pytz |
| except ImportError: |
| pytz = None |
| |
| import groc |
| |
| HOURS = 'hours' |
| MINUTES = 'minutes' |
| |
| try: |
| from pytz import NonExistentTimeError |
| from pytz import AmbiguousTimeError |
| except ImportError: |
| |
| class NonExistentTimeError(Exception): |
| pass |
| |
| class AmbiguousTimeError(Exception): |
| pass |
| |
| |
| def GrocTimeSpecification(schedule, timezone=None): |
| """Factory function. |
| |
| Turns a schedule specification into a TimeSpecification. |
| |
| Arguments: |
| schedule: the schedule specification, as a string |
| timezone: the optional timezone as a string for this specification. |
| Defaults to 'UTC' - valid entries are things like 'Australia/Victoria' |
| or 'PST8PDT'. |
| Returns: |
| a TimeSpecification instance |
| """ |
| parser = groc.CreateParser(schedule) |
| parser.timespec() |
| |
| if parser.period_string: |
| return IntervalTimeSpecification(parser.interval_mins, |
| parser.period_string, |
| parser.synchronized, |
| parser.start_time_string, |
| parser.end_time_string, |
| timezone) |
| else: |
| return SpecificTimeSpecification(parser.ordinal_set, parser.weekday_set, |
| parser.month_set, |
| parser.monthday_set, |
| parser.time_string, |
| timezone) |
| |
| |
| class TimeSpecification(object): |
| """Base class for time specifications.""" |
| |
| def GetMatches(self, start, n): |
| """Returns the next n times that match the schedule, starting at time start. |
| |
| Arguments: |
| start: a datetime to start from. Matches will start from after this time. |
| n: the number of matching times to return |
| |
| Returns: |
| a list of n datetime objects |
| """ |
| out = [] |
| for _ in range(n): |
| start = self.GetMatch(start) |
| out.append(start) |
| return out |
| |
| def GetMatch(self, start): |
| """Returns the next match after time start. |
| |
| Must be implemented in subclasses. |
| |
| Arguments: |
| start: a datetime to start from. Matches will start from after this time. |
| This may be in any pytz time zone, or it may be timezone-naive |
| (interpreted as UTC). |
| |
| Returns: |
| a datetime object in the timezone of the input 'start' |
| """ |
| raise NotImplementedError |
| |
| |
| def _GetTimezone(timezone_string): |
| """Converts a timezone string to a pytz timezone object. |
| |
| Arguments: |
| timezone_string: a string representing a timezone, or None |
| |
| Returns: |
| a pytz timezone object, or None if the input timezone_string is None |
| |
| Raises: |
| ValueError: if timezone_string is not None and the pytz module could not be |
| loaded |
| """ |
| if timezone_string: |
| if pytz is None: |
| raise ValueError('need pytz in order to specify a timezone') |
| return pytz.timezone(timezone_string) |
| else: |
| return None |
| |
| |
| def _ToTimeZone(t, tzinfo): |
| """Converts 't' to the time zone 'tzinfo'. |
| |
| Arguments: |
| t: a datetime object. It may be in any pytz time zone, or it may be |
| timezone-naive (interpreted as UTC). |
| tzinfo: a pytz timezone object, or None (interpreted as UTC). |
| |
| Returns: |
| a datetime object in the time zone 'tzinfo' |
| """ |
| if pytz is None: |
| |
| return t.replace(tzinfo=tzinfo) |
| elif tzinfo: |
| |
| if not t.tzinfo: |
| t = pytz.utc.localize(t) |
| return tzinfo.normalize(t.astimezone(tzinfo)) |
| elif t.tzinfo: |
| |
| return pytz.utc.normalize(t.astimezone(pytz.utc)).replace(tzinfo=None) |
| else: |
| |
| return t |
| |
| |
| def _GetTime(time_string): |
| """Converts a string to a datetime.time object. |
| |
| Arguments: |
| time_string: a string representing a time ('hours:minutes') |
| |
| Returns: |
| a datetime.time object |
| """ |
| hourstr, minutestr = time_string.split(':') |
| return datetime.time(int(hourstr), int(minutestr)) |
| |
| |
| class IntervalTimeSpecification(TimeSpecification): |
| """A time specification for a given interval. |
| |
| An Interval type spec runs at the given fixed interval. It has the following |
| attributes: |
| period - the type of interval, either 'hours' or 'minutes' |
| interval - the number of units of type period. |
| synchronized - whether to synchronize the times to be locked to a fixed |
| period (midnight in the specified timezone). |
| start_time, end_time - restrict matches to a given range of times every day. |
| If these are None, there is no restriction. Otherwise, they are |
| datetime.time objects. |
| timezone - the time zone in which start_time and end_time should be |
| interpreted, or None (defaults to UTC). This is a pytz timezone object. |
| """ |
| |
| def __init__(self, interval, period, synchronized=False, |
| start_time_string='', end_time_string='', timezone=None): |
| super(IntervalTimeSpecification, self).__init__() |
| if interval < 1: |
| raise groc.GrocException('interval must be greater than zero') |
| self.interval = interval |
| self.period = period |
| self.synchronized = synchronized |
| if self.period == HOURS: |
| self.seconds = self.interval * 3600 |
| else: |
| self.seconds = self.interval * 60 |
| self.timezone = _GetTimezone(timezone) |
| |
| |
| if self.synchronized: |
| if start_time_string: |
| raise ValueError( |
| 'start_time_string may not be specified if synchronized is true') |
| if end_time_string: |
| raise ValueError( |
| 'end_time_string may not be specified if synchronized is true') |
| if (self.seconds > 86400) or ((86400 % self.seconds) != 0): |
| raise groc.GrocException('can only use synchronized for periods that' |
| ' divide evenly into 24 hours') |
| |
| |
| self.start_time = datetime.time(0, 0).replace(tzinfo=self.timezone) |
| self.end_time = datetime.time(23, 59).replace(tzinfo=self.timezone) |
| elif start_time_string: |
| if not end_time_string: |
| raise ValueError( |
| 'end_time_string must be specified if start_time_string is') |
| self.start_time = ( |
| _GetTime(start_time_string).replace(tzinfo=self.timezone)) |
| self.end_time = _GetTime(end_time_string).replace(tzinfo=self.timezone) |
| else: |
| if end_time_string: |
| raise ValueError( |
| 'start_time_string must be specified if end_time_string is') |
| self.start_time = None |
| self.end_time = None |
| |
| def GetMatch(self, start): |
| """Returns the next match after 'start'. |
| |
| Arguments: |
| start: a datetime to start from. Matches will start from after this time. |
| This may be in any pytz time zone, or it may be timezone-naive |
| (interpreted as UTC). |
| |
| Returns: |
| a datetime object in the timezone of the input 'start' |
| """ |
| if self.start_time is None: |
| |
| return start + datetime.timedelta(seconds=self.seconds) |
| |
| |
| t = _ToTimeZone(start, self.timezone) |
| |
| |
| start_time = self._GetPreviousDateTime(t, self.start_time) |
| |
| |
| |
| t_delta = t - start_time |
| t_delta_seconds = (t_delta.days * 60 * 24 + t_delta.seconds) |
| num_intervals = (t_delta_seconds + self.seconds) / self.seconds |
| interval_time = ( |
| start_time + datetime.timedelta(seconds=(num_intervals * self.seconds))) |
| if self.timezone: |
| interval_time = self.timezone.normalize(interval_time) |
| |
| |
| |
| next_start_time = self._GetNextDateTime(t, self.start_time) |
| if (self._TimeIsInRange(t) and |
| self._TimeIsInRange(interval_time) and |
| interval_time < next_start_time): |
| result = interval_time |
| else: |
| result = next_start_time |
| |
| |
| return _ToTimeZone(result, start.tzinfo) |
| |
| def _TimeIsInRange(self, t): |
| """Returns true if 't' falls between start_time and end_time, inclusive. |
| |
| Arguments: |
| t: a datetime object, in self.timezone |
| |
| Returns: |
| a boolean |
| """ |
| |
| |
| previous_start_time = self._GetPreviousDateTime(t, self.start_time) |
| previous_end_time = self._GetPreviousDateTime(t, self.end_time) |
| if previous_start_time > previous_end_time: |
| return True |
| else: |
| return t == previous_end_time |
| |
| @staticmethod |
| def _GetPreviousDateTime(t, target_time): |
| """Returns the latest datetime <= 't' that has the time target_time. |
| |
| Arguments: |
| t: a datetime.datetime object, in self.timezone |
| target_time: a datetime.time object, in self.timezone |
| |
| Returns: |
| a datetime.datetime object, in self.timezone |
| """ |
| |
| date = t.date() |
| while True: |
| result = IntervalTimeSpecification._CombineDateAndTime(date, target_time) |
| if result <= t: |
| return result |
| date -= datetime.timedelta(days=1) |
| |
| @staticmethod |
| def _GetNextDateTime(t, target_time): |
| """Returns the earliest datetime > 't' that has the time target_time. |
| |
| Arguments: |
| t: a datetime.datetime object, in self.timezone |
| target_time: a time object, in self.timezone |
| |
| Returns: |
| a datetime.datetime object, in self.timezone |
| """ |
| |
| date = t.date() |
| while True: |
| result = IntervalTimeSpecification._CombineDateAndTime(date, target_time) |
| if result > t: |
| return result |
| date += datetime.timedelta(days=1) |
| |
| @staticmethod |
| def _CombineDateAndTime(date, time): |
| """Creates a datetime object from date and time objects. |
| |
| This is similar to the datetime.combine method, but its timezone |
| calculations are designed to work with pytz. |
| |
| Arguments: |
| date: a datetime.date object, in any timezone |
| time: a datetime.time object, in any timezone |
| |
| Returns: |
| a datetime.datetime object, in the timezone of the input 'time' |
| """ |
| if time.tzinfo: |
| naive_result = datetime.datetime( |
| date.year, date.month, date.day, time.hour, time.minute, time.second) |
| try: |
| return time.tzinfo.localize(naive_result, is_dst=None) |
| except AmbiguousTimeError: |
| |
| |
| return min(time.tzinfo.localize(naive_result, is_dst=True), |
| time.tzinfo.localize(naive_result, is_dst=False)) |
| except NonExistentTimeError: |
| |
| |
| |
| |
| while True: |
| naive_result += datetime.timedelta(minutes=1) |
| try: |
| return time.tzinfo.localize(naive_result, is_dst=None) |
| except NonExistentTimeError: |
| pass |
| else: |
| return datetime.datetime.combine(date, time) |
| |
| |
| class SpecificTimeSpecification(TimeSpecification): |
| """Specific time specification. |
| |
| A Specific interval is more complex, but defines a certain time to run and |
| the days that it should run. It has the following attributes: |
| time - the time of day to run, as 'HH:MM' |
| ordinals - first, second, third &c, as a set of integers in 1..5 |
| months - the months that this should run, as a set of integers in 1..12 |
| weekdays - the days of the week that this should run, as a set of integers, |
| 0=Sunday, 6=Saturday |
| timezone - the optional timezone as a string for this specification. |
| Defaults to UTC - valid entries are things like Australia/Victoria |
| or PST8PDT. |
| |
| A specific time schedule can be quite complex. A schedule could look like |
| this: |
| '1st,third sat,sun of jan,feb,mar 09:15' |
| |
| In this case, ordinals would be {1,3}, weekdays {0,6}, months {1,2,3} and |
| time would be '09:15'. |
| """ |
| |
| def __init__(self, ordinals=None, weekdays=None, months=None, monthdays=None, |
| timestr='00:00', timezone=None): |
| super(SpecificTimeSpecification, self).__init__() |
| if weekdays and monthdays: |
| raise ValueError('cannot supply both monthdays and weekdays') |
| if ordinals is None: |
| |
| self.ordinals = set(range(1, 6)) |
| else: |
| self.ordinals = set(ordinals) |
| if self.ordinals and (min(self.ordinals) < 1 or max(self.ordinals) > 5): |
| raise ValueError('ordinals must be between 1 and 5 inclusive, ' |
| 'got %r' % ordinals) |
| |
| if weekdays is None: |
| |
| self.weekdays = set(range(7)) |
| else: |
| self.weekdays = set(weekdays) |
| if self.weekdays and (min(self.weekdays) < 0 or max(self.weekdays) > 6): |
| raise ValueError('weekdays must be between ' |
| '0 (sun) and 6 (sat) inclusive, ' |
| 'got %r' % weekdays) |
| |
| if months is None: |
| |
| self.months = set(range(1, 13)) |
| else: |
| self.months = set(months) |
| if self.months and (min(self.months) < 1 or max(self.months) > 12): |
| raise ValueError('months must be between ' |
| '1 (jan) and 12 (dec) inclusive, ' |
| 'got %r' % months) |
| |
| if not monthdays: |
| self.monthdays = set() |
| else: |
| if min(monthdays) < 1: |
| raise ValueError('day of month must be greater than 0') |
| if max(monthdays) > 31: |
| raise ValueError('day of month must be less than 32') |
| if self.months: |
| for month in self.months: |
| _, ndays = calendar.monthrange(4, month) |
| if min(monthdays) <= ndays: |
| break |
| else: |
| raise ValueError('invalid day of month, ' |
| 'got day %r of month %r' % (max(monthdays), month)) |
| self.monthdays = set(monthdays) |
| self.time = _GetTime(timestr) |
| self.timezone = _GetTimezone(timezone) |
| |
| def _MatchingDays(self, year, month): |
| """Returns matching days for the given year and month. |
| |
| For the given year and month, return the days that match this instance's |
| day specification, based on either (a) the ordinals and weekdays, or |
| (b) the explicitly specified monthdays. If monthdays are specified, |
| dates that fall outside the range of the month will not be returned. |
| |
| Arguments: |
| year: the year as an integer |
| month: the month as an integer, in range 1-12 |
| |
| Returns: |
| a list of matching days, as ints in range 1-31 |
| """ |
| start_day, last_day = calendar.monthrange(year, month) |
| if self.monthdays: |
| return sorted([day for day in self.monthdays if day <= last_day]) |
| |
| |
| out_days = [] |
| start_day = (start_day + 1) % 7 |
| for ordinal in self.ordinals: |
| for weekday in self.weekdays: |
| day = ((weekday - start_day) % 7) + 1 |
| day += 7 * (ordinal - 1) |
| if day <= last_day: |
| out_days.append(day) |
| return sorted(out_days) |
| |
| def _NextMonthGenerator(self, start, matches): |
| """Creates a generator that produces results from the set 'matches'. |
| |
| Matches must be >= 'start'. If none match, the wrap counter is incremented, |
| and the result set is reset to the full set. Yields a 2-tuple of (match, |
| wrapcount). |
| |
| Arguments: |
| start: first set of matches will be >= this value (an int) |
| matches: the set of potential matches (a sequence of ints) |
| |
| Yields: |
| a two-tuple of (match, wrap counter). match is an int in range (1-12), |
| wrapcount is a int indicating how many times we've wrapped around. |
| """ |
| potential = matches = sorted(matches) |
| |
| after = start - 1 |
| wrapcount = 0 |
| while True: |
| potential = [x for x in potential if x > after] |
| if not potential: |
| |
| |
| wrapcount += 1 |
| potential = matches |
| after = potential[0] |
| yield (after, wrapcount) |
| |
| def GetMatch(self, start): |
| """Returns the next match after time start. |
| |
| Must be implemented in subclasses. |
| |
| Arguments: |
| start: a datetime to start from. Matches will start from after this time. |
| This may be in any pytz time zone, or it may be timezone-naive |
| (interpreted as UTC). |
| |
| Returns: |
| a datetime object in the timezone of the input 'start' |
| """ |
| |
| |
| |
| |
| |
| start_time = _ToTimeZone(start, self.timezone).replace(tzinfo=None) |
| if self.months: |
| |
| months = self._NextMonthGenerator(start_time.month, self.months) |
| while True: |
| |
| month, yearwraps = months.next() |
| candidate_month = start_time.replace(day=1, month=month, |
| year=start_time.year + yearwraps) |
| |
| |
| day_matches = self._MatchingDays(candidate_month.year, month) |
| |
| if ((candidate_month.year, candidate_month.month) |
| == (start_time.year, start_time.month)): |
| |
| day_matches = [x for x in day_matches if x >= start_time.day] |
| |
| while (day_matches and day_matches[0] == start_time.day |
| and start_time.time() >= self.time): |
| day_matches.pop(0) |
| while day_matches: |
| |
| out = candidate_month.replace(day=day_matches[0], hour=self.time.hour, |
| minute=self.time.minute, second=0, |
| microsecond=0) |
| |
| if self.timezone and pytz is not None: |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| try: |
| out = self.timezone.localize(out, is_dst=None) |
| except AmbiguousTimeError: |
| |
| out = self.timezone.localize(out) |
| except NonExistentTimeError: |
| |
| |
| |
| |
| |
| |
| for _ in range(24): |
| |
| |
| out += datetime.timedelta(minutes=60) |
| try: |
| out = self.timezone.localize(out) |
| except NonExistentTimeError: |
| |
| continue |
| break |
| return _ToTimeZone(out, start.tzinfo) |
