Merge pull request #109 from shotgunsoftware/ticket/35260_sgtimezone_scoping

For #35260: Refactoring scoping of sgtimezone to support serialization

Author: victoriagrey

shotgun_api3/lib/sgtimezone.py

@@ -5,9 +5,15 @@
 #  current users of api2 to install new modules and modify PYTHONPATH info.
 # ----------------------------------------------------------------------------
 
+from datetime import tzinfo, timedelta, datetime
+import time as _time
+
 class SgTimezone(object):
-    from datetime import tzinfo, timedelta, datetime
-    import time as _time
+    '''
+    Shotgun's server infrastructure is configured for Coordinated Universal
+    Time (UTC). In order to provide relevant local timestamps to users, we wrap
+    the datetime module's tzinfo to provide convenient conversion methods.
+    '''
 
     ZERO = timedelta(0)
     STDOFFSET = timedelta(seconds = -_time.timezone)
@@ -18,41 +24,76 @@ class SgTimezone(object):
     DSTDIFF = DSTOFFSET - STDOFFSET
 
     def __init__(self): 
-        self.utc = self.UTC()
-        self.local = self.LocalTimezone()
+        self.utc = UTC()
+        self.local = LocalTimezone()
+
+    @classmethod
+    def UTC(cls):
+        '''
+        For backwards compatibility, from when UTC was a nested class,
+        we allow instantiation via SgTimezone
+        '''
+        return UTC()
+
+    @classmethod
+    def LocalTimezone(cls):
+        '''
+        For backwards compatibility, from when LocalTimezone was a nested
+        class, we allow instantiation via SgTimezone
+        '''
+        return LocalTimezone()
 
-    class UTC(tzinfo):
-        
-        def utcoffset(self, dt):
-            return SgTimezone.ZERO
-        
-        def tzname(self, dt):
-            return "UTC"
-        
-        def dst(self, dt):
-            return SgTimezone.ZERO
+class UTC(tzinfo):
+    '''
+    Implementation of datetime's tzinfo to provide consistent calculated
+    offsets against Coordinated Universal Time (UTC)
+    '''
+    
+    def utcoffset(self, dt):
+        return SgTimezone.ZERO
 
-    class LocalTimezone(tzinfo):
-        
-        def utcoffset(self, dt):
-            if self._isdst(dt):
-                return SgTimezone.DSTOFFSET
-            else:
-                return SgTimezone.STDOFFSET
-        
-        def dst(self, dt):
-            if self._isdst(dt):
-                return SgTimezone.DSTDIFF
-            else:
-                return SgTimezone.ZERO
-        
-        def tzname(self, dt):
-            return _time.tzname[self._isdst(dt)]
-        
-        def _isdst(self, dt):
-            tt = (dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second, dt.weekday(), 0, -1)
-            import time as _time
-            stamp = _time.mktime(tt)
-            tt = _time.localtime(stamp)
-            return tt.tm_isdst > 0
+    def tzname(self, dt):
+        return "UTC"
+    
+    def dst(self, dt):
+        return SgTimezone.ZERO
 
+class LocalTimezone(tzinfo):
+    '''
+    Implementation of datetime's tzinfo to provide convenient conversion
+    between Shotgun server time and local user time
+    '''
+    
+    def utcoffset(self, dt):
+        '''
+        Difference between the user's local timezone and UTC timezone in seconds
+        '''
+        if self._isdst(dt):
+            return SgTimezone.DSTOFFSET
+        else:
+            return SgTimezone.STDOFFSET
+    
+    def dst(self, dt):
+        '''
+        Daylight savings time (dst) offset in seconds
+        '''
+        if self._isdst(dt):
+            return SgTimezone.DSTDIFF
+        else:
+            return SgTimezone.ZERO
+    
+    def tzname(self, dt):
+        '''
+        Name of the user's local timezone, including a reference
+        to daylight savings time (dst) if applicable
+        '''
+        return _time.tzname[self._isdst(dt)]
+    
+    def _isdst(self, dt):
+        '''
+        Calculate whether the timestamp in question was in daylight savings
+        '''
+        tt = (dt.year, dt.month, dt.day, dt.hour, dt.minute, dt.second, dt.weekday(), 0, -1)
+        stamp = _time.mktime(tt)
+        tt = _time.localtime(stamp)
+        return tt.tm_isdst > 0