#!/usr/bin/env python  """ Common calendar client utilities.  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 datetime import datetime, timedelta from imiptools import config from imiptools.data import Object, get_address, get_uri, get_window_end, \                            is_new_object, make_freebusy, to_part, \                            uri_dict, uri_items, uri_values from imiptools.dates import check_permitted_values, format_datetime, get_default_timezone, \                             get_duration, get_time, get_timestamp from imiptools.period import can_schedule, remove_period, \                              remove_additional_periods, remove_affected_period, \                              update_freebusy from imiptools.profile import Preferences import imip_store  class Client:      "Common handler and manager methods."      default_window_size = 100     organiser_methods = "ADD", "CANCEL", "DECLINECOUNTER", "PUBLISH", "REQUEST"      def __init__(self, user, messenger=None, store=None, publisher=None, preferences_dir=None):          """         Initialise a calendar client with the current 'user', plus any         'messenger', 'store' and 'publisher' objects, indicating any specific         'preferences_dir'.         """          self.user = user         self.messenger = messenger         self.store = store or imip_store.FileStore()          try:             self.publisher = publisher or imip_store.FilePublisher()         except OSError:             self.publisher = None          self.preferences_dir = preferences_dir         self.preferences = None      # Store-related methods.      def acquire_lock(self):         self.store.acquire_lock(self.user)      def release_lock(self):         self.store.release_lock(self.user)      # Preferences-related methods.      def get_preferences(self):         if not self.preferences and self.user:             self.preferences = Preferences(self.user, self.preferences_dir)         return self.preferences      def get_user_attributes(self):         prefs = self.get_preferences()         return prefs and prefs.get_all(["CN"]) or {}      def get_tzid(self):         prefs = self.get_preferences()         return prefs and prefs.get("TZID") or get_default_timezone()      def get_window_size(self):         prefs = self.get_preferences()         try:             return prefs and int(prefs.get("window_size")) or self.default_window_size         except (TypeError, ValueError):             return self.default_window_size      def get_window_end(self):         return get_window_end(self.get_tzid(), self.get_window_size())      def is_participating(self):          "Return participation in the calendar system."          prefs = self.get_preferences()         return prefs and prefs.get("participating", config.PARTICIPATING_DEFAULT) != "no" or False      def is_sharing(self):          "Return whether free/busy information is being generally shared."          prefs = self.get_preferences()         return prefs and prefs.get("freebusy_sharing", config.SHARING_DEFAULT) == "share" or False      def is_bundling(self):          "Return whether free/busy information is being bundled in messages."          prefs = self.get_preferences()         return prefs and prefs.get("freebusy_bundling", config.BUNDLING_DEFAULT) == "always" or False      def is_notifying(self):          "Return whether recipients are notified about free/busy payloads."          prefs = self.get_preferences()         return prefs and prefs.get("freebusy_messages", config.NOTIFYING_DEFAULT) == "notify" or False      def is_publishing(self):          "Return whether free/busy information is being published as Web resources."          prefs = self.get_preferences()         return prefs and prefs.get("freebusy_publishing", config.PUBLISHING_DEFAULT) == "publish" or False      def is_refreshing(self):          "Return whether a recipient supports requests to refresh event details."          prefs = self.get_preferences()         return prefs and prefs.get("event_refreshing", config.REFRESHING_DEFAULT) == "always" or False      def allow_add(self):         return self.get_add_method_response() in ("add", "refresh")      def get_add_method_response(self):         prefs = self.get_preferences()         return prefs and prefs.get("add_method_response", config.ADD_RESPONSE_DEFAULT) or "refresh"      def get_offer_period(self):          "Decode a specification in the iCalendar duration format."          prefs = self.get_preferences()         duration = prefs and prefs.get("freebusy_offers", config.FREEBUSY_OFFER_DEFAULT)          # NOTE: Should probably report an error somehow if None.          return duration and get_duration(duration) or None      def get_organiser_replacement(self):         prefs = self.get_preferences()         return prefs and prefs.get("organiser_replacement", config.ORGANISER_REPLACEMENT_DEFAULT) or "attendee"      def have_manager(self):         return config.MANAGER_INTERFACE      def get_permitted_values(self):          """         Decode a specification of one of the following forms...          <minute values>         <hour values>:<minute values>         <hour values>:<minute values>:<second values>          ...with each list of values being comma-separated.         """          prefs = self.get_preferences()         permitted_values = prefs and prefs.get("permitted_times")         if permitted_values:             try:                 l = []                 for component in permitted_values.split(":")[:3]:                     if component:                         l.append(map(int, component.split(",")))                     else:                         l.append(None)              # NOTE: Should probably report an error somehow.              except ValueError:                 return None             else:                 l = (len(l) < 2 and [None] or []) + l + (len(l) < 3 and [None] or [])                 return l         else:             return None      # Common operations on calendar data.      def update_attendees(self, obj, attendees, removed):          """         Update the attendees in 'obj' with the given 'attendees' and 'removed'         attendee lists. A list is returned containing the attendees whose         attendance should be cancelled.         """          to_cancel = []          existing_attendees = uri_values(obj.get_values("ATTENDEE") or [])         added = set(attendees).difference(existing_attendees)          if added or removed:             attendees = uri_items(obj.get_items("ATTENDEE") or [])             sequence = obj.get_value("SEQUENCE")              if removed:                 remaining = []                  for attendee, attendee_attr in attendees:                     if attendee in removed:                          # Without a sequence number, assume that the event has not                         # been published and that attendees can be silently removed.                          if sequence is not None:                             to_cancel.append((attendee, attendee_attr))                     else:                         remaining.append((attendee, attendee_attr))                  attendees = remaining              if added:                 for attendee in added:                     attendee = attendee.strip()                     if attendee:                         attendees.append((get_uri(attendee), {"PARTSTAT" : "NEEDS-ACTION", "RSVP" : "TRUE"}))              obj["ATTENDEE"] = attendees          return to_cancel      def update_participation(self, obj, partstat=None):          """         Update the participation in 'obj' of the user with the given 'partstat'.         """          attendee_attr = uri_dict(obj.get_value_map("ATTENDEE")).get(self.user)         if not attendee_attr:             return None         if partstat:             attendee_attr["PARTSTAT"] = partstat         if attendee_attr.has_key("RSVP"):             del attendee_attr["RSVP"]         self.update_sender(attendee_attr)         return attendee_attr      def update_sender(self, attr):          "Update the SENT-BY attribute of the 'attr' sender metadata."          if self.messenger and self.messenger.sender != get_address(self.user):             attr["SENT-BY"] = get_uri(self.messenger.sender)      def get_periods(self, obj):          """         Return periods for the given 'obj'. Interpretation of periods can depend         on the time zone, which is obtained for the current user.         """          return obj.get_periods(self.get_tzid(), self.get_window_end())      # Store operations.      def get_stored_object(self, uid, recurrenceid, section=None, username=None):          """         Return the stored object for the current user, with the given 'uid' and         'recurrenceid' from the given 'section' and for the given 'username' (if         specified), or from the standard object collection otherwise.         """          if section == "counters":             fragment = self.store.get_counter(self.user, username, uid, recurrenceid)         else:             fragment = self.store.get_event(self.user, uid, recurrenceid)         return fragment and Object(fragment)      # Free/busy operations.      def get_freebusy_part(self, freebusy=None):          """         Return a message part containing free/busy information for the user,         either specified as 'freebusy' or obtained from the store directly.         """          if self.is_sharing() and self.is_bundling():              # Invent a unique identifier.              utcnow = get_timestamp()             uid = "imip-agent-%s-%s" % (utcnow, get_address(self.user))              freebusy = freebusy or self.store.get_freebusy(self.user)              user_attr = {}             self.update_sender(user_attr)             return to_part("PUBLISH", [make_freebusy(freebusy, uid, self.user, user_attr)])          return None      def update_freebusy(self, freebusy, periods, transp, uid, recurrenceid, summary, organiser, expires=None):          """         Update the 'freebusy' collection with the given 'periods', indicating a         'transp' status, explicit 'uid' and 'recurrenceid' to indicate either a         recurrence or the parent event. The 'summary' and 'organiser' must also         be provided.          An optional 'expires' datetime string can be provided to tag a free/busy         offer.         """          update_freebusy(freebusy, periods, transp, uid, recurrenceid, summary, organiser, expires)  class ClientForObject(Client):      "A client maintaining a specific object."      def __init__(self, obj, user, messenger=None, store=None, publisher=None, preferences_dir=None):         Client.__init__(self, user, messenger, store, publisher, preferences_dir)         self.set_object(obj)      def set_object(self, obj):          "Set the current object to 'obj', obtaining metadata details."          self.obj = obj         self.uid = obj and self.obj.get_uid()         self.recurrenceid = obj and self.obj.get_recurrenceid()         self.sequence = obj and self.obj.get_value("SEQUENCE")         self.dtstamp = obj and self.obj.get_value("DTSTAMP")      def set_identity(self, method):          """         Set the current user for the current object in the context of the given         'method'. It is usually set when initialising the handler, using the         recipient details, but outgoing messages do not reference the recipient         in this way.         """          pass      def is_usable(self, method=None):          "Return whether the current object is usable with the given 'method'."          return True      # Object update methods.      def update_recurrenceid(self):          """         Update the RECURRENCE-ID in the current object, initialising it from         DTSTART.         """          self.obj["RECURRENCE-ID"] = [self.obj.get_item("DTSTART")]         self.recurrenceid = self.obj.get_recurrenceid()      def update_dtstamp(self):          "Update the DTSTAMP in the current object."          dtstamp = self.obj.get_utc_datetime("DTSTAMP")         utcnow = get_time()         self.dtstamp = format_datetime(dtstamp and dtstamp > utcnow and dtstamp or utcnow)         self.obj["DTSTAMP"] = [(self.dtstamp, {})]      def set_sequence(self, increment=False):          "Update the SEQUENCE in the current object."          sequence = self.obj.get_value("SEQUENCE") or "0"         self.obj["SEQUENCE"] = [(str(int(sequence) + (increment and 1 or 0)), {})]      def merge_attendance(self, attendees):          """         Merge attendance from the current object's 'attendees' into the version         stored for the current user.         """          obj = self.get_stored_object_version()          if not obj or not self.have_new_object():             return False          # Get attendee details in a usable form.          attendee_map = uri_dict(obj.get_value_map("ATTENDEE"))          for attendee, attendee_attr in attendees.items():              # Update attendance in the loaded object.              attendee_map[attendee] = attendee_attr          # Set the new details and store the object.          obj["ATTENDEE"] = attendee_map.items()          # Set a specific recurrence or the complete event if not an additional         # occurrence.          self.store.set_event(self.user, self.uid, self.recurrenceid, obj.to_node())          return True      # Object-related tests.      def is_recognised_organiser(self, organiser):          """         Return whether the given 'organiser' is recognised from         previously-received details. If no stored details exist, True is         returned.         """          obj = self.get_stored_object_version()         if obj:             stored_organiser = get_uri(obj.get_value("ORGANIZER"))             return stored_organiser == organiser         else:             return True      def is_recognised_attendee(self, attendee):          """         Return whether the given 'attendee' is recognised from         previously-received details. If no stored details exist, True is         returned.         """          obj = self.get_stored_object_version()         if obj:             stored_attendees = uri_dict(obj.get_value_map("ATTENDEE"))             return stored_attendees.has_key(attendee)         else:             return True      def get_attendance(self, user=None, obj=None):          """         Return the attendance attributes for 'user', or the current user if         'user' is not specified.         """          attendees = uri_dict((obj or self.obj).get_value_map("ATTENDEE"))         return attendees.get(user or self.user)      def is_participating(self, user, as_organiser=False, obj=None):          """         Return whether, subject to the 'user' indicating an identity and the         'as_organiser' status of that identity, the user concerned is actually         participating in the current object event.         """          # Use any attendee property information for an organiser, not the         # organiser property attributes.          attr = self.get_attendance(user, obj=obj)         return as_organiser or attr is not None and not attr or attr and attr.get("PARTSTAT") != "DECLINED"      def get_overriding_transparency(self, user, as_organiser=False):          """         Return the overriding transparency to be associated with the free/busy         records for an event, subject to the 'user' indicating an identity and         the 'as_organiser' status of that identity.          Where an identity is only an organiser and not attending, "ORG" is         returned. Otherwise, no overriding transparency is defined and None is         returned.         """          attr = self.get_attendance(user)         return as_organiser and not (attr and attr.get("PARTSTAT")) and "ORG" or None      def can_schedule(self, freebusy, periods):          """         Indicate whether within 'freebusy' the given 'periods' can be scheduled.         """          return can_schedule(freebusy, periods, self.uid, self.recurrenceid)      def have_new_object(self, strict=True):          """         Return whether the current object is new to the current user.          If 'strict' is specified and is a false value, the DTSTAMP test will be         ignored. This is useful in handling responses from attendees from         clients (like Claws Mail) that erase time information from DTSTAMP and         make it invalid.         """          obj = self.get_stored_object_version()          # If found, compare SEQUENCE and potentially DTSTAMP.          if obj:             sequence = obj.get_value("SEQUENCE")             dtstamp = obj.get_value("DTSTAMP")              # If the request refers to an older version of the object, ignore             # it.              return is_new_object(sequence, self.sequence, dtstamp, self.dtstamp, not strict)          return True      def possibly_recurring_indefinitely(self):          "Return whether the object recurs indefinitely."          # Obtain the stored object to make sure that recurrence information         # is not being ignored. This might happen if a client sends a         # cancellation without the complete set of properties, for instance.          return self.obj.possibly_recurring_indefinitely() or \                self.get_stored_object_version() and \                self.get_stored_object_version().possibly_recurring_indefinitely()      # Constraint application on event periods.      def check_object(self):          "Check the object against any scheduling constraints."          permitted_values = self.get_permitted_values()         if not permitted_values:             return None          invalid = []          for period in self.obj.get_periods(self.get_tzid()):             start = period.get_start()             end = period.get_end()             start_errors = check_permitted_values(start, permitted_values)             end_errors = check_permitted_values(end, permitted_values)             if start_errors or end_errors:                 invalid.append((period.origin, start_errors, end_errors))          return invalid      def correct_object(self):          "Correct the object according to any scheduling constraints."          permitted_values = self.get_permitted_values()         return permitted_values and self.obj.correct_object(self.get_tzid(), permitted_values)      # Object retrieval.      def get_stored_object_version(self):          """         Return the stored object to which the current object refers for the         current user.         """          return self.get_stored_object(self.uid, self.recurrenceid)      def get_definitive_object(self, as_organiser):          """         Return an object considered definitive for the current transaction,         using 'as_organiser' to select the current transaction's object if         false, or selecting a stored object if true.         """          return not as_organiser and self.obj or self.get_stored_object_version()      def get_parent_object(self):          """         Return the parent object to which the current object refers for the         current user.         """          return self.recurrenceid and self.get_stored_object(self.uid, None) or None      # Convenience methods for modifying free/busy collections.      def get_recurrence_start_point(self, recurrenceid):          "Get 'recurrenceid' in a form suitable for matching free/busy entries."          return self.obj.get_recurrence_start_point(recurrenceid, self.get_tzid())      def remove_from_freebusy(self, freebusy):          "Remove this event from the given 'freebusy' collection."          if not remove_period(freebusy, self.uid, self.recurrenceid) and self.recurrenceid:             remove_affected_period(freebusy, self.uid, self.get_recurrence_start_point(self.recurrenceid))      def remove_freebusy_for_recurrences(self, freebusy, recurrenceids=None):          """         Remove from 'freebusy' any original recurrence from parent free/busy         details for the current object, if the current object is a specific         additional recurrence. Otherwise, remove all additional recurrence         information corresponding to 'recurrenceids', or if omitted, all         recurrences.         """          if self.recurrenceid:             recurrenceid = self.get_recurrence_start_point(self.recurrenceid)             remove_affected_period(freebusy, self.uid, recurrenceid)         else:             # Remove obsolete recurrence periods.              remove_additional_periods(freebusy, self.uid, recurrenceids)              # Remove original periods affected by additional recurrences.              if recurrenceids:                 for recurrenceid in recurrenceids:                     recurrenceid = self.get_recurrence_start_point(recurrenceid)                     remove_affected_period(freebusy, self.uid, recurrenceid)      def update_freebusy(self, freebusy, user, as_organiser, offer=False):          """         Update the 'freebusy' collection for this event with the periods and         transparency associated with the current object, subject to the 'user'         identity and the attendance details provided for them, indicating         whether the update is being done 'as_organiser' (for the organiser of         an event) or not.          If 'offer' is set to a true value, any free/busy updates will be tagged         with an expiry time.         """          # Obtain the stored object if the current object is not issued by the         # organiser. Attendees do not have the opportunity to redefine the         # periods.          obj = self.get_definitive_object(as_organiser)         if not obj:             return          # Obtain the affected periods.          periods = self.get_periods(obj)          # Define an overriding transparency, the indicated event transparency,         # or the default transparency for the free/busy entry.          transp = self.get_overriding_transparency(user, as_organiser) or \                  obj.get_value("TRANSP") or \                  "OPAQUE"          # Calculate any expiry time. If no offer period is defined, do not         # record the offer periods.          if offer:             offer_period = self.get_offer_period()             if offer_period:                 expires = get_timestamp(offer_period)             else:                 return         else:             expires = None          # Perform the low-level update.          Client.update_freebusy(self, freebusy, periods, transp,             self.uid, self.recurrenceid,             obj.get_value("SUMMARY"),             obj.get_value("ORGANIZER"),             expires)      def update_freebusy_for_participant(self, freebusy, user, for_organiser=False,                                         updating_other=False, offer=False):          """         Update the 'freebusy' collection for the given 'user', indicating         whether the update is 'for_organiser' (being done for the organiser of         an event) or not, and whether it is 'updating_other' (meaning another         user's details).          If 'offer' is set to a true value, any free/busy updates will be tagged         with an expiry time.         """          # Record in the free/busy details unless a non-participating attendee.         # Remove periods for non-participating attendees.          if offer or self.is_participating(user, for_organiser and not updating_other):             self.update_freebusy(freebusy, user,                 for_organiser and not updating_other or                 not for_organiser and updating_other,                 offer                 )         else:             self.remove_from_freebusy(freebusy)      def remove_freebusy_for_participant(self, freebusy, user, for_organiser=False,                                         updating_other=False):          """         Remove details from the 'freebusy' collection for the given 'user',         indicating whether the modification is 'for_organiser' (being done for         the organiser of an event) or not, and whether it is 'updating_other'         (meaning another user's details).         """          # Remove from the free/busy details if a specified attendee.          if self.is_participating(user, for_organiser and not updating_other):             self.remove_from_freebusy(freebusy)      # Convenience methods for updating stored free/busy information received     # from other users.      def update_freebusy_from_participant(self, user, for_organiser, fn=None):          """         For the current user, record the free/busy information for another         'user', indicating whether the update is 'for_organiser' or not, thus         maintaining a separate record of their free/busy details.         """          fn = fn or self.update_freebusy_for_participant          # A user does not store free/busy information for themself as another         # party.          if user == self.user:             return          self.acquire_lock()         try:             freebusy = self.store.get_freebusy_for_other(self.user, user)             fn(freebusy, user, for_organiser, True)              # Tidy up any obsolete recurrences.              self.remove_freebusy_for_recurrences(freebusy, self.store.get_recurrences(self.user, self.uid))             self.store.set_freebusy_for_other(self.user, freebusy, user)          finally:             self.release_lock()      def update_freebusy_from_organiser(self, organiser):          "For the current user, record free/busy information from 'organiser'."          self.update_freebusy_from_participant(organiser, True)      def update_freebusy_from_attendees(self, attendees):          "For the current user, record free/busy information from 'attendees'."          for attendee in attendees.keys():             self.update_freebusy_from_participant(attendee, False)      def remove_freebusy_from_organiser(self, organiser):          "For the current user, remove free/busy information from 'organiser'."          self.update_freebusy_from_participant(organiser, True, self.remove_freebusy_for_participant)      def remove_freebusy_from_attendees(self, attendees):          "For the current user, remove free/busy information from 'attendees'."          for attendee in attendees.keys():             self.update_freebusy_from_participant(attendee, False, self.remove_freebusy_for_participant)      # Convenience methods for updating free/busy details at the event level.      def update_event_in_freebusy(self, for_organiser=True):          """         Update free/busy information when handling an object, doing so for the         organiser of an event if 'for_organiser' is set to a true value.         """          freebusy = self.store.get_freebusy(self.user)          # Obtain the attendance attributes for this user, if available.          self.update_freebusy_for_participant(freebusy, self.user, for_organiser)          # Remove original recurrence details replaced by additional         # recurrences, as well as obsolete additional recurrences.          self.remove_freebusy_for_recurrences(freebusy, self.store.get_recurrences(self.user, self.uid))         self.store.set_freebusy(self.user, freebusy)          if self.publisher and self.is_sharing() and self.is_publishing():             self.publisher.set_freebusy(self.user, freebusy)          # Update free/busy provider information if the event may recur         # indefinitely.          if self.possibly_recurring_indefinitely():             self.store.append_freebusy_provider(self.user, self.obj)          return True      def remove_event_from_freebusy(self):          "Remove free/busy information when handling an object."          freebusy = self.store.get_freebusy(self.user)          self.remove_from_freebusy(freebusy)         self.remove_freebusy_for_recurrences(freebusy)         self.store.set_freebusy(self.user, freebusy)          if self.publisher and self.is_sharing() and self.is_publishing():             self.publisher.set_freebusy(self.user, freebusy)          # Update free/busy provider information if the event may recur         # indefinitely.          if self.possibly_recurring_indefinitely():             self.store.remove_freebusy_provider(self.user, self.obj)      def update_event_in_freebusy_offers(self):          "Update free/busy offers when handling an object."          freebusy = self.store.get_freebusy_offers(self.user)          # Obtain the attendance attributes for this user, if available.          self.update_freebusy_for_participant(freebusy, self.user, offer=True)          # Remove original recurrence details replaced by additional         # recurrences, as well as obsolete additional recurrences.          self.remove_freebusy_for_recurrences(freebusy, self.store.get_recurrences(self.user, self.uid))         self.store.set_freebusy_offers(self.user, freebusy)          return True      def remove_event_from_freebusy_offers(self):          "Remove free/busy offers when handling an object."          freebusy = self.store.get_freebusy_offers(self.user)          self.remove_from_freebusy(freebusy)         self.remove_freebusy_for_recurrences(freebusy)         self.store.set_freebusy_offers(self.user, freebusy)          return True  # vim: tabstop=4 expandtab shiftwidth=4