#!/usr/bin/env python  """ Managing free/busy periods.  Copyright (C) 2014, 2015, 2016, 2017 Paul Boddie <paul@boddie.org.uk>  This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.  This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.  You should have received a copy of the GNU General Public License along with this program.  If not, see <http://www.gnu.org/licenses/>. """  from bisect import bisect_left, bisect_right from imiptools.dates import format_datetime from imiptools.period import get_overlapping, Period, PeriodBase  # Conversion functions.  def from_string(s, encoding):      "Interpret 's' using 'encoding', preserving None."      if s:         if isinstance(s, unicode):             return s         else:             return unicode(s, encoding)     else:         return s  def to_string(s, encoding):      "Encode 's' using 'encoding', preserving None."      if s:         return s.encode(encoding)     else:         return s  class period_from_tuple:      "Convert a tuple to an instance of the given 'period_class'."      def __init__(self, period_class):         self.period_class = period_class     def __call__(self, t):         return make_period(t, self.period_class)  def period_to_tuple(p):      "Convert period 'p' to a tuple for serialisation."      return p.as_tuple(strings_only=True)  def make_period(t, period_class):      "Convert tuple 't' to an instance of the given 'period_class'."      args = []     for arg, column in zip(t, period_class.period_columns):         args.append(from_string(arg, "utf-8"))     return period_class(*args)  def make_tuple(t, period_class):      "Restrict tuple 't' to the columns appropriate for 'period_class'."      args = []     for arg, column in zip(t, period_class.period_columns):         args.append(arg)     return tuple(args)    # Period abstractions.  class FreeBusyPeriod(PeriodBase):      "A free/busy record abstraction."      period_columns = [         "start", "end", "object_uid", "transp", "object_recurrenceid",         "summary", "organiser"         ]      def __init__(self, start, end, uid=None, transp=None, recurrenceid=None,         summary=None, organiser=None):          """         Initialise a free/busy period with the given 'start' and 'end' points,         plus any 'uid', 'transp', 'recurrenceid', 'summary' and 'organiser'         details.         """          PeriodBase.__init__(self, start, end)         self.uid = uid or None         self.transp = transp or None         self.recurrenceid = recurrenceid or None         self.summary = summary or None         self.organiser = organiser or None      def as_tuple(self, strings_only=False, string_datetimes=False):          """         Return the initialisation parameter tuple, converting datetimes and         false value parameters to strings if 'strings_only' is set to a true         value. Otherwise, if 'string_datetimes' is set to a true value, only the         datetime values are converted to strings.         """          null = lambda x: (strings_only and [""] or [x])[0]         return (             (strings_only or string_datetimes) and format_datetime(self.get_start_point()) or self.start,             (strings_only or string_datetimes) and format_datetime(self.get_end_point()) or self.end,             self.uid or null(self.uid),             self.transp or strings_only and "OPAQUE" or None,             self.recurrenceid or null(self.recurrenceid),             self.summary or null(self.summary),             self.organiser or null(self.organiser)             )      def __cmp__(self, other):          """         Compare this object to 'other', employing the uid if the periods         involved are the same.         """          result = PeriodBase.__cmp__(self, other)         if result == 0 and isinstance(other, FreeBusyPeriod):             return cmp((self.uid, self.recurrenceid), (other.uid, other.recurrenceid))         else:             return result      def get_key(self):         return self.uid, self.recurrenceid, self.get_start()      def __repr__(self):         return "FreeBusyPeriod%r" % (self.as_tuple(),)      def get_tzid(self):         return "UTC"      # Period and event recurrence logic.      def is_replaced(self, recurrences):          """         Return whether this period refers to one of the 'recurrences'.         The 'recurrences' must be UTC datetimes corresponding to the start of         the period described by a recurrence.         """          for recurrence in recurrences:             if self.is_affected(recurrence):                 return True         return False      def is_affected(self, recurrence):          """         Return whether this period refers to 'recurrence'. The 'recurrence' must         be a UTC datetime corresponding to the start of the period described by         a recurrence.         """          return recurrence and self.get_start_point() == recurrence      # Value correction methods.      def make_corrected(self, start, end):         return self.__class__(start, end)  class FreeBusyOfferPeriod(FreeBusyPeriod):      "A free/busy record abstraction for an offer period."      period_columns = FreeBusyPeriod.period_columns + ["expires"]      def __init__(self, start, end, uid=None, transp=None, recurrenceid=None,         summary=None, organiser=None, expires=None):          """         Initialise a free/busy period with the given 'start' and 'end' points,         plus any 'uid', 'transp', 'recurrenceid', 'summary' and 'organiser'         details.          An additional 'expires' parameter can be used to indicate an expiry         datetime in conjunction with free/busy offers made when countering         event proposals.         """          FreeBusyPeriod.__init__(self, start, end, uid, transp, recurrenceid,             summary, organiser)         self.expires = expires or None      def as_tuple(self, strings_only=False, string_datetimes=False):          """         Return the initialisation parameter tuple, converting datetimes and         false value parameters to strings if 'strings_only' is set to a true         value. Otherwise, if 'string_datetimes' is set to a true value, only the         datetime values are converted to strings.         """          null = lambda x: (strings_only and [""] or [x])[0]         return FreeBusyPeriod.as_tuple(self, strings_only, string_datetimes) + (             self.expires or null(self.expires),)      def __repr__(self):         return "FreeBusyOfferPeriod%r" % (self.as_tuple(),)  class FreeBusyGroupPeriod(FreeBusyPeriod):      "A free/busy record abstraction for a quota group period."      period_columns = FreeBusyPeriod.period_columns + ["attendee"]      def __init__(self, start, end, uid=None, transp=None, recurrenceid=None,         summary=None, organiser=None, attendee=None):          """         Initialise a free/busy period with the given 'start' and 'end' points,         plus any 'uid', 'transp', 'recurrenceid', 'summary' and 'organiser'         details.          An additional 'attendee' parameter can be used to indicate the identity         of the attendee recording the period.         """          FreeBusyPeriod.__init__(self, start, end, uid, transp, recurrenceid,             summary, organiser)         self.attendee = attendee or None      def as_tuple(self, strings_only=False, string_datetimes=False):          """         Return the initialisation parameter tuple, converting datetimes and         false value parameters to strings if 'strings_only' is set to a true         value. Otherwise, if 'string_datetimes' is set to a true value, only the         datetime values are converted to strings.         """          null = lambda x: (strings_only and [""] or [x])[0]         return FreeBusyPeriod.as_tuple(self, strings_only, string_datetimes) + (             self.attendee or null(self.attendee),)      def __cmp__(self, other):          """         Compare this object to 'other', employing the uid if the periods         involved are the same.         """          result = FreeBusyPeriod.__cmp__(self, other)         if isinstance(other, FreeBusyGroupPeriod) and result == 0:             return cmp(self.attendee, other.attendee)         else:             return result      def __repr__(self):         return "FreeBusyGroupPeriod%r" % (self.as_tuple(),)    # Collection abstractions.  class FreeBusyCollectionBase:      "Common operations on free/busy period collections."      period_class = FreeBusyPeriod      def __init__(self, mutable=True):         self.mutable = mutable      def _check_mutable(self):         if not self.mutable:             raise TypeError, "Cannot mutate this collection."      def close(self):          "Close the collection."          pass      def copy(self):          "Make an independent mutable copy of the collection."          return FreeBusyCollection(list(self), True)      def make_period(self, t):          """         Make a period using the given tuple of arguments and the collection's         column details.         """          return make_period(t, self.period_class)      def make_tuple(self, t):          """         Return a tuple from the given tuple 't' conforming to the collection's         column details.         """          return make_tuple(t, self.period_class)      # List emulation methods.      def __iadd__(self, periods):         self.insert_periods(periods)         return self      def append(self, period):         self.insert_period(period)      # Operations.      def insert_period(self, period):          """         Insert the given 'period' into the collection.          This should be implemented in subclasses.         """          pass      def insert_periods(self, periods):          "Insert the given 'periods' into the collection."          for p in periods:             self.insert_period(p)      def can_schedule(self, periods, uid, recurrenceid):          """         Return whether the collection can accommodate the given 'periods'         employing the specified 'uid' and 'recurrenceid'.         """          for conflict in self.have_conflict(periods, True):             if conflict.uid != uid or conflict.recurrenceid != recurrenceid:                 return False          return True      def have_conflict(self, periods, get_conflicts=False):          """         Return whether any period in the collection overlaps with the given         'periods', returning a collection of such overlapping periods if         'get_conflicts' is set to a true value.         """          conflicts = set()         for p in periods:             overlapping = self.period_overlaps(p, get_conflicts)             if overlapping:                 if get_conflicts:                     conflicts.update(overlapping)                 else:                     return True          if get_conflicts:             return conflicts         else:             return False      def period_overlaps(self, period, get_periods=False):          """         Return whether any period in the collection overlaps with the given         'period', returning a collection of overlapping periods if 'get_periods'         is set to a true value.         """          overlapping = self.get_overlapping([period])          if get_periods:             return overlapping         else:             return len(overlapping) != 0      def replace_overlapping(self, period, replacements):          """         Replace existing periods in the collection within the given 'period',         using the given 'replacements'.         """          self._check_mutable()          self.remove_overlapping(period)         for replacement in replacements:             self.insert_period(replacement)      def coalesce_freebusy(self):          "Coalesce the periods in the collection, returning a new collection."          if not self:             return FreeBusyCollection()          fb = []          it = iter(self)         period = it.next()          start = period.get_start_point()         end = period.get_end_point()          try:             while True:                 period = it.next()                 if period.get_start_point() > end:                     fb.append(self.period_class(start, end))                     start = period.get_start_point()                     end = period.get_end_point()                 else:                     end = max(end, period.get_end_point())         except StopIteration:             pass          fb.append(self.period_class(start, end))         return FreeBusyCollection(fb)      def invert_freebusy(self):          "Return the free periods from the collection as a new collection."          if not self:             return FreeBusyCollection([self.period_class(None, None)])          # Coalesce periods that overlap or are adjacent.          fb = self.coalesce_freebusy()         free = []          # Add a start-of-time period if appropriate.          first = fb[0].get_start_point()         if first:             free.append(self.period_class(None, first))          start = fb[0].get_end_point()          for period in fb[1:]:             free.append(self.period_class(start, period.get_start_point()))             start = period.get_end_point()          # Add an end-of-time period if appropriate.          if start:             free.append(self.period_class(start, None))          return FreeBusyCollection(free)      def _update_freebusy(self, periods, uid, recurrenceid):          """         Update the free/busy details with the given 'periods', using the given         'uid' plus 'recurrenceid' to remove existing periods.         """          self._check_mutable()          self.remove_specific_event_periods(uid, recurrenceid)          self.insert_periods(periods)      def update_freebusy(self, periods, transp, uid, recurrenceid, summary, organiser):          """         Update the free/busy details with the given 'periods', 'transp' setting,         'uid' plus 'recurrenceid' and 'summary' and 'organiser' details.         """          new_periods = []          for p in periods:             new_periods.append(                 self.period_class(p.get_start_point(), p.get_end_point(), uid, transp, recurrenceid, summary, organiser)                 )          self._update_freebusy(new_periods, uid, recurrenceid)  class SupportAttendee:      "A mix-in that supports the affected attendee in free/busy periods."      period_class = FreeBusyGroupPeriod      def _update_freebusy(self, periods, uid, recurrenceid, attendee=None):          """         Update the free/busy details with the given 'periods', using the given         'uid' plus 'recurrenceid' and 'attendee' to remove existing periods.         """          self._check_mutable()          self.remove_specific_event_periods(uid, recurrenceid, attendee)          self.insert_periods(periods)      def update_freebusy(self, periods, transp, uid, recurrenceid, summary, organiser, attendee=None):          """         Update the free/busy details with the given 'periods', 'transp' setting,         'uid' plus 'recurrenceid' and 'summary' and 'organiser' details.          An optional 'attendee' indicates the attendee affected by the period.         """          new_periods = []          for p in periods:             new_periods.append(                 self.period_class(p.get_start_point(), p.get_end_point(), uid, transp, recurrenceid, summary, organiser, attendee)                 )          self._update_freebusy(new_periods, uid, recurrenceid, attendee)  class SupportExpires:      "A mix-in that supports the expiry datetime in free/busy periods."      period_class = FreeBusyOfferPeriod      def update_freebusy(self, periods, transp, uid, recurrenceid, summary, organiser, expires=None):          """         Update the free/busy details with the given 'periods', 'transp' setting,         'uid' plus 'recurrenceid' and 'summary' and 'organiser' details.          An optional 'expires' datetime string indicates the expiry time of any         free/busy offer.         """          new_periods = []          for p in periods:             new_periods.append(                 self.period_class(p.get_start_point(), p.get_end_point(), uid, transp, recurrenceid, summary, organiser, expires)                 )          self._update_freebusy(new_periods, uid, recurrenceid)    # Simple abstractions suitable for use with file-based representations and as # general copies of collections.  class FreeBusyCollection(FreeBusyCollectionBase):      "An abstraction for a collection of free/busy periods."      def __init__(self, periods=None, mutable=True):          """         Initialise the collection with the given list of 'periods', or start an         empty collection if no list is given. If 'mutable' is indicated, the         collection may be changed; otherwise, an exception will be raised.         """          FreeBusyCollectionBase.__init__(self, mutable)          if periods is not None:             self.periods = periods         else:             self.periods = []      def get_filename(self):          "Return any filename for the periods collection."          if hasattr(self.periods, "filename"):             return self.periods.filename         else:             return None      def close(self):          "Close the collection."          if hasattr(self.periods, "close"):             self.periods.close()      # List emulation methods.      def __nonzero__(self):         return bool(self.periods)      def __iter__(self):         return iter(self.periods)      def __len__(self):         return len(self.periods)      def __getitem__(self, i):         return self.periods[i]      # Dictionary emulation methods (even though this is not a mapping).      def clear(self):         del self.periods[:]      # Operations.      def insert_period(self, period):          "Insert the given 'period' into the collection."          self._check_mutable()          i = bisect_left(self.periods, period)         if i == len(self.periods):             self.periods.append(period)         elif self.periods[i] != period:             self.periods.insert(i, period)      def remove_periods(self, periods):          "Remove the given 'periods' from the collection."          self._check_mutable()          for period in periods:             i = bisect_left(self.periods, period)             if i < len(self.periods) and self.periods[i] == period:                 del self.periods[i]      def remove_periods_before(self, period):          "Remove the entries in the collection before 'period'."          last = bisect_right(self.periods, period)         self.remove_periods(self.periods[:last])      def remove_event_periods(self, uid, recurrenceid=None, participant=None):          """         Remove from the collection all periods associated with 'uid' and         'recurrenceid' (which if omitted causes the "parent" object's periods to         be referenced).          If 'participant' is specified, only remove periods for which the         participant is given as attending.          Return the removed periods.         """          self._check_mutable()          removed = []         i = 0         while i < len(self.periods):             fb = self.periods[i]              if fb.uid == uid and fb.recurrenceid == recurrenceid and \                (not participant or participant == fb.attendee):                  removed.append(self.periods[i])                 del self.periods[i]             else:                 i += 1          return removed      # Specific period removal when updating event details.      remove_specific_event_periods = remove_event_periods      def remove_additional_periods(self, uid, recurrenceids=None):          """         Remove from the collection all periods associated with 'uid' having a         recurrence identifier indicating an additional or modified period.          If 'recurrenceids' is specified, remove all periods associated with         'uid' that do not have a recurrence identifier in the given list.          Return the removed periods.         """          self._check_mutable()          removed = []         i = 0         while i < len(self.periods):             fb = self.periods[i]             if fb.uid == uid and fb.recurrenceid and (                 recurrenceids is None or                 recurrenceids is not None and fb.recurrenceid not in recurrenceids                 ):                 removed.append(self.periods[i])                 del self.periods[i]             else:                 i += 1          return removed      def remove_affected_period(self, uid, start, participant=None):          """         Remove from the collection the period associated with 'uid' that         provides an occurrence starting at the given 'start' (provided by a         recurrence identifier, converted to a datetime). A recurrence identifier         is used to provide an alternative time period whilst also acting as a         reference to the originally-defined occurrence.          If 'participant' is specified, only remove periods for which the         participant is given as attending.          Return any removed period in a list.         """          self._check_mutable()          removed = []          search = Period(start, start)         found = bisect_left(self.periods, search)          while found < len(self.periods):             fb = self.periods[found]              # Stop looking if the start no longer matches the recurrence identifier.              if fb.get_start_point() != search.get_start_point():                 break              # If the period belongs to the parent object, remove it and return.              if not fb.recurrenceid and uid == fb.uid and \                (not participant or participant == fb.attendee):                  removed.append(self.periods[found])                 del self.periods[found]                 break              # Otherwise, keep looking for a matching period.              found += 1          return removed      def periods_from(self, period):          "Return the entries in the collection at or after 'period'."          first = bisect_left(self.periods, period)         return self.periods[first:]      def periods_until(self, period):          "Return the entries in the collection before 'period'."          last = bisect_right(self.periods, Period(period.get_end(), period.get_end(), period.get_tzid()))         return self.periods[:last]      def get_overlapping(self, periods):          """         Return the entries in the collection providing periods overlapping with         the given sorted collection of 'periods'.         """          return get_overlapping(self.periods, periods)      def remove_overlapping(self, period):          "Remove all periods overlapping with 'period' from the collection."          self._check_mutable()          overlapping = self.get_overlapping([period])          if overlapping:             for fb in overlapping:                 self.periods.remove(fb)  class FreeBusyGroupCollection(SupportAttendee, FreeBusyCollection):      "A collection of quota group free/busy objects."      def remove_specific_event_periods(self, uid, recurrenceid=None, attendee=None):          """         Remove from the collection all periods associated with 'uid' and         'recurrenceid' (which if omitted causes the "parent" object's periods to         be referenced) and any 'attendee'.          Return the removed periods.         """          self._check_mutable()          removed = []         i = 0         while i < len(self.periods):             fb = self.periods[i]             if fb.uid == uid and fb.recurrenceid == recurrenceid and fb.attendee == attendee:                 removed.append(self.periods[i])                 del self.periods[i]             else:                 i += 1          return removed  class FreeBusyOffersCollection(SupportExpires, FreeBusyCollection):      "A collection of offered free/busy objects."      pass  # vim: tabstop=4 expandtab shiftwidth=4