Merge lp:~oubiwann/txaws/416366-remove-epsilon into lp:txaws

[Duncan McGreggor]

[Duncan McGreggor (oubiwann)]

I've copied over particular aspects of Divmod's ISO datetime stuff (including some unit tests) for use by txaws.storage. This way, the Epslion package doesn't need to be installed by folks that want to use txaws.storage.

[lp:~oubiwann/txaws/416366-remove-epsilon]

46. By Duncan McGreggor on 2009-11-04

Fixed pyflakes.

47. By Duncan McGreggor on 2009-11-05

Fixed some formatting.

48. By Duncan McGreggor on 2009-11-05

Fixed typo.

[Duncan McGreggor (oubiwann)]

We're not going to remove Epsilon support.

review: Disapprove

Unmerged revisions

48. By Duncan McGreggor on 2009-11-05

Fixed typo.

47. By Duncan McGreggor on 2009-11-05

Fixed some formatting.

46. By Duncan McGreggor on 2009-11-04

Fixed pyflakes.

45. By Duncan McGreggor on 2009-11-04

Added unit tests for Time class.

44. By Duncan McGreggor on 2009-11-04

Removed unnecessary code.

43. By Duncan McGreggor on 2009-11-04

Removed the dependenty upon Epsilon by copying the extime module into the txAWS
util module.

