#!/usr/bin/env python  """ Interpretation of vCalendar content.  Copyright (C) 2014, 2015 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 from datetime import date, datetime, timedelta from email.mime.text import MIMEText from imiptools.dates import format_datetime, get_datetime, \                             get_datetime_item as get_item_from_datetime, \                             get_datetime_tzid, \                             get_duration, get_period, get_period_item, \                             get_recurrence_start_point, \                             get_time, get_tzid, to_datetime, to_timezone, \                             to_utc_datetime from imiptools.period import FreeBusyPeriod, Period, RecurringPeriod, period_overlaps from vCalendar import iterwrite, parse, ParseError, to_dict, to_node from vRecurrence import get_parameters, get_rule import email.utils  try:     from cStringIO import StringIO except ImportError:     from StringIO import StringIO  class Object:      "Access to calendar structures."      def __init__(self, fragment):         self.objtype, (self.details, self.attr) = fragment.items()[0]      def get_uid(self):         return self.get_value("UID")      def get_recurrenceid(self):          """         Return the recurrence identifier, normalised to a UTC datetime if         specified as a datetime or date with accompanying time zone information,         maintained as a date or floating datetime otherwise. If no recurrence         identifier is present, None is returned.          Note that this normalised form of the identifier may well not be the         same as the originally-specified identifier because that could have been         specified using an accompanying TZID attribute, whereas the normalised         form is effectively a converted datetime value.         """          if not self.has_key("RECURRENCE-ID"):             return None         dt, attr = self.get_datetime_item("RECURRENCE-ID")          # Coerce any date to a UTC datetime if TZID was specified.          tzid = attr.get("TZID")         if tzid:             dt = to_timezone(to_datetime(dt, tzid), "UTC")         return format_datetime(dt)      def get_recurrence_start_point(self, recurrenceid, tzid):          """         Return the start point corresponding to the given 'recurrenceid', using         the fallback 'tzid' to define the specific point in time referenced by         the recurrence identifier if the identifier has a date representation.          If 'recurrenceid' is given as None, this object's recurrence identifier         is used to obtain a start point, but if this object does not provide a         recurrence, None is returned.          A start point is typically used to match free/busy periods which are         themselves defined in terms of UTC datetimes.         """          recurrenceid = recurrenceid or self.get_recurrenceid()         if recurrenceid:             return get_recurrence_start_point(recurrenceid, tzid)         else:             return None      def get_recurrence_start_points(self, recurrenceids, tzid):         return [self.get_recurrence_start_point(recurrenceid, tzid) for recurrenceid in recurrenceids]      # Structure access.      def copy(self):         return Object(to_dict(self.to_node()))      def get_items(self, name, all=True):         return get_items(self.details, name, all)      def get_item(self, name):         return get_item(self.details, name)      def get_value_map(self, name):         return get_value_map(self.details, name)      def get_values(self, name, all=True):         return get_values(self.details, name, all)      def get_value(self, name):         return get_value(self.details, name)      def get_utc_datetime(self, name, date_tzid=None):         return get_utc_datetime(self.details, name, date_tzid)      def get_date_value_items(self, name, tzid=None):         return get_date_value_items(self.details, name, tzid)      def get_date_value_item_periods(self, name, tzid=None):         return get_date_value_item_periods(self.details, name, self.get_main_period(tzid).get_duration(), tzid)      def get_period_values(self, name, tzid=None):         return get_period_values(self.details, name, tzid)      def get_datetime(self, name):         t = get_datetime_item(self.details, name)         if not t: return None         dt, attr = t         return dt      def get_datetime_item(self, name):         return get_datetime_item(self.details, name)      def get_duration(self, name):         return get_duration(self.get_value(name))      def to_node(self):         return to_node({self.objtype : [(self.details, self.attr)]})      def to_part(self, method):         return to_part(method, [self.to_node()])      # Direct access to the structure.      def has_key(self, name):         return self.details.has_key(name)      def get(self, name):         return self.details.get(name)      def keys(self):         return self.details.keys()      def __getitem__(self, name):         return self.details[name]      def __setitem__(self, name, value):         self.details[name] = value      def __delitem__(self, name):         del self.details[name]      def remove(self, name):         try:             del self[name]         except KeyError:             pass      def remove_all(self, names):         for name in names:             self.remove(name)      def preserve(self, names):         for name in self.keys():             if not name in names:                 self.remove(name)      # Computed results.      def get_main_period(self, tzid=None):          """         Return a period object corresponding to the main start-end period for         the object.         """          (dtstart, dtstart_attr), (dtend, dtend_attr) = self.get_main_period_items()         tzid = tzid or get_tzid(dtstart_attr, dtend_attr)         return RecurringPeriod(dtstart, dtend, tzid, "DTSTART", dtstart_attr, dtend_attr)      def get_main_period_items(self):          """         Return two (value, attributes) items corresponding to the main start-end         period for the object.         """          dtstart, dtstart_attr = self.get_datetime_item("DTSTART")          if self.has_key("DTEND"):             dtend, dtend_attr = self.get_datetime_item("DTEND")         elif self.has_key("DURATION"):             duration = self.get_duration("DURATION")             dtend = dtstart + duration             dtend_attr = dtstart_attr         else:             dtend, dtend_attr = dtstart, dtstart_attr          return (dtstart, dtstart_attr), (dtend, dtend_attr)      def get_periods(self, tzid, end=None):          """         Return periods defined by this object, employing the given 'tzid' where         no time zone information is defined, and limiting the collection to a         window of time with the given 'end'.          If 'end' is omitted, only explicit recurrences and recurrences from         explicitly-terminated rules will be returned.         """          return get_periods(self, tzid, end)      def get_active_periods(self, recurrenceids, tzid, end=None):          """         Return all periods specified by this object that are not replaced by         those defined by 'recurrenceids', using 'tzid' as a fallback time zone         to convert floating dates and datetimes, and using 'end' to indicate the         end of the time window within which periods are considered.         """          # Specific recurrences yield all specified periods.          periods = self.get_periods(tzid, end)          if self.get_recurrenceid():             return periods          # Parent objects need to have their periods tested against redefined         # recurrences.          active = []          for p in periods:              # Subtract any recurrences from the free/busy details of a             # parent object.              if not p.is_replaced(recurrenceids):                 active.append(p)          return active      def get_freebusy_period(self, period, only_organiser=False):          """         Return a free/busy period for the given 'period' provided by this         object, using the 'only_organiser' status to produce a suitable         transparency value.         """          return FreeBusyPeriod(             period.get_start_point(),             period.get_end_point(),             self.get_value("UID"),             only_organiser and "ORG" or self.get_value("TRANSP") or "OPAQUE",             self.get_recurrenceid(),             self.get_value("SUMMARY"),             get_uri(self.get_value("ORGANIZER"))             )      def get_participation_status(self, participant):          """         Return the participation status of the given 'participant', with the         special value "ORG" indicating organiser-only participation.         """              attendees = uri_dict(self.get_value_map("ATTENDEE"))         organiser = get_uri(self.get_value("ORGANIZER"))          attendee_attr = attendees.get(participant)         if attendee_attr:             return attendee_attr.get("PARTSTAT", "NEEDS-ACTION")         elif organiser == participant:             return "ORG"          return None      def get_participation(self, partstat, include_needs_action=False):          """         Return whether 'partstat' indicates some kind of participation in an         event. If 'include_needs_action' is specified as a true value, events         not yet responded to will be treated as events with tentative         participation.         """          return not partstat in ("DECLINED", "DELEGATED", "NEEDS-ACTION") or \                include_needs_action and partstat == "NEEDS-ACTION" or \                partstat == "ORG"      def get_tzid(self):          """         Return a time zone identifier used by the start or end datetimes,         potentially suitable for converting dates to datetimes.         """          if not self.has_key("DTSTART"):             return None         dtstart, dtstart_attr = self.get_datetime_item("DTSTART")         if self.has_key("DTEND"):             dtend, dtend_attr = self.get_datetime_item("DTEND")         else:             dtend_attr = None         return get_tzid(dtstart_attr, dtend_attr)      def is_shared(self):          """         Return whether this object is shared based on the presence of a SEQUENCE         property.         """          return self.get_value("SEQUENCE") is not None      def possibly_active_from(self, dt, tzid):          """         Return whether the object is possibly active from or after the given         datetime 'dt' using 'tzid' to convert any dates or floating datetimes.         """          dt = to_datetime(dt, tzid)         periods = self.get_periods(tzid)          for p in periods:             if p.get_end_point() > dt:                 return True          return self.possibly_recurring_indefinitely()      def possibly_recurring_indefinitely(self):          "Return whether this object may recur indefinitely."          rrule = self.get_value("RRULE")         parameters = rrule and get_parameters(rrule)         until = parameters and parameters.get("UNTIL")         count = parameters and parameters.get("COUNT")          # Non-recurring periods or constrained recurrences.          if not rrule or until or count:             return False          # Unconstrained recurring periods will always lie beyond any specified         # datetime.          else:             return True      # Modification methods.      def set_datetime(self, name, dt, tzid=None):          """         Set a datetime for property 'name' using 'dt' and the optional fallback         'tzid', returning whether an update has occurred.         """          if dt:             old_value = self.get_value(name)             self[name] = [get_item_from_datetime(dt, tzid)]             return format_datetime(dt) != old_value          return False      def set_period(self, period):          "Set the given 'period' as the main start and end."          result = self.set_datetime("DTSTART", period.get_start())         result = self.set_datetime("DTEND", period.get_end()) or result         if self.has_key("DURATION"):             del self["DURATION"]          return result      def set_periods(self, periods):          """         Set the given 'periods' as recurrence date properties, replacing the         previous RDATE properties and ignoring any RRULE properties.         """          old_values = set(self.get_date_value_item_periods("RDATE") or [])         new_rdates = []          if self.has_key("RDATE"):             del self["RDATE"]          main_changed = False          for p in periods:             if p.origin == "RDATE" and p != self.get_main_period():                 new_rdates.append(get_period_item(p.get_start(), p.get_end()))             elif p.origin == "DTSTART":                 main_changed = self.set_period(p)          if new_rdates:             self["RDATE"] = new_rdates          return main_changed or old_values != set(self.get_date_value_item_periods("RDATE") or [])      def set_rule(self, rule):          """         Set the given 'rule' in this object, replacing the previous RRULE         property, returning whether the object has changed. The provided 'rule'         must be an item.         """          if not rule:             return False          old_rrule = self.get_item("RRULE")         self["RRULE"] = [rule]         return old_rrule != rule      def set_exceptions(self, exceptions):          """         Set the given 'exceptions' in this object, replacing the previous EXDATE         properties, returning whether the object has changed. The provided         'exceptions' must be a collection of items.         """          old_exdates = set(self.get_date_value_item_periods("EXDATE") or [])         if exceptions:             self["EXDATE"] = exceptions             return old_exdates != set(self.get_date_value_item_periods("EXDATE") or [])         elif old_exdates:             del self["EXDATE"]             return True         else:             return False      def update_dtstamp(self):          "Update the DTSTAMP in the object."          dtstamp = self.get_utc_datetime("DTSTAMP")         utcnow = get_time()         dtstamp = format_datetime(dtstamp and dtstamp > utcnow and dtstamp or utcnow)         self["DTSTAMP"] = [(dtstamp, {})]         return dtstamp      def update_sequence(self, increment=False):          "Set or update the SEQUENCE in the object."          sequence = self.get_value("SEQUENCE") or "0"         self["SEQUENCE"] = [(str(int(sequence) + (increment and 1 or 0)), {})]         return sequence      def update_exceptions(self, excluded, asserted):          """         Update the exceptions to any rule by applying the list of 'excluded'         periods. Where 'asserted' periods are provided, exceptions will be         removed corresponding to those periods.         """          old_exdates = self.get_date_value_item_periods("EXDATE") or []         new_exdates = set(old_exdates)         new_exdates.update(excluded)         new_exdates.difference_update(asserted)          if not new_exdates and self.has_key("EXDATE"):             del self["EXDATE"]         else:             self["EXDATE"] = []             for p in new_exdates:                 self["EXDATE"].append(get_period_item(p.get_start(), p.get_end()))          return set(old_exdates) != new_exdates      def correct_object(self, tzid, permitted_values):          """         Correct the object's period details using the given 'tzid' and         'permitted_values'.         """          corrected = set()         rdates = []          for period in self.get_periods(tzid):             corrected_period = period.get_corrected(permitted_values)              if corrected_period is period:                 if period.origin == "RDATE":                     rdates.append(period)                 continue              if period.origin == "DTSTART":                 self.set_period(corrected_period)                 corrected.add("DTSTART")             elif period.origin == "RDATE":                 rdates.append(corrected_period)                 corrected.add("RDATE")          if "RDATE" in corrected:             self.set_periods(rdates)          return corrected  # Construction and serialisation.  def make_calendar(nodes, method=None):      """     Return a complete calendar node wrapping the given 'nodes' and employing the     given 'method', if indicated.     """      return ("VCALENDAR", {},             (method and [("METHOD", {}, method)] or []) +             [("VERSION", {}, "2.0")] +             nodes            )  def make_freebusy(freebusy, uid, organiser, organiser_attr=None, attendee=None,                   attendee_attr=None, period=None):          """     Return a calendar node defining the free/busy details described in the given     'freebusy' list, employing the given 'uid', for the given 'organiser' and     optional 'organiser_attr', with the optional 'attendee' providing recipient     details together with the optional 'attendee_attr'.      The result will be constrained to the 'period' if specified.     """          record = []     rwrite = record.append          rwrite(("ORGANIZER", organiser_attr or {}, organiser))      if attendee:         rwrite(("ATTENDEE", attendee_attr or {}, attendee))       rwrite(("UID", {}, uid))      if freebusy:          # Get a constrained view if start and end limits are specified.          if period:             periods = period_overlaps(freebusy, period, True)         else:             periods = freebusy          # Write the limits of the resource.          if periods:             rwrite(("DTSTART", {"VALUE" : "DATE-TIME"}, format_datetime(periods[0].get_start_point())))             rwrite(("DTEND", {"VALUE" : "DATE-TIME"}, format_datetime(periods[-1].get_end_point())))         else:             rwrite(("DTSTART", {"VALUE" : "DATE-TIME"}, format_datetime(period.get_start_point())))             rwrite(("DTEND", {"VALUE" : "DATE-TIME"}, format_datetime(period.get_end_point())))          for p in periods:             if p.transp == "OPAQUE":                 rwrite(("FREEBUSY", {"FBTYPE" : "BUSY"}, "/".join(                     map(format_datetime, [p.get_start_point(), p.get_end_point()])                     )))      return ("VFREEBUSY", {}, record)  def parse_object(f, encoding, objtype=None):      """     Parse the iTIP content from 'f' having the given 'encoding'. If 'objtype' is     given, only objects of that type will be returned. Otherwise, the root of     the content will be returned as a dictionary with a single key indicating     the object type.      Return None if the content was not readable or suitable.     """      try:         try:             doctype, attrs, elements = obj = parse(f, encoding=encoding)             if objtype and doctype == objtype:                 return to_dict(obj)[objtype][0]             elif not objtype:                 return to_dict(obj)         finally:             f.close()      # NOTE: Handle parse errors properly.      except (ParseError, ValueError):         pass      return None  def to_part(method, calendar):      """     Write using the given 'method', the 'calendar' details to a MIME     text/calendar part.     """      encoding = "utf-8"     out = StringIO()     try:         to_stream(out, make_calendar(calendar, method), encoding)         part = MIMEText(out.getvalue(), "calendar", encoding)         part.set_param("method", method)         return part      finally:         out.close()  def to_stream(out, fragment, encoding="utf-8"):     iterwrite(out, encoding=encoding).append(fragment)  # Structure access functions.  def get_items(d, name, all=True):      """     Get all items from 'd' for the given 'name', returning single items if     'all' is specified and set to a false value and if only one value is     present for the name. Return None if no items are found for the name or if     many items are found but 'all' is set to a false value.     """      if d.has_key(name):         items = [(value or None, attr) for value, attr in d[name]]         if all:             return items         elif len(items) == 1:             return items[0]         else:             return None     else:         return None  def get_item(d, name):     return get_items(d, name, False)  def get_value_map(d, name):      """     Return a dictionary for all items in 'd' having the given 'name'. The     dictionary will map values for the name to any attributes or qualifiers     that may have been present.     """      items = get_items(d, name)     if items:         return dict(items)     else:         return {}  def values_from_items(items):     return map(lambda x: x[0], items)  def get_values(d, name, all=True):     if d.has_key(name):         items = d[name]         if not all and len(items) == 1:             return items[0][0]         else:             return values_from_items(items)     else:         return None  def get_value(d, name):     return get_values(d, name, False)  def get_date_value_items(d, name, tzid=None):      """     Obtain items from 'd' having the given 'name', where a single item yields     potentially many values. Return a list of tuples of the form (value,     attributes) where the attributes have been given for the property in 'd'.     """      items = get_items(d, name)     if items:         all_items = []         for item in items:             values, attr = item             if not attr.has_key("TZID") and tzid:                 attr["TZID"] = tzid             if not isinstance(values, list):                 values = [values]             for value in values:                 all_items.append((get_datetime(value, attr) or get_period(value, attr), attr))         return all_items     else:         return None  def get_date_value_item_periods(d, name, duration, tzid=None):      """     Obtain items from 'd' having the given 'name', where a single item yields     potentially many values. The 'duration' must be provided to define the     length of periods having only a start datetime. Return a list of periods     corresponding to the property in 'd'.     """      items = get_date_value_items(d, name, tzid)     if not items:         return items      periods = []      for value, attr in items:         if isinstance(value, tuple):             periods.append(RecurringPeriod(value[0], value[1], tzid, name, attr))         else:             periods.append(RecurringPeriod(value, value + duration, tzid, name, attr))      return periods  def get_period_values(d, name, tzid=None):      """     Return period values from 'd' for the given property 'name', using 'tzid'     where specified to indicate the time zone.     """      values = []     for value, attr in get_items(d, name) or []:         if not attr.has_key("TZID") and tzid:             attr["TZID"] = tzid         start, end = get_period(value, attr)         values.append(Period(start, end, tzid=tzid))     return values  def get_utc_datetime(d, name, date_tzid=None):      """     Return the value provided by 'd' for 'name' as a datetime in the UTC zone     or as a date, converting any date to a datetime if 'date_tzid' is specified.     If no datetime or date is available, None is returned.     """      t = get_datetime_item(d, name)     if not t:         return None     else:         dt, attr = t         return dt is not None and to_utc_datetime(dt, date_tzid) or None  def get_datetime_item(d, name):      """     Return the value provided by 'd' for 'name' as a datetime or as a date,     together with the attributes describing it. Return None if no value exists     for 'name' in 'd'.     """      t = get_item(d, name)     if not t:         return None     else:         value, attr = t         dt = get_datetime(value, attr)         tzid = get_datetime_tzid(dt)         if tzid:             attr["TZID"] = tzid         return dt, attr  # Conversion functions.  def get_address_parts(values):      "Return name and address tuples for each of the given 'values'."      l = []     for name, address in values and email.utils.getaddresses(values) or []:         if is_mailto_uri(name):             name = name[7:] # strip "mailto:"         l.append((name, address))     return l  def get_addresses(values):      """     Return only addresses from the given 'values' which may be of the form     "Common Name <recipient@domain>", with the latter part being the address     itself.     """      return [address for name, address in get_address_parts(values)]  def get_address(value):      "Return an e-mail address from the given 'value'."      if not value: return None     return get_addresses([value])[0]  def get_verbose_address(value, attr=None):      """     Return a verbose e-mail address featuring any name from the given 'value'     and any accompanying 'attr' dictionary.     """      l = get_address_parts([value])     if not l:         return value     name, address = l[0]     if not name:         name = attr and attr.get("CN")     if name and address:         return "%s <%s>" % (name, address)     else:         return address  def is_mailto_uri(value):     return value.lower().startswith("mailto:")  def get_uri(value):      "Return a URI for the given 'value'."      if not value: return None     return is_mailto_uri(value) and ("mailto:%s" % value[7:]) or \            ":" in value and value or \            "mailto:%s" % get_address(value)  def uri_parts(values):      "Return any common name plus the URI for each of the given 'values'."      return [(name, get_uri(address)) for name, address in get_address_parts(values)]  uri_value = get_uri  def uri_values(values):     return map(get_uri, values)  def uri_dict(d):     return dict([(get_uri(key), value) for key, value in d.items()])  def uri_item(item):     return get_uri(item[0]), item[1]  def uri_items(items):     return [(get_uri(value), attr) for value, attr in items]  # Operations on structure data.  def is_new_object(old_sequence, new_sequence, old_dtstamp, new_dtstamp, ignore_dtstamp):      """     Return for the given 'old_sequence' and 'new_sequence', 'old_dtstamp' and     'new_dtstamp', and the 'ignore_dtstamp' indication, whether the object     providing the new information is really newer than the object providing the     old information.     """      have_sequence = old_sequence is not None and new_sequence is not None     is_same_sequence = have_sequence and int(new_sequence) == int(old_sequence)      have_dtstamp = old_dtstamp and new_dtstamp     is_old_dtstamp = have_dtstamp and new_dtstamp < old_dtstamp or old_dtstamp and not new_dtstamp      is_old_sequence = have_sequence and (         int(new_sequence) < int(old_sequence) or         is_same_sequence and is_old_dtstamp         )      return is_same_sequence and ignore_dtstamp or not is_old_sequence  def get_periods(obj, tzid, end=None, inclusive=False):      """     Return periods for the given object 'obj', employing the given 'tzid' where     no time zone information is available (for whole day events, for example),     confining materialised periods to before the given 'end' datetime.      If 'end' is omitted, only explicit recurrences and recurrences from     explicitly-terminated rules will be returned.      If 'inclusive' is set to a true value, any period occurring at the 'end'     will be included.     """      rrule = obj.get_value("RRULE")     parameters = rrule and get_parameters(rrule)      # Use localised datetimes.      main_period = obj.get_main_period(tzid)      dtstart = main_period.get_start()     dtstart_attr = main_period.get_start_attr()      # Attempt to get time zone details from the object, using the supplied zone     # only as a fallback.      obj_tzid = obj.get_tzid()      if not rrule:         periods = [main_period]      elif end or parameters and parameters.has_key("UNTIL") or parameters.has_key("COUNT"):          # Recurrence rules create multiple instances to be checked.         # Conflicts may only be assessed within a period defined by policy         # for the agent, with instances outside that period being considered         # unchecked.          selector = get_rule(dtstart, rrule)         periods = []          until = parameters.get("UNTIL")         if until:             until_dt = to_timezone(get_datetime(until, dtstart_attr), obj_tzid)             end = end and min(until_dt, end) or until_dt             inclusive = True          for recurrence_start in selector.materialise(dtstart, end, parameters.get("COUNT"), parameters.get("BYSETPOS"), inclusive):             create = len(recurrence_start) == 3 and date or datetime             recurrence_start = to_timezone(create(*recurrence_start), obj_tzid)             recurrence_end = recurrence_start + main_period.get_duration()             periods.append(RecurringPeriod(recurrence_start, recurrence_end, tzid, "RRULE", dtstart_attr))      else:         periods = []      # Add recurrence dates.      rdates = obj.get_date_value_item_periods("RDATE", tzid)     if rdates:         periods += rdates      # Return a sorted list of the periods.      periods.sort()      # Exclude exception dates.      exdates = obj.get_date_value_item_periods("EXDATE", tzid)      if exdates:         for period in exdates:             i = bisect_left(periods, period)             while i < len(periods) and periods[i] == period:                 del periods[i]      return periods  def get_sender_identities(mapping):      """     Return a mapping from actual senders to the identities for which they     have provided data, extracting this information from the given     'mapping'.     """      senders = {}      for value, attr in mapping.items():         sent_by = attr.get("SENT-BY")         if sent_by:             sender = get_uri(sent_by)         else:             sender = value          if not senders.has_key(sender):             senders[sender] = []          senders[sender].append(value)      return senders  def get_window_end(tzid, days=100):      """     Return a datetime in the time zone indicated by 'tzid' marking the end of a     window of the given number of 'days'.     """      return to_timezone(datetime.now(), tzid) + timedelta(days)  # vim: tabstop=4 expandtab shiftwidth=4