roundup/date.py

   1 #
   2 # Copyright (c) 2001 Bizar Software Pty Ltd (http://www.bizarsoftware.com.au/)
   3 # This module is free software, and you may redistribute it and/or modify
   4 # under the same terms as Python, so long as this copyright message and
   5 # disclaimer are retained in their original form.
   6 #
   7 # IN NO EVENT SHALL BIZAR SOFTWARE PTY LTD BE LIABLE TO ANY PARTY FOR
   8 # DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING
   9 # OUT OF THE USE OF THIS CODE, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE
  10 # POSSIBILITY OF SUCH DAMAGE.
  11 #
  12 # BIZAR SOFTWARE PTY LTD SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
  13 # BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  14 # FOR A PARTICULAR PURPOSE.  THE CODE PROVIDED HEREUNDER IS ON AN "AS IS"
  15 # BASIS, AND THERE IS NO OBLIGATION WHATSOEVER TO PROVIDE MAINTENANCE,
  16 # SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  17 #
  18 # $Id: date.py,v 1.20 2002-02-21 23:34:51 richard Exp $
  19
  20 __doc__ = """
  21 Date, time and time interval handling.
  22 """
  23
  24 import time, re, calendar
  25 from i18n import _
  26
  27 class Date:
  28     '''
  29     As strings, date-and-time stamps are specified with the date in
  30     international standard format (yyyy-mm-dd) joined to the time
  31     (hh:mm:ss) by a period ("."). Dates in this form can be easily compared
  32     and are fairly readable when printed. An example of a valid stamp is
  33     "2000-06-24.13:03:59". We'll call this the "full date format". When
  34     Timestamp objects are printed as strings, they appear in the full date
  35     format with the time always given in GMT. The full date format is
  36     always exactly 19 characters long.
  37
  38     For user input, some partial forms are also permitted: the whole time
  39     or just the seconds may be omitted; and the whole date may be omitted
  40     or just the year may be omitted. If the time is given, the time is
  41     interpreted in the user's local time zone. The Date constructor takes
  42     care of these conversions. In the following examples, suppose that yyyy
  43     is the current year, mm is the current month, and dd is the current day
  44     of the month; and suppose that the user is on Eastern Standard Time.
  45
  46       "2000-04-17" means <Date 2000-04-17.00:00:00>
  47       "01-25" means <Date yyyy-01-25.00:00:00>
  48       "2000-04-17.03:45" means <Date 2000-04-17.08:45:00>
  49       "08-13.22:13" means <Date yyyy-08-14.03:13:00>
  50       "11-07.09:32:43" means <Date yyyy-11-07.14:32:43>
  51       "14:25" means <Date yyyy-mm-dd.19:25:00>
  52       "8:47:11" means <Date yyyy-mm-dd.13:47:11>
  53       "." means "right now"
  54
  55     The Date class should understand simple date expressions of the form
  56     stamp + interval and stamp - interval. When adding or subtracting
  57     intervals involving months or years, the components are handled
  58     separately. For example, when evaluating "2000-06-25 + 1m 10d", we
  59     first add one month to get 2000-07-25, then add 10 days to get
  60     2000-08-04 (rather than trying to decide whether 1m 10d means 38 or 40
  61     or 41 days).
  62
  63     Example usage:
  64         >>> Date(".")
  65         <Date 2000-06-26.00:34:02>
  66         >>> _.local(-5)
  67         "2000-06-25.19:34:02"
  68         >>> Date(". + 2d")
  69         <Date 2000-06-28.00:34:02>
  70         >>> Date("1997-04-17", -5)
  71         <Date 1997-04-17.00:00:00>
  72         >>> Date("01-25", -5)
  73         <Date 2000-01-25.00:00:00>
  74         >>> Date("08-13.22:13", -5)
  75         <Date 2000-08-14.03:13:00>
  76         >>> Date("14:25", -5)
  77         <Date 2000-06-25.19:25:00>
  78     '''
  79     def __init__(self, spec='.', offset=0):
  80         """Construct a date given a specification and a time zone offset.
  81
  82           'spec' is a full date or a partial form, with an optional
  83                  added or subtracted interval. Or a date 9-tuple.
  84         'offset' is the local time zone offset from GMT in hours.
  85         """
  86         if type(spec) == type(''):
  87             self.set(spec, offset=offset)
  88         else:
  89             y,m,d,H,M,S,x,x,x = spec
  90             ts = calendar.timegm((y,m,d,H+offset,M,S,0,0,0))
  91             self.year, self.month, self.day, self.hour, self.minute, \
  92                 self.second, x, x, x = time.gmtime(ts)
  93
  94     def applyInterval(self, interval):
  95         ''' Apply the interval to this date
  96         '''
  97         t = (self.year + interval.year,
  98              self.month + interval.month,
  99              self.day + interval.day,
 100              self.hour + interval.hour,
 101              self.minute + interval.minute,
 102              self.second + interval.second, 0, 0, 0)
 103         self.year, self.month, self.day, self.hour, self.minute, \
 104             self.second, x, x, x = time.gmtime(calendar.timegm(t))
 105
 106     def __add__(self, other):
 107         """Add an interval to this date to produce another date.
 108         """
 109         # do the basic calc
 110         sign = other.sign
 111         year = self.year + sign * other.year
 112         month = self.month + sign * other.month
 113         day = self.day + sign * other.day
 114         hour = self.hour + sign * other.hour
 115         minute = self.minute + sign * other.minute
 116         second = self.second + sign * other.second
 117
 118         # now cope with under- and over-flow
 119         # first do the time
 120         while (second < 0 or second > 59 or minute < 0 or minute > 59 or
 121                 hour < 0 or hour > 59):
 122             if second < 0: minute -= 1; second += 60
 123             elif second > 59: minute += 1; second -= 60
 124             if minute < 0: hour -= 1; minute += 60
 125             elif minute > 59: hour += 1; minute -= 60
 126             if hour < 0: day -= 1; hour += 24
 127             elif hour > 59: day += 1; hour -= 24
 128
 129         # fix up the month so we're within range
 130         while month < 1 or month > 12:
 131             if month < 1: year -= 1; month += 12
 132             if month > 12: year += 1; month -= 12
 133
 134         # now do the days, now that we know what month we're in
 135         mdays = calendar.mdays
 136         if month == 2 and calendar.isleap(year): month_days = 29
 137         else: month_days = mdays[month]
 138         while month < 1 or month > 12 or day < 0 or day > month_days:
 139             # now to day under/over
 140             if day < 0: month -= 1; day += month_days
 141             elif day > month_days: month += 1; day -= month_days
 142
 143             # possibly fix up the month so we're within range
 144             while month < 1 or month > 12:
 145                 if month < 1: year -= 1; month += 12
 146                 if month > 12: year += 1; month -= 12
 147
 148             # re-figure the number of days for this month
 149             if month == 2 and calendar.isleap(year): month_days = 29
 150             else: month_days = mdays[month]
 151
 152         return Date((year, month, day, hour, minute, second, 0, 0, 0))
 153
 154     # XXX deviates from spec to allow subtraction of dates as well
 155     def __sub__(self, other):
 156         """ Subtract:
 157              1. an interval from this date to produce another date.
 158              2. a date from this date to produce an interval.
 159         """
 160         if isinstance(other, Interval):
 161             other = Interval(other.get_tuple(), sign=-other.sign)
 162             return self.__add__(other)
 163
 164         assert isinstance(other, Date), 'May only subtract Dates or Intervals'
 165
 166         # TODO this code will fall over laughing if the dates cross
 167         # leap years, phases of the moon, ....
 168         a = calendar.timegm((self.year, self.month, self.day, self.hour,
 169             self.minute, self.second, 0, 0, 0))
 170         b = calendar.timegm((other.year, other.month, other.day,
 171             other.hour, other.minute, other.second, 0, 0, 0))
 172         diff = a - b
 173         if diff < 0:
 174             sign = 1
 175             diff = -diff
 176         else:
 177             sign = -1
 178         S = diff%60
 179         M = (diff/60)%60
 180         H = (diff/(60*60))%60
 181         if H>1: S = 0
 182         d = (diff/(24*60*60))%30
 183         if d>1: H = S = M = 0
 184         m = (diff/(30*24*60*60))%12
 185         if m>1: H = S = M = 0
 186         y = (diff/(365*24*60*60))
 187         if y>1: d = H = S = M = 0
 188         return Interval((y, m, d, H, M, S), sign=sign)
 189
 190     def __cmp__(self, other):
 191         """Compare this date to another date."""
 192         if other is None:
 193             return 1
 194         for attr in ('year', 'month', 'day', 'hour', 'minute', 'second'):
 195             r = cmp(getattr(self, attr), getattr(other, attr))
 196             if r: return r
 197         return 0
 198
 199     def __str__(self):
 200         """Return this date as a string in the yyyy-mm-dd.hh:mm:ss format."""
 201         return '%4d-%02d-%02d.%02d:%02d:%02d'%(self.year, self.month, self.day,
 202             self.hour, self.minute, self.second)
 203
 204     def pretty(self):
 205         ''' print up the date date using a pretty format...
 206         '''
 207         str = time.strftime('%d %B %Y', (self.year, self.month,
 208             self.day, self.hour, self.minute, self.second, 0, 0, 0))
 209         if str[0] == '0': return ' ' + str[1:]
 210         return str
 211
 212     def set(self, spec, offset=0, date_re=re.compile(r'''
 213               (((?P<y>\d\d\d\d)-)?((?P<m>\d\d?)-(?P<d>\d\d?))?)? # yyyy-mm-dd
 214               (?P<n>\.)?                                       # .
 215               (((?P<H>\d?\d):(?P<M>\d\d))?(:(?P<S>\d\d))?)?    # hh:mm:ss
 216               (?P<o>.+)?                                       # offset
 217               ''', re.VERBOSE)):
 218         ''' set the date to the value in spec
 219         '''
 220         m = date_re.match(spec)
 221         if not m:
 222             raise ValueError, _('Not a date spec: [[yyyy-]mm-dd].[[h]h:mm[:ss]]'
 223                 '[offset]')
 224         info = m.groupdict()
 225
 226         # get the current date/time using the offset
 227         y,m,d,H,M,S,x,x,x = time.gmtime(time.time())
 228
 229         # override year, month, day parts
 230         if info['m'] is not None and info['d'] is not None:
 231             m = int(info['m'])
 232             d = int(info['d'])
 233             if info['y'] is not None: y = int(info['y'])
 234             H = M = S = 0
 235
 236         # override hour, minute, second parts
 237         if info['H'] is not None and info['M'] is not None:
 238             H = int(info['H']) - offset
 239             M = int(info['M'])
 240             S = 0
 241             if info['S'] is not None: S = int(info['S'])
 242
 243         # now handle the adjustment of hour
 244         ts = calendar.timegm((y,m,d,H,M,S,0,0,0))
 245         self.year, self.month, self.day, self.hour, self.minute, \
 246             self.second, x, x, x = time.gmtime(ts)
 247
 248         if info['o']:
 249             self.applyInterval(Interval(info['o']))
 250
 251     def __repr__(self):
 252         return '<Date %s>'%self.__str__()
 253
 254     def local(self, offset):
 255         """Return this date as yyyy-mm-dd.hh:mm:ss in a local time zone."""
 256         t = (self.year, self.month, self.day, self.hour + offset, self.minute,
 257              self.second, 0, 0, 0)
 258         self.year, self.month, self.day, self.hour, self.minute, \
 259             self.second, x, x, x = time.gmtime(calendar.timegm(t))
 260
 261     def get_tuple(self):
 262         return (self.year, self.month, self.day, self.hour, self.minute,
 263             self.second, 0, 0, 0)
 264
 265 class Interval:
 266     '''
 267     Date intervals are specified using the suffixes "y", "m", and "d". The
 268     suffix "w" (for "week") means 7 days. Time intervals are specified in
 269     hh:mm:ss format (the seconds may be omitted, but the hours and minutes
 270     may not).
 271
 272       "3y" means three years
 273       "2y 1m" means two years and one month
 274       "1m 25d" means one month and 25 days
 275       "2w 3d" means two weeks and three days
 276       "1d 2:50" means one day, two hours, and 50 minutes
 277       "14:00" means 14 hours
 278       "0:04:33" means four minutes and 33 seconds
 279
 280     Example usage:
 281         >>> Interval("  3w  1  d  2:00")
 282         <Interval 22d 2:00>
 283         >>> Date(". + 2d") + Interval("- 3w")
 284         <Date 2000-06-07.00:34:02>
 285
 286     Intervals are added/subtracted in order of:
 287        seconds, minutes, hours, years, months, days
 288
 289     Calculations involving monts (eg '+2m') have no effect on days - only
 290     days (or over/underflow from hours/mins/secs) will do that, and
 291     days-per-month and leap years are accounted for. Leap seconds are not.
 292
 293     TODO: more examples, showing the order of addition operation
 294     '''
 295     def __init__(self, spec, sign=1):
 296         """Construct an interval given a specification."""
 297         if type(spec) == type(''):
 298             self.set(spec)
 299         else:
 300             self.sign = sign
 301             self.year, self.month, self.day, self.hour, self.minute, \
 302                 self.second = spec
 303
 304     def __cmp__(self, other):
 305         """Compare this interval to another interval."""
 306         if other is None:
 307             return 1
 308         for attr in ('year', 'month', 'day', 'hour', 'minute', 'second'):
 309             r = cmp(getattr(self, attr), getattr(other, attr))
 310             if r: return r
 311         return 0
 312
 313     def __str__(self):
 314         """Return this interval as a string."""
 315         sign = {1:'+', -1:'-'}[self.sign]
 316         l = [sign]
 317         if self.year: l.append('%sy'%self.year)
 318         if self.month: l.append('%sm'%self.month)
 319         if self.day: l.append('%sd'%self.day)
 320         if self.second:
 321             l.append('%d:%02d:%02d'%(self.hour, self.minute, self.second))
 322         elif self.hour or self.minute:
 323             l.append('%d:%02d'%(self.hour, self.minute))
 324         return ' '.join(l)
 325
 326     def set(self, spec, interval_re = re.compile('''
 327             \s*
 328             (?P<s>[-+])?         # + or -
 329             \s*
 330             ((?P<y>\d+\s*)y)?    # year
 331             \s*
 332             ((?P<m>\d+\s*)m)?    # month
 333             \s*
 334             ((?P<w>\d+\s*)w)?    # week
 335             \s*
 336             ((?P<d>\d+\s*)d)?    # day
 337             \s*
 338             (((?P<H>\d+):(?P<M>\d+))?(:(?P<S>\d+))?)?   # time
 339             \s*
 340             ''', re.VERBOSE)):
 341         ''' set the date to the value in spec
 342         '''
 343         self.year = self.month = self.week = self.day = self.hour = \
 344             self.minute = self.second = 0
 345         self.sign = 1
 346         m = interval_re.match(spec)
 347         if not m:
 348             raise ValueError, _('Not an interval spec: [+-] [#y] [#m] [#w] '
 349                 '[#d] [[[H]H:MM]:SS]')
 350
 351         info = m.groupdict()
 352         for group, attr in {'y':'year', 'm':'month', 'w':'week', 'd':'day',
 353                 'H':'hour', 'M':'minute', 'S':'second'}.items():
 354             if info[group] is not None:
 355                 setattr(self, attr, int(info[group]))
 356
 357         if self.week:
 358             self.day = self.day + self.week*7
 359
 360         if info['s'] is not None:
 361             self.sign = {'+':1, '-':-1}[info['s']]
 362
 363     def __repr__(self):
 364         return '<Interval %s>'%self.__str__()
 365
 366     def pretty(self):
 367         ''' print up the date date using one of these nice formats..
 368         '''
 369         if self.year or self.month > 2:
 370             return None
 371         elif self.month or self.day > 13:
 372             days = (self.month * 30) + self.day
 373             if days > 28:
 374                 if int(days/30) > 1:
 375                     s = _('%(number)s months')%{'number': int(days/30)}
 376                 else:
 377                     s = _('1 month')
 378             else:
 379                 s = _('%(number)s weeks')%{'number': int(days/7)}
 380         elif self.day > 7:
 381             s = _('1 week')
 382         elif self.day > 1:
 383             s = _('%(number)s days')%{'number': self.day}
 384         elif self.day == 1 or self.hour > 12:
 385             if self.sign > 0:
 386                 return _('tomorrow')
 387             else:
 388                 return _('yesterday')
 389         elif self.hour > 1:
 390             s = _('%(number)s hours')%{'number': self.hour}
 391         elif self.hour == 1:
 392             if self.minute < 15:
 393                 s = _('an hour')
 394             elif self.minute/15 == 2:
 395                 s = _('1 1/2 hours')
 396             else:
 397                 s = _('1 %(number)s/4 hours')%{'number': self.minute/15}
 398         elif self.minute < 1:
 399             if self.sign > 0:
 400                 return _('in a moment')
 401             else:
 402                 return _('just now')
 403         elif self.minute == 1:
 404             s = _('1 minute')
 405         elif self.minute < 15:
 406             s = _('%(number)s minutes')%{'number': self.minute}
 407         elif int(self.minute/15) == 2:
 408             s = _('1/2 an hour')
 409         else:
 410             s = _('%(number)s/4 hour')%{'number': int(self.minute/15)}
 411         return s
 412
 413     def get_tuple(self):
 414         return (self.year, self.month, self.day, self.hour, self.minute,
 415             self.second)
 416
 417
 418 def test():
 419     intervals = ("  3w  1  d  2:00", " + 2d", "3w")
 420     for interval in intervals:
 421         print '>>> Interval("%s")'%interval
 422         print `Interval(interval)`
 423
 424     dates = (".", "2000-06-25.19:34:02", ". + 2d", "1997-04-17", "01-25",
 425         "08-13.22:13", "14:25")
 426     for date in dates:
 427         print '>>> Date("%s")'%date
 428         print `Date(date)`
 429
 430     sums = ((". + 2d", "3w"), (".", "  3w  1  d  2:00"))
 431     for date, interval in sums:
 432         print '>>> Date("%s") + Interval("%s")'%(date, interval)
 433         print `Date(date) + Interval(interval)`
 434
 435 if __name__ == '__main__':
 436     test()
 437
 438 #
 439 # $Log: not supported by cvs2svn $
 440 # Revision 1.19  2002/02/21 23:11:45  richard
 441 #  . fixed some problems in date calculations (calendar.py doesn't handle over-
 442 #    and under-flow). Also, hour/minute/second intervals may now be more than
 443 #    99 each.
 444 #
 445 # Revision 1.18  2002/01/23 20:00:50  jhermann
 446 # %e is a UNIXism and not documented for Python
 447 #
 448 # Revision 1.17  2002/01/16 07:02:57  richard
 449 #  . lots of date/interval related changes:
 450 #    - more relaxed date format for input
 451 #
 452 # Revision 1.16  2002/01/08 11:56:24  richard
 453 # missed an import _
 454 #
 455 # Revision 1.15  2002/01/05 02:27:00  richard
 456 # I18N'ification
 457 #
 458 # Revision 1.14  2001/11/22 15:46:42  jhermann
 459 # Added module docstrings to all modules.
 460 #
 461 # Revision 1.13  2001/09/18 22:58:37  richard
 462 #
 463 # Added some more help to roundu-admin
 464 #
 465 # Revision 1.12  2001/08/17 03:08:11  richard
 466 # fixed prettification of intervals of 1 week
 467 #
 468 # Revision 1.11  2001/08/15 23:43:18  richard
 469 # Fixed some isFooTypes that I missed.
 470 # Refactored some code in the CGI code.
 471 #
 472 # Revision 1.10  2001/08/07 00:24:42  richard
 473 # stupid typo
 474 #
 475 # Revision 1.9  2001/08/07 00:15:51  richard
 476 # Added the copyright/license notice to (nearly) all files at request of
 477 # Bizar Software.
 478 #
 479 # Revision 1.8  2001/08/05 07:46:12  richard
 480 # Changed date.Date to use regular string formatting instead of strftime -
 481 # win32 seems to have problems with %T and no hour... or something...
 482 #
 483 # Revision 1.7  2001/08/02 00:27:04  richard
 484 # Extended the range of intervals that are pretty-printed before actual dates
 485 # are displayed.
 486 #
 487 # Revision 1.6  2001/07/31 09:54:18  richard
 488 # Fixed the 2.1-specific gmtime() (no arg) call in roundup.date. (Paul Wright)
 489 #
 490 # Revision 1.5  2001/07/29 07:01:39  richard
 491 # Added vim command to all source so that we don't get no steenkin' tabs :)
 492 #
 493 # Revision 1.4  2001/07/25 04:09:34  richard
 494 # Fixed offset handling (shoulda read the spec a little better)
 495 #
 496 # Revision 1.3  2001/07/23 07:56:05  richard
 497 # Storing only marshallable data in the db - no nasty pickled class references.
 498 #
 499 # Revision 1.2  2001/07/22 12:09:32  richard
 500 # Final commit of Grande Splite
 501 #
 502 # Revision 1.1  2001/07/22 11:58:35  richard
 503 # More Grande Splite
 504 #
 505 #
 506 # vim: set filetype=python ts=4 sw=4 et si