=== modified file 'txaws/storage/client.py'
--- txaws/storage/client.py	2009-09-05 01:13:43 +0000
+++ txaws/storage/client.py	2009-11-05 04:20:23 +0000
@@ -7,13 +7,11 @@
 functionality in this wrapper.
 """
 
-from epsilon.extime import Time
-
 from twisted.web.client import getPage
 from twisted.web.http import datetimeToString
 
 from txaws.service import AWSServiceEndpoint
-from txaws.util import XML, calculate_md5
+from txaws.util import Time, XML, calculate_md5
 
 
 class S3Request(object):

=== modified file 'txaws/storage/tests/test_client.py'
--- txaws/storage/tests/test_client.py	2009-09-05 01:13:43 +0000
+++ txaws/storage/tests/test_client.py	2009-11-05 04:20:23 +0000
@@ -1,15 +1,12 @@
 from datetime import datetime
 
-from epsilon.extime import Time
-
 from twisted.internet.defer import succeed
 
 from txaws.credentials import AWSCredentials
 from txaws.service import AWSServiceEndpoint
 from txaws.storage.client import S3, S3Request
 from txaws.testing.base import TXAWSTestCase
-from txaws.util import calculate_md5
-
+from txaws.util import FixedOffset, calculate_md5
 
 
 class StubbedS3Request(S3Request):
@@ -219,14 +216,14 @@
         self.assertEqual(req.object_name, None)
 
         def _check_result(buckets):
+            time1 = datetime(2006, 2, 3, 16, 45, 9, 0, FixedOffset(0, 0))
+            time2 = datetime(2006, 2, 3, 16, 41, 58, 0, FixedOffset(0, 0))
             self.assertEqual(
                 list(buckets),
                 [{"name": u"quotes",
-                  "created": Time.fromDatetime(
-                    datetime(2006, 2, 3, 16, 45, 9))},
+                  "created": time1},
                  {"name": u"samples",
-                  "created": Time.fromDatetime(
-                    datetime(2006, 2, 3, 16, 41, 58))}])
+                  "created": time2}])
         return d.addCallback(_check_result)
 
     def test_create_bucket(self):

=== modified file 'txaws/tests/test_util.py'
--- txaws/tests/test_util.py	2009-09-05 00:26:12 +0000
+++ txaws/tests/test_util.py	2009-11-05 04:20:23 +0000
@@ -1,8 +1,9 @@
+from datetime import datetime, timedelta, tzinfo
 from urlparse import urlparse
 
-from twisted.trial.unittest import TestCase
+from twisted.trial.unittest import FailTest, TestCase
 
-from txaws.util import hmac_sha1, iso8601time, parse
+from txaws.util import FixedOffset, Time, hmac_sha1, iso8601time, parse
 
 class MiscellaneousTests(TestCase):
 
@@ -70,3 +71,109 @@
         self.assertTrue(isinstance(scheme, str))
         self.assertTrue(isinstance(host, str))
         self.assertTrue(isinstance(path, str))
+
+
+class TestTime(TestCase):
+    class MST(tzinfo):
+        def tzname(self, dt):
+            return 'MST'
+        def utcoffset(self, dt):
+            return timedelta(hours = -7)
+        def dst(self, dt):
+            return timedelta(0)
+
+    class CET(tzinfo):
+        def tzname(self, dt):
+            return 'MST'
+        def utcoffset(self, dt):
+            return timedelta(hours = 1)
+        def dst(self, dt):
+            return timedelta(0)
+
+    reference = datetime(2004, 12, 6, 14, 15, 16)
+    awareReference = datetime(
+        2004, 12, 6, 14, 15, 16, tzinfo=FixedOffset(0, 0))
+
+    def _createReference(self, reference=None):
+        """
+        Return a reference instance.
+        """
+        return Time.fromDatetime(reference or self.reference)
+
+    def test_insignificantTimezones(self):
+        """
+        Timezones should be insignificant when the resolution is >= 1 day
+        """
+        def testEqual(creator, input):
+            self.assertEquals(
+                creator(input), creator(input, tzinfo=self.MST()))
+
+        def testNotEqual(creator, input):
+            self.assertNotEquals(
+                creator(input), creator(input, tzinfo=self.MST()))
+
+        testEqual(Time.fromISO8601TimeAndDate, '2005')
+        testEqual(Time.fromISO8601TimeAndDate, '2005-02')
+        testEqual(Time.fromISO8601TimeAndDate, '2005-02-10')
+
+        testNotEqual(Time.fromISO8601TimeAndDate, '2005-02-10T12')
+        testNotEqual(Time.fromISO8601TimeAndDate, '2005-02-10T12:10')
+        testNotEqual(Time.fromISO8601TimeAndDate, '2005-02-10T12:10:03')
+
+    def test_fromISO8601DateAndTime(self):
+        self.assertRaises(ValueError, Time.fromISO8601TimeAndDate, '2005-W53' )
+        self.assertRaises(ValueError, Time.fromISO8601TimeAndDate, '2004-367' )
+        try:
+            Time.fromISO8601TimeAndDate('2004-366')
+        except ValueError:
+            raise FailTest, 'leap years should have 366 days'
+
+        try:
+            Time.fromISO8601TimeAndDate('2004-123T14-0600')
+            Time.fromISO8601TimeAndDate('2004-123T14:13-0600')
+            Time.fromISO8601TimeAndDate('2004-123T14:13:51-0600')
+        except ValueError:
+            raise FailTest('timezone should be allowed if time with'
+                           '*any* resolution is specified')
+
+    def test_fromDatetime(self):
+        self.assertEquals(
+            repr(Time.fromDatetime(datetime(2004, 12, 6, 14, 15, 16))),
+            "Time(2004, 12, 6, 14, 15, 16, 0, 341, 0)")
+        self.assertEquals(
+            repr(Time.fromDatetime(datetime(
+                2004, 12, 6, 7, 15, 16, tzinfo=self.MST()))),
+            "Time(2004, 12, 6, 14, 15, 16, 0, 341, 0)")
+        self.assertEquals(
+            repr(Time.fromDatetime(datetime(
+                2004, 12, 6, 15, 15, 16, tzinfo=self.CET()))),
+            "Time(2004, 12, 6, 14, 15, 16, 0, 341, 0)")
+
+    def test_asDatetime(self):
+        self.assertEquals(
+            self._createReference().asDatetime(), self.awareReference)
+        self.assertEquals(
+            self._createReference().asDatetime(tzinfo=self.MST()),
+            self.awareReference )
+        self.assertEquals(
+            self._createReference().asDatetime(tzinfo=self.CET()),
+            self.awareReference)
+
+    def test_arithmetic(self):
+        """
+        Verify that L{timedelta} objects can be added to and subtracted from
+        L{Time} instances and that L{Time} instances can be subtracted from
+        each other.
+        """
+        time1 = Time.fromISO8601TimeAndDate('2004-12-03T14:15:16')
+        time2 = Time.fromISO8601TimeAndDate('2004-12-09T14:15:16')
+        offset = timedelta(days=6)
+
+        # Supported operations
+        self.assertEqual(time1 + offset, time2)
+        self.assertEqual(time2 - offset, time1)
+        self.assertEqual(time2 - time1, offset)
+
+        # Make sure unsupported types give back a TypeError
+        self.assertRaises(TypeError, lambda: time1 + 1)
+        self.assertRaises(TypeError, lambda: time1 - 1)

=== modified file 'txaws/util.py'
--- txaws/util.py	2009-10-21 19:40:18 +0000
+++ txaws/util.py	2009-11-05 04:20:23 +0000
@@ -4,11 +4,13 @@
 services.
 """
 
