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.22 2002-07-14 06:05:50 richard Exp $
20 __doc__ = """
21 Date, time and time interval handling.
22 """
24 import time, re, calendar
25 from i18n import _
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.
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.
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"
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).
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.
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)
94 def addInterval(self, interval):
95 ''' Add the interval to this date, returning the date tuple
96 '''
97 # do the basic calc
98 sign = interval.sign
99 year = self.year + sign * interval.year
100 month = self.month + sign * interval.month
101 day = self.day + sign * interval.day
102 hour = self.hour + sign * interval.hour
103 minute = self.minute + sign * interval.minute
104 second = self.second + sign * interval.second
106 # now cope with under- and over-flow
107 # first do the time
108 while (second < 0 or second > 59 or minute < 0 or minute > 59 or
109 hour < 0 or hour > 59):
110 if second < 0: minute -= 1; second += 60
111 elif second > 59: minute += 1; second -= 60
112 if minute < 0: hour -= 1; minute += 60
113 elif minute > 59: hour += 1; minute -= 60
114 if hour < 0: day -= 1; hour += 24
115 elif hour > 59: day += 1; hour -= 24
117 # fix up the month so we're within range
118 while month < 1 or month > 12:
119 if month < 1: year -= 1; month += 12
120 if month > 12: year += 1; month -= 12
122 # now do the days, now that we know what month we're in
123 mdays = calendar.mdays
124 if month == 2 and calendar.isleap(year): month_days = 29
125 else: month_days = mdays[month]
126 while month < 1 or month > 12 or day < 0 or day > month_days:
127 # now to day under/over
128 if day < 0: month -= 1; day += month_days
129 elif day > month_days: month += 1; day -= month_days
131 # possibly fix up the month so we're within range
132 while month < 1 or month > 12:
133 if month < 1: year -= 1; month += 12
134 if month > 12: year += 1; month -= 12
136 # re-figure the number of days for this month
137 if month == 2 and calendar.isleap(year): month_days = 29
138 else: month_days = mdays[month]
139 return (year, month, day, hour, minute, second, 0, 0, 0)
141 def applyInterval(self, interval):
142 ''' Apply the interval to this date
143 '''
144 self.year, self.month, self.day, self.hour, self.minute, \
145 self.second, x, x, x = self.addInterval(interval)
147 def __add__(self, interval):
148 """Add an interval to this date to produce another date.
149 """
150 return Date(self.addInterval(interval))
152 # XXX deviates from spec to allow subtraction of dates as well
153 def __sub__(self, other):
154 """ Subtract:
155 1. an interval from this date to produce another date.
156 2. a date from this date to produce an interval.
157 """
158 if isinstance(other, Interval):
159 other = Interval(other.get_tuple(), sign=-other.sign)
160 return self.__add__(other)
162 assert isinstance(other, Date), 'May only subtract Dates or Intervals'
164 # TODO this code will fall over laughing if the dates cross
165 # leap years, phases of the moon, ....
166 a = calendar.timegm((self.year, self.month, self.day, self.hour,
167 self.minute, self.second, 0, 0, 0))
168 b = calendar.timegm((other.year, other.month, other.day,
169 other.hour, other.minute, other.second, 0, 0, 0))
170 diff = a - b
171 if diff < 0:
172 sign = 1
173 diff = -diff
174 else:
175 sign = -1
176 S = diff%60
177 M = (diff/60)%60
178 H = (diff/(60*60))%60
179 if H>1: S = 0
180 d = (diff/(24*60*60))%30
181 if d>1: H = S = M = 0
182 m = (diff/(30*24*60*60))%12
183 if m>1: H = S = M = 0
184 y = (diff/(365*24*60*60))
185 if y>1: d = H = S = M = 0
186 return Interval((y, m, d, H, M, S), sign=sign)
188 def __cmp__(self, other):
189 """Compare this date to another date."""
190 if other is None:
191 return 1
192 for attr in ('year', 'month', 'day', 'hour', 'minute', 'second'):
193 r = cmp(getattr(self, attr), getattr(other, attr))
194 if r: return r
195 return 0
197 def __str__(self):
198 """Return this date as a string in the yyyy-mm-dd.hh:mm:ss format."""
199 return '%4d-%02d-%02d.%02d:%02d:%02d'%(self.year, self.month, self.day,
200 self.hour, self.minute, self.second)
202 def pretty(self):
203 ''' print up the date date using a pretty format...
204 '''
205 str = time.strftime('%d %B %Y', (self.year, self.month,
206 self.day, self.hour, self.minute, self.second, 0, 0, 0))
207 if str[0] == '0': return ' ' + str[1:]
208 return str
210 def set(self, spec, offset=0, date_re=re.compile(r'''
211 (((?P<y>\d\d\d\d)-)?((?P<m>\d\d?)-(?P<d>\d\d?))?)? # yyyy-mm-dd
212 (?P<n>\.)? # .
213 (((?P<H>\d?\d):(?P<M>\d\d))?(:(?P<S>\d\d))?)? # hh:mm:ss
214 (?P<o>.+)? # offset
215 ''', re.VERBOSE)):
216 ''' set the date to the value in spec
217 '''
218 m = date_re.match(spec)
219 if not m:
220 raise ValueError, _('Not a date spec: [[yyyy-]mm-dd].[[h]h:mm[:ss]]'
221 '[offset]')
222 info = m.groupdict()
224 # get the current date/time using the offset
225 y,m,d,H,M,S,x,x,x = time.gmtime(time.time())
227 # override year, month, day parts
228 if info['m'] is not None and info['d'] is not None:
229 m = int(info['m'])
230 d = int(info['d'])
231 if info['y'] is not None: y = int(info['y'])
232 H = M = S = 0
234 # override hour, minute, second parts
235 if info['H'] is not None and info['M'] is not None:
236 H = int(info['H']) - offset
237 M = int(info['M'])
238 S = 0
239 if info['S'] is not None: S = int(info['S'])
241 # now handle the adjustment of hour
242 ts = calendar.timegm((y,m,d,H,M,S,0,0,0))
243 self.year, self.month, self.day, self.hour, self.minute, \
244 self.second, x, x, x = time.gmtime(ts)
246 if info['o']:
247 self.applyInterval(Interval(info['o']))
249 def __repr__(self):
250 return '<Date %s>'%self.__str__()
252 def local(self, offset):
253 """Return this date as yyyy-mm-dd.hh:mm:ss in a local time zone."""
254 t = (self.year, self.month, self.day, self.hour + offset, self.minute,
255 self.second, 0, 0, 0)
256 self.year, self.month, self.day, self.hour, self.minute, \
257 self.second, x, x, x = time.gmtime(calendar.timegm(t))
259 def get_tuple(self):
260 return (self.year, self.month, self.day, self.hour, self.minute,
261 self.second, 0, 0, 0)
263 class Interval:
264 '''
265 Date intervals are specified using the suffixes "y", "m", and "d". The
266 suffix "w" (for "week") means 7 days. Time intervals are specified in
267 hh:mm:ss format (the seconds may be omitted, but the hours and minutes
268 may not).
270 "3y" means three years
271 "2y 1m" means two years and one month
272 "1m 25d" means one month and 25 days
273 "2w 3d" means two weeks and three days
274 "1d 2:50" means one day, two hours, and 50 minutes
275 "14:00" means 14 hours
276 "0:04:33" means four minutes and 33 seconds
278 Example usage:
279 >>> Interval(" 3w 1 d 2:00")
280 <Interval 22d 2:00>
281 >>> Date(". + 2d") + Interval("- 3w")
282 <Date 2000-06-07.00:34:02>
284 Intervals are added/subtracted in order of:
285 seconds, minutes, hours, years, months, days
287 Calculations involving monts (eg '+2m') have no effect on days - only
288 days (or over/underflow from hours/mins/secs) will do that, and
289 days-per-month and leap years are accounted for. Leap seconds are not.
291 TODO: more examples, showing the order of addition operation
292 '''
293 def __init__(self, spec, sign=1):
294 """Construct an interval given a specification."""
295 if type(spec) == type(''):
296 self.set(spec)
297 else:
298 self.sign = sign
299 self.year, self.month, self.day, self.hour, self.minute, \
300 self.second = spec
302 def __cmp__(self, other):
303 """Compare this interval to another interval."""
304 if other is None:
305 return 1
306 for attr in ('year', 'month', 'day', 'hour', 'minute', 'second'):
307 r = cmp(getattr(self, attr), getattr(other, attr))
308 if r: return r
309 return 0
311 def __str__(self):
312 """Return this interval as a string."""
313 sign = {1:'+', -1:'-'}[self.sign]
314 l = [sign]
315 if self.year: l.append('%sy'%self.year)
316 if self.month: l.append('%sm'%self.month)
317 if self.day: l.append('%sd'%self.day)
318 if self.second:
319 l.append('%d:%02d:%02d'%(self.hour, self.minute, self.second))
320 elif self.hour or self.minute:
321 l.append('%d:%02d'%(self.hour, self.minute))
322 return ' '.join(l)
324 def set(self, spec, interval_re = re.compile('''
325 \s*
326 (?P<s>[-+])? # + or -
327 \s*
328 ((?P<y>\d+\s*)y)? # year
329 \s*
330 ((?P<m>\d+\s*)m)? # month
331 \s*
332 ((?P<w>\d+\s*)w)? # week
333 \s*
334 ((?P<d>\d+\s*)d)? # day
335 \s*
336 (((?P<H>\d+):(?P<M>\d+))?(:(?P<S>\d+))?)? # time
337 \s*
338 ''', re.VERBOSE)):
339 ''' set the date to the value in spec
340 '''
341 self.year = self.month = self.week = self.day = self.hour = \
342 self.minute = self.second = 0
343 self.sign = 1
344 m = interval_re.match(spec)
345 if not m:
346 raise ValueError, _('Not an interval spec: [+-] [#y] [#m] [#w] '
347 '[#d] [[[H]H:MM]:SS]')
349 info = m.groupdict()
350 for group, attr in {'y':'year', 'm':'month', 'w':'week', 'd':'day',
351 'H':'hour', 'M':'minute', 'S':'second'}.items():
352 if info[group] is not None:
353 setattr(self, attr, int(info[group]))
355 if self.week:
356 self.day = self.day + self.week*7
358 if info['s'] is not None:
359 self.sign = {'+':1, '-':-1}[info['s']]
361 def __repr__(self):
362 return '<Interval %s>'%self.__str__()
364 def pretty(self):
365 ''' print up the date date using one of these nice formats..
366 '''
367 if self.year:
368 if self.year == 1:
369 return _('1 year')
370 else:
371 return _('%(number)s years')%{'number': self.year}
372 elif self.month or self.day > 13:
373 days = (self.month * 30) + self.day
374 if days > 28:
375 if int(days/30) > 1:
376 s = _('%(number)s months')%{'number': int(days/30)}
377 else:
378 s = _('1 month')
379 else:
380 s = _('%(number)s weeks')%{'number': int(days/7)}
381 elif self.day > 7:
382 s = _('1 week')
383 elif self.day > 1:
384 s = _('%(number)s days')%{'number': self.day}
385 elif self.day == 1 or self.hour > 12:
386 if self.sign > 0:
387 return _('tomorrow')
388 else:
389 return _('yesterday')
390 elif self.hour > 1:
391 s = _('%(number)s hours')%{'number': self.hour}
392 elif self.hour == 1:
393 if self.minute < 15:
394 s = _('an hour')
395 elif self.minute/15 == 2:
396 s = _('1 1/2 hours')
397 else:
398 s = _('1 %(number)s/4 hours')%{'number': self.minute/15}
399 elif self.minute < 1:
400 if self.sign > 0:
401 return _('in a moment')
402 else:
403 return _('just now')
404 elif self.minute == 1:
405 s = _('1 minute')
406 elif self.minute < 15:
407 s = _('%(number)s minutes')%{'number': self.minute}
408 elif int(self.minute/15) == 2:
409 s = _('1/2 an hour')
410 else:
411 s = _('%(number)s/4 hour')%{'number': int(self.minute/15)}
412 return s
414 def get_tuple(self):
415 return (self.year, self.month, self.day, self.hour, self.minute,
416 self.second)
419 def test():
420 intervals = (" 3w 1 d 2:00", " + 2d", "3w")
421 for interval in intervals:
422 print '>>> Interval("%s")'%interval
423 print `Interval(interval)`
425 dates = (".", "2000-06-25.19:34:02", ". + 2d", "1997-04-17", "01-25",
426 "08-13.22:13", "14:25")
427 for date in dates:
428 print '>>> Date("%s")'%date
429 print `Date(date)`
431 sums = ((". + 2d", "3w"), (".", " 3w 1 d 2:00"))
432 for date, interval in sums:
433 print '>>> Date("%s") + Interval("%s")'%(date, interval)
434 print `Date(date) + Interval(interval)`
436 if __name__ == '__main__':
437 test()
439 #
440 # $Log: not supported by cvs2svn $
441 # Revision 1.21 2002/05/15 06:32:46 richard
442 # . reverting to dates for intervals > 2 months sucks
443 #
444 # Revision 1.20 2002/02/21 23:34:51 richard
445 # Oops, there's 24 hours in a day, and subtraction of intervals now works
446 # properly.
447 #
448 # Revision 1.19 2002/02/21 23:11:45 richard
449 # . fixed some problems in date calculations (calendar.py doesn't handle over-
450 # and under-flow). Also, hour/minute/second intervals may now be more than
451 # 99 each.
452 #
453 # Revision 1.18 2002/01/23 20:00:50 jhermann
454 # %e is a UNIXism and not documented for Python
455 #
456 # Revision 1.17 2002/01/16 07:02:57 richard
457 # . lots of date/interval related changes:
458 # - more relaxed date format for input
459 #
460 # Revision 1.16 2002/01/08 11:56:24 richard
461 # missed an import _
462 #
463 # Revision 1.15 2002/01/05 02:27:00 richard
464 # I18N'ification
465 #
466 # Revision 1.14 2001/11/22 15:46:42 jhermann
467 # Added module docstrings to all modules.
468 #
469 # Revision 1.13 2001/09/18 22:58:37 richard
470 #
471 # Added some more help to roundu-admin
472 #
473 # Revision 1.12 2001/08/17 03:08:11 richard
474 # fixed prettification of intervals of 1 week
475 #
476 # Revision 1.11 2001/08/15 23:43:18 richard
477 # Fixed some isFooTypes that I missed.
478 # Refactored some code in the CGI code.
479 #
480 # Revision 1.10 2001/08/07 00:24:42 richard
481 # stupid typo
482 #
483 # Revision 1.9 2001/08/07 00:15:51 richard
484 # Added the copyright/license notice to (nearly) all files at request of
485 # Bizar Software.
486 #
487 # Revision 1.8 2001/08/05 07:46:12 richard
488 # Changed date.Date to use regular string formatting instead of strftime -
489 # win32 seems to have problems with %T and no hour... or something...
490 #
491 # Revision 1.7 2001/08/02 00:27:04 richard
492 # Extended the range of intervals that are pretty-printed before actual dates
493 # are displayed.
494 #
495 # Revision 1.6 2001/07/31 09:54:18 richard
496 # Fixed the 2.1-specific gmtime() (no arg) call in roundup.date. (Paul Wright)
497 #
498 # Revision 1.5 2001/07/29 07:01:39 richard
499 # Added vim command to all source so that we don't get no steenkin' tabs :)
500 #
501 # Revision 1.4 2001/07/25 04:09:34 richard
502 # Fixed offset handling (shoulda read the spec a little better)
503 #
504 # Revision 1.3 2001/07/23 07:56:05 richard
505 # Storing only marshallable data in the db - no nasty pickled class references.
506 #
507 # Revision 1.2 2001/07/22 12:09:32 richard
508 # Final commit of Grande Splite
509 #
510 # Revision 1.1 2001/07/22 11:58:35 richard
511 # More Grande Splite
512 #
513 #
514 # vim: set filetype=python ts=4 sw=4 et si