Add support for getting "aware" datetime info

This adds 2 properties to commits.  Their values are derived from the
existing data stored on them, but this makes them more conveniently
queryable:

    - authored_datetime
    - committed_datetime

These return "aware" datetimes, so they are effectively companions to
their raw timestamp equivalents, respectively `authored_date` and
`committed_date`.

These datetime instances are convenient structures since they show the
author-local commit date and their UTC offset.

1 files changed, 29 insertions, 1 deletions

diff --git a/git/objects/util.py b/git/objects/util.py
index 8fd92a0a..cbb9fe3c 100644
--- a/git/objects/util.py
+++ b/git/objects/util.py
@@ -15,10 +15,13 @@ from collections import deque as Deque
 from string import digits
 import time
 import calendar
+from datetime import datetime, timedelta, tzinfo
 
 __all__ = ('get_object_type_by_name', 'parse_date', 'parse_actor_and_date',
            'ProcessStreamAdapter', 'Traversable', 'altz_to_utctz_str', 'utctz_to_altz',
-           'verify_utctz', 'Actor')
+           'verify_utctz', 'Actor', 'tzoffset', 'utc')
+
+ZERO = timedelta(0)
 
 #{ Functions
 
@@ -97,6 +100,31 @@ def verify_utctz(offset):
     return offset
 
 
+class tzoffset(tzinfo):
+    def __init__(self, secs_west_of_utc, name=None):
+        self._offset = timedelta(seconds=-secs_west_of_utc)
+        self._name = name or 'fixed'
+
+    def utcoffset(self, dt):
+        return self._offset
+
+    def tzname(self, dt):
+        return self._name
+
+    def dst(self, dt):
+        return ZERO
+
+
+utc = tzoffset(0, 'UTC')
+
+
+def from_timestamp(timestamp, tz_offset):
+    """Converts a timestamp + tz_offset into an aware datetime instance."""
+    utc_dt = datetime.fromtimestamp(timestamp, utc)
+    local_dt = utc_dt.astimezone(tzoffset(tz_offset))
+    return local_dt
+
+
 def parse_date(string_date):
     """
     Parse the given date as one of the following