+import datetime
+import hmac
+import re
+import time
 from base64 import b64encode
 from hashlib import sha1, md5, sha256
-import hmac
 from urlparse import urlparse, urlunparse
-import time
 
 # Import XMLTreeBuilder from somewhere; here in one place to prevent
 # duplication.
@@ -18,7 +20,8 @@
     from elementtree.ElementTree import XMLTreeBuilder
 
 
-__all__ = ["hmac_sha1", "hmac_sha256", "iso8601time", "calculate_md5", "XML"]
+__all__ = [
+    "hmac_sha1", "hmac_sha256", "iso8601time", "calculate_md5", "Time", "XML"]
 
 
 def calculate_md5(data):
@@ -94,3 +97,472 @@
     if path == "":
         path = "/"
     return scheme, host, port, path
+
+
+def _timedeltaToSignHrMin(offset):
+    """
+    Return a (sign, hour, minute) triple for the offset described by timedelta.
+
+    sign is a string, either "+" or "-". In the case of 0 offset, sign is "+".
+    """
+    minutes = round((offset.days * 3600000000 * 24
+                     + offset.seconds * 1000000
+                     + offset.microseconds)
+                    / 60000000.0)
+    if minutes < 0:
+        sign = '-'
+        minutes = -minutes
+    else:
+        sign = '+'
+    return (sign, minutes // 60, minutes % 60)
+
+
+def _timedeltaToSeconds(offset):
+    """
+    Convert a datetime.timedelta instance to simply a number of seconds.
+
+    For example, you can specify purely second intervals with timedelta's
+    constructor:
+
+        >>> td = datetime.timedelta(seconds=99999999)
+
+    but then you can't get them out again:
+
+        >>> td.seconds
+        35199
+
+    This allows you to:
+
+        >>> import txaws.util
+        >>> txaws.util._timedeltaToSeconds(td)
+        99999999.0
+
+    @param offset: a L{datetime.timedelta} representing an interval that we
+    wish to know the total number of seconds for.
+
+    @return: a number of seconds
+    @rtype: float
+    """
+    return ((offset.days * 60*60*24) +
+            (offset.seconds) +
+            (offset.microseconds * 1e-6))
+
+
+class FixedOffset(datetime.tzinfo):
+    _zeroOffset = datetime.timedelta()
+
+    def __init__(self, hours, minutes):
+        self.offset = datetime.timedelta(minutes = hours * 60 + minutes)
+
+    def utcoffset(self, dt):
+        return self.offset
+
+    def tzname(self, dt):
+        return _timedeltaToSignHrMin(self.offset)
+
+    def dst(self, tz):
+        return self._zeroOffset
+
+    def __repr__(self):
+        return '<%s.%s object at 0x%x offset %r>' % (
+            self.__module__, type(self).__name__, id(self), self.offset)
+
+
+class Time(object):
+    """An object representing a well defined instant in time.
+
+    A Time object unambiguously addresses some time, independent of timezones,
+    contorted base-60 counting schemes, leap seconds, and the effects of
+    general relativity. It provides methods for returning a representation of
+    this time in various ways that a human or a programmer might find more
+    useful in various applications.
+
+    Every Time instance has an attribute 'resolution'. This can be ignored, or
+    the instance can be considered to address a span of time. This resolution
+    is determined by the value used to initalize the instance, or the
+    resolution of the internal representation, whichever is greater. It is
+    mostly useful when using input formats that allow the specification of
+    whole days or weeks. For example, ISO 8601 allows one to state a time as,
+    "2005-W03", meaning "the third week of 2005". In this case the resolution
+    is set to one week. Other formats are considered to express only an instant
+    in time, such as a POSIX timestamp, because the resolution of the time is
+    limited only by the hardware's representation of a real number.
+
+    Timezones are significant only for instances with a resolution greater than
+    one day. When the timezone is insignificant, the result of methods like
+    asISO8601TimeAndDate is the same for any given tzinfo parameter. Sort order
+    is determined by the start of the period in UTC. For example, "today" sorts
+    after "midnight today, central Europe", and before "midnight today, US
+    Eastern". For applications that need to store a mix of timezone dependent
+    and independent instances, it may be wise to store them separately, since
+    the time between the start and end of today in the local timezone may not
+    include the start of today in UTC, and thus not independent instances
+    addressing the whole day. In other words, the desired sort order (the one
+    where just "Monday" sorts before any more precise time in "Monday", and
+    after any in "Sunday") of Time instances is dependant on the timezone
+    context.
+
+    Date arithmetic and boolean operations operate on instants in time, not
+    periods. In this case, the start of the period is used as the value, and
+    the result has a resolution of 0.
+
+    For containment tests with the 'in' operator, the period addressed by the
+    instance is used.
+
+    The methods beginning with 'from' are constructors to create instances from
+    various formats. Some of them are textual formats, and others are other
+    time types commonly found in Python code.
+
+    Likewise, methods beginning with 'as' return the represented time in
+    various formats. Some of these methods should try to reflect the resolution
+    of the instance. However, they don't yet.
+
+    For formats with both a constructor and a formatter, d == fromFu(d.asFu())
+
+    @type resolution: datetime.timedelta
+    @ivar resolution: the length of the period to which this instance could
+    refer. For example, "Today, 13:38" could refer to any time between 13:38
+    until but not including 13:39. In this case resolution would be
+    timedelta(minutes=1).
+    """
+
+    # the instance variable _time is the internal representation of time. It
+    # is a naive datetime object which is always UTC. A UTC tzinfo would be
+    # great, if one existed, and anyway it complicates pickling.
+
+    rfc2822Weekdays = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
+
+    rfc2822Months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug',
+                     'Sep', 'Oct', 'Nov', 'Dec']
+
+    resolution = datetime.timedelta.resolution
+
+    def __init__(self):
+        """Return a new Time instance representing the time now.
+
+        See also the fromFu methods to create new instances from other types of
+        initializers.
+        """
+        self._time = datetime.datetime.utcnow()
+
+    iso8601pattern = re.compile(r"""
+        ^ (?P<year> \d{4})
+        (
+            # a year may optionally be followed by one of:
+            # - a month
+            # - a week
+            # - a specific day, and an optional time
+            #     a specific day is one of:
+            #     - a month and day
+            #     - week and weekday
+            #     - a day of the year
+            (
+                -? (?P<month1> \d{2})
+                |
+                -? W (?P<week1> \d{2})
+                |
+                (
+                    -? (?P<month2> \d{2})
+                    -? (?P<day> \d{2})
+                    |
+                    -? W (?P<week2> \d{2})
+                    -? (?P<weekday> \d)
+                    |
+                    -? (?P<dayofyear> \d{3})
+                )
+                (
+                    T (?P<hour> \d{2})
+                    (
+                        :? (?P<minute> \d{2})
+                        (
+                            :? (?P<second> \d{2})
+                            (
+                                [\.,] (?P<fractionalsec> \d+)
+                            )?
+                        )?
+                    )?
+                    (
+                        (?P<zulu> Z)
+                        |
+                        (?P<tzhour> [+\-]\d{2})
+                        (
+                            :? (?P<tzmin> \d{2})
+                        )?
+                    )?
+                )?
+            )?
+        )? $""", re.VERBOSE)
+
+    def fromISO8601TimeAndDate(klass, iso8601string, tzinfo=None):
+        """Return a new Time instance from a string formated as in ISO 8601.
+
+        If the given string contains no timezone, it is assumed to be in the
+        timezone specified by the parameter `tzinfo`, or UTC if tzinfo is None.
+        An input string with an explicit timezone will always override tzinfo.
+
+        If the given iso8601string does not contain all parts of the time, they
+        will default to 0 in the timezone given by `tzinfo`.
+
+        WARNING: this function is incomplete. ISO is dumb and their standards
+        are not free. Only a subset of all valid ISO 8601 dates are parsed,
+        because I can't find a formal description of the format. However,
+        common ones should work.
+        """
+
+        def calculateTimezone():
+            if groups['zulu'] == 'Z':
+                return FixedOffset(0, 0)
+            else:
+                tzhour = groups.pop('tzhour')
+                tzmin = groups.pop('tzmin')
+                if tzhour is not None:
+                    return FixedOffset(int(tzhour), int(tzmin or 0))
+            return tzinfo or FixedOffset(0, 0)
+
+        def coerceGroups():
+            groups['month'] = groups['month1'] or groups['month2']
+            groups['week'] = groups['week1'] or groups['week2']
+            # don't include fractional seconds, because it's not an integer.
+            defaultTo0 = ['hour', 'minute', 'second']
+            defaultTo1 = ['month', 'day', 'week', 'weekday', 'dayofyear']
+            if groups['fractionalsec'] is None:
+                groups['fractionalsec'] = '0'
+            for key in defaultTo0:
+                if groups[key] is None:
+                    groups[key] = 0
+            for key in defaultTo1:
+                if groups[key] is None:
+                    groups[key] = 1
+            groups['fractionalsec'] = float('.'+groups['fractionalsec'])
+            for key in defaultTo0 + defaultTo1 + ['year']:
+                groups[key] = int(groups[key])
+
+            for group, min, max in [
+                # some years have only 52 weeks
+                ('week', 1, 53),
+                ('weekday', 1, 7),
+                ('month', 1, 12),
+                ('day', 1, 31),
+                ('hour', 0, 24),
+                ('minute', 0, 59),
+
+                # Sometime in the 22nd century AD, two leap seconds will be
+                # required every year.  In the 25th century AD, four every
+                # year.  We'll ignore that for now though because it would be
+                # tricky to get right and we certainly don't need it for our
+                # target applications.  In other words, post-singularity
+                # Martian users, please do not rely on this code for
+                # compatibility with Greater Galactic Protectorate of Earth
+                # date/time formatting!  Apologies, but no library I know of in
+                # Python is sufficient for processing their dates and times
+                # without ADA bindings to get the radiation-safety zone counter
+                # correct. -glyph
+
+                ('second', 0, 61),
+                # don't forget leap years
+                ('dayofyear', 1, 366)]:
+                if not min <= groups[group] <= max:
+                    raise ValueError, '%s must be in %i..%i' % (group, min, max)
+
+        def determineResolution():
+            if match.group('fractionalsec') is not None:
+                return max(datetime.timedelta.resolution,
+                    datetime.timedelta(
+                        microseconds=1 * 10 ** -len(
+                            match.group('fractionalsec')) * 1000000))
+
+            for testGroup, resolution in [
+            ('second', datetime.timedelta(seconds=1)),
+            ('minute', datetime.timedelta(minutes=1)),
+            ('hour', datetime.timedelta(hours=1)),
+            ('weekday', datetime.timedelta(days=1)),
+            ('dayofyear', datetime.timedelta(days=1)),
+            ('day', datetime.timedelta(days=1)),
+            ('week1', datetime.timedelta(weeks=1)),
+            ('week2', datetime.timedelta(weeks=1))]:
+                if match.group(testGroup) is not None:
+                    return resolution
+
+            if match.group('month1') is not None \
+            or match.group('month2') is not None:
+                if self._time.month == 12:
+                    return datetime.timedelta(days=31)
+                nextMonth = self._time.replace(month=self._time.month+1)
+                return nextMonth - self._time
+            else:
+                nextYear = self._time.replace(year=self._time.year+1)
+                return nextYear - self._time
+
+        def calculateDtime(tzinfo):
+            """Calculate a datetime for the start of the addressed period."""
+
+            if match.group('week1') is not None \
+            or match.group('week2') is not None:
+                if not 0 < groups['week'] <= 53:
+                    raise ValueError(
+                        'week must be in 1..53 (was %i)' % (groups['week'],))
+                dtime = datetime.datetime(
+                    groups['year'],
+                    1,
+                    4,
+                    groups['hour'],
+                    groups['minute'],
+                    groups['second'],
+                    int(round(groups['fractionalsec'] * 1000000)),
+                    tzinfo=tzinfo
+                )
+                dtime -= datetime.timedelta(days = dtime.weekday())
+                dtime += datetime.timedelta(
+                    days = (groups['week']-1) * 7 + groups['weekday'] - 1)
+                if dtime.isocalendar() != (
+                    groups['year'], groups['week'], groups['weekday']):
+                    # actually the problem could be an error in my logic, but
+                    # nothing should cause this but requesting week 53 of a
+                    # year with 52 weeks.
+                    raise ValueError('year %04i has no week %02i' %
+                                     (groups['year'], groups['week']))
+                return dtime
+
+            if match.group('dayofyear') is not None:
+                dtime = datetime.datetime(
+                    groups['year'],
+                    1,
+                    1,
+                    groups['hour'],
+                    groups['minute'],
+                    groups['second'],
+                    int(round(groups['fractionalsec'] * 1000000)),
+                    tzinfo=tzinfo
+                )
+                dtime += datetime.timedelta(days=groups['dayofyear']-1)
+                if dtime.year != groups['year']:
+                    raise ValueError(
+                        'year %04i has no day of year %03i' %
+                        (groups['year'], groups['dayofyear']))
+                return dtime
+
+            else:
+                return datetime.datetime(
+                    groups['year'],
+                    groups['month'],
+                    groups['day'],
+                    groups['hour'],
+                    groups['minute'],
+                    groups['second'],
+                    int(round(groups['fractionalsec'] * 1000000)),
+                    tzinfo=tzinfo
+                )
+
+        match = klass.iso8601pattern.match(iso8601string)
+        if match is None:
+            raise ValueError(
+                '%r could not be parsed as an ISO 8601 date and time' %
+                (iso8601string,))
+
+        groups = match.groupdict()
+        coerceGroups()
+        if match.group('hour') is not None:
+            timezone = calculateTimezone()
+        else:
+            timezone = None
+        self = klass.fromDatetime(calculateDtime(timezone))
+        self.resolution = determineResolution()
+        return self.asDatetime()
+
+    fromISO8601TimeAndDate = classmethod(fromISO8601TimeAndDate)
+
+    def fromDatetime(klass, dtime):
+        """Return a new Time instance from a datetime.datetime instance.
+
+        If the datetime instance does not have an associated timezone, it is
+        assumed to be UTC.
+        """
+        self = klass.__new__(klass)
+        if dtime.tzinfo is not None:
+            self._time = dtime.astimezone(FixedOffset(0, 0)).replace(tzinfo=None)
+        else:
+            self._time = dtime
+        self.resolution = datetime.timedelta.resolution
+        return self
+
+    fromDatetime = classmethod(fromDatetime)
+
+    def asDatetime(self, tzinfo=None):
+        """Return this time as an aware datetime.datetime instance.
+
+        The returned datetime object has the specified tzinfo, or a tzinfo
+        describing UTC if the tzinfo parameter is None.
+        """
+        if tzinfo is None:
+            tzinfo = FixedOffset(0, 0)
+
+        if not self.isTimezoneDependent():
+            return self._time.replace(tzinfo=tzinfo)
+        else:
+            return self._time.replace(tzinfo=FixedOffset(0, 0)).astimezone(tzinfo)
+
+    def isTimezoneDependent(self):
+        """Return True iff timezone is relevant for this instance.
+
+        Timezone is only relevent for instances with a resolution better than
+        one day.
+        """
+        return self.resolution < datetime.timedelta(days=1)
+
+    def __cmp__(self, other):
+        if not isinstance(other, Time):
+            raise TypeError("Cannot meaningfully compare %r with %r" % (self, other))
+        return cmp(self._time, other._time)
+
+    def __eq__(self, other):
+        if isinstance(other, Time):
+            return cmp(self._time, other._time) == 0
+        return False
+
+    def __ne__(self, other):
+        return not (self == other)
+
+    def __repr__(self):
+        return "%s%s" % (
+            self.__class__.__name__, self.asDatetime().timetuple())
+
+    def __contains__(self, other):
+        """Test if another Time instance is entirely within the period addressed by this one."""
+        if not isinstance(other, Time):
+            raise TypeError(
+                '%r is not a Time instance; can not test for containment'
+                % (other,))
+        if other._time < self._time:
+            return False
+        if self._time + self.resolution < other._time + other.resolution:
+            return False
+        return True
+
+    def __add__(self, addend):
+        if not isinstance(addend, datetime.timedelta):
+            raise TypeError, 'expected a datetime.timedelta instance'
+        return Time.fromDatetime(self._time + addend)
+
+    def __sub__(self, subtrahend):
+        """
+        Implement subtraction of an interval or another time from this one.
+
+        @type subtrahend: L{datetime.timedelta} or L{Time}
+
+        @param subtrahend: The object to be subtracted from this one.
+
+        @rtype: L{datetime.timedelta} or L{Time}
+
+        @return: If C{subtrahend} is a L{datetime.timedelta}, the result is
+        a L{Time} instance which is offset from this one by that amount.  If
+        C{subtrahend} is a L{Time}, the result is a L{datetime.timedelta}
+        instance which gives the difference between it and this L{Time}
+        instance.
+        """
+        if isinstance(subtrahend, datetime.timedelta):
+            return Time.fromDatetime(self._time - subtrahend)
+
+        if isinstance(subtrahend, Time):
+            return self.asDatetime() - subtrahend.asDatetime()
+
+        return NotImplemented