# HG changeset patch
# User Matti Hamalainen <ccr@tnsp.org>
# Date 1476792355 -10800
# Node ID 1f7967aa013333fc84b2b0c15d3d1a308bac88ab
# Parent  f671602635b7dd9316634830370239c7fefd4a2c
Improve and add comments.

diff -r f671602635b7 -r 1f7967aa0133 multimerge.py
--- a/multimerge.py	Tue Oct 18 14:39:59 2016 +0300
+++ b/multimerge.py	Tue Oct 18 15:05:55 2016 +0300
@@ -33,13 +33,16 @@
 
 
 ###
-### Misc. helper functions
+### Misc. helper functions, etc
 ###
+
+## List of event tuple fields that should NOT be compared for equality
 gcm_no_compare_fields = [
     "id", "iCalUID", "etag", "sequence", "gcm_cal_id",
     "created", "updated", "htmlLink", "organizer", "creator",
 ]
 
+## List of logging levels from lowest to highest
 gcm_log_levels = ["CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG"]
 
 
@@ -58,11 +61,11 @@
         print(smsg.encode("UTF-8"))
 
 
-## Fatal errors
+## Fatal error handler
 def gcm_fatal(smsg):
     gcm_print(u"ERROR: "+ smsg)
     if cfg.email_ok and cfg.email != "off":
-        ## If e-mail is set, send e-mail
+        ## If e-mail is not "off", send e-mail
         msg = MIMEText(("\n".join(gcm_msgbuf)).encode("UTF-8"), "plain")
         msg.set_charset("UTF-8")
         msg["Subject"] = cfg.email_subject
@@ -70,6 +73,7 @@
         msg["To"] = ",".join(cfg.email_to)
         gcm_print("Sending mail to {0} from {1}, subj: {2} ..".format(";".join(cfg.email_to), cfg.email_sender, cfg.email_subject))
         try:
+            # Act based on email mode
             if cfg.email == "smtp":
                 gcm_print("Using SMTP server {0}, login {1}".format(cfg.email_smtp_server, cfg.email_smtp_user))
                 server = smtplib.SMTP(cfg.email_smtp_server)
@@ -129,6 +133,7 @@
     return credentials
 
 
+## Dump/print a given list of events for debugging purposes
 def gcm_dump_events(events, show):
     for event in events:
         if show == None or show(event):
@@ -159,7 +164,7 @@
     return None
 
 
-
+## Compare two given events for equality (except for excluded list of fields)
 def gcm_compare_events(ev1, ev2):
     for field in ev1:
         if not field in gcm_no_compare_fields and ev1[field] != ev2[field]:
@@ -398,7 +403,7 @@
 gcm_bench_start = time.time()
 
 
-## Settings
+## Define all the settings
 cfg_section = "gcm"
 cfg = GCMSettings()
 
@@ -438,7 +443,7 @@
 cfg.mdef("credential_file", True, cfg.is_filename, None, "client_credentials.json")
 
 
-## Check arguments
+## Check if we have arguments
 if len(sys.argv) <= 1:
     gcm_fatal(u"No configuration file specified.\nUsage: {0} <configfile>".format(sys.argv[0]))
 
@@ -557,18 +562,20 @@
     gcm_debug(3, u"Target calendar '{0}' [ ID: {1} ]".format(dst_calendar["summary"], dst_calendar["id"]))
 
 
-## Fetch colors
+## Fetch calendar colors data
 try:
     colors = service.colors().get().execute()
 except Exception as e:
     gcm_fatal(u"Failed to fetch calendar color settings:\n\n{0}".format(str(e)))
 
 
-## Now, we fetch and collect events
+## Now, fetch and collect events from source calendars
 gcm_debug(3, u"Fetching calendar events .. ")
 src_events = []
 for calendar in src_calendars:
     gcm_debug(4, u"- {0} ({1})".format(calendar["id"], calendar["summary"]))
+
+    # Find matching color from the source calendar for the event, if one has been set
     c_found = None
     if "colorId" in calendar and calendar["colorId"] in colors["calendar"]:
         gcm_debug(4, u"  Calendar color: {0}".format(colors["calendar"][calendar["colorId"]]))
@@ -578,26 +585,29 @@
         else:
             gcm_debug(4, u"  No matching event color found!")
 
-    # Add events, if any, to main list
+    # Fetch and add events, if any, to main source events list
     events = gcm_generate_ids(gcm_fetch_events(calendar["id"], False), calendar["id"], "___", "id")
     if events:
         for event in events:
+            # Set summary and color for existing events
             if event["status"] != u"cancelled":
                 if c_found != None:
                     event["colorId"] = c_found
                 event["summary"] = u"[{1}] {0}".format(event["summary"], calendar["gcm_id"])
+
+        # Add to list of source events
         src_events.extend(events)
         if gcm_check_debug(4):
             gcm_dump_events(events, (lambda ev: ev["status"] != u"cancelled"))
 
 
-## Get current events
+## Fetch current events from the target
 gcm_debug(3, u"Fetching current target calendar events.")
 dst_events = gcm_generate_ids(gcm_fetch_events(cfg.dst_id, True), "", "", "iCalUID")
 gcm_debug(3, u"Found {0} event(s).".format(len(dst_events)))
 
 
-## Start merging events ..
+## Start populating/updating events ..
 gcm_debug(3, u"Re-merging events to target calendar ..")
 dst_ids = frozenset(map(lambda x: x["gcm_id"], dst_events))
 src_ids = frozenset(map(lambda x: x["gcm_id"], src_events))
@@ -625,7 +635,7 @@
             evn_unchanged += 1
             gcm_debug(4, u"No need to update event {0} [{1}]".format(event["id"], event["gcm_id"]))
     elif event["status"] != u"cancelled":
-        ## Event does not seem to exist. Insert new event.
+        # Event does not seem to exist. Insert new event.
         gcm_debug(4, u"Inserting new event {0} [{1}]".format(event["id"], event["gcm_id"]))
         event.pop("id", None)
         event["iCalUID"] = event["gcm_id"]     # Replace Google generated ID with our own