# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1438180828 -7200
# Node ID 55518c07a9ff4e9ead141e50b9226bd3e95f26ab
# Parent  11a77ae8abd909573e8844a934ef7416ee888651
Improved window-related docstrings and comments.

diff -r 11a77ae8abd9 -r 55518c07a9ff imiptools/data.py
--- a/imiptools/data.py	Wed Jul 29 16:39:08 2015 +0200
+++ b/imiptools/data.py	Wed Jul 29 16:40:28 2015 +0200
@@ -425,9 +425,12 @@
 def get_periods(obj, tzid, window_end, inclusive=False):
 
     """
-    Return periods for the given object 'obj', confining materialised periods
-    to before the given 'window_end' datetime. If 'inclusive' is set to a true
-    value, any period occurring at the 'window_end' will be included.
+    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 'window_end' datetime.
+
+    If 'inclusive' is set to a true value, any period occurring at the
+    'window_end' will be included.
     """
 
     rrule = obj.get_value("RRULE")
@@ -446,6 +449,9 @@
     else:
         dtend, dtend_attr = dtstart, dtstart_attr
 
+    # Attempt to get time zone details from the object, using the supplied zone
+    # only as a fallback.
+
     tzid = obj.get_tzid() or tzid
 
     if not rrule:
@@ -526,10 +532,13 @@
 
     return senders
 
-# NOTE: Need to expose the 100 day window for recurring events in the
-# NOTE: configuration.
+def get_window_end(tzid, days=100):
 
-def get_window_end(tzid, window_size=100):
-    return to_timezone(datetime.now(), tzid) + timedelta(window_size)
+    """
+    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