clockwise module

right! date and time.

(module name after the movie clockwise, starring monthy python john cleese)

class teafiles.clockwise.DateTime(year=1970, month=1, day=1, hours=0, minutes=0, seconds=0, milliseconds=0, ticks=None)

Holds a date and time value measured in milliseconds since the unix epoch 1970-01-01. This value, the number of “ticks”, is the only state maintained by this class.

1. Either ticks are passed, in which case all other arguments are ignored.
2. Otherwise all other arguments are used to compute the ticks to be stored.

• year: beween 1 .. 9999
• month: between 1 .. 12
• day: between 1 .. 31
• hours, minutes, seconds and milliseconds are not checked to be in any range, they are multiplied with their respective number of milliseconds and summed up to the value of _ticks.

>>> DateTime()
1970-01-01 00:00:00:000
>>> DateTime().ticks
0
>>> DateTime(1970, 1, 1).ticks
0
>>> DateTime(1970, 1, 2).ticks
86400000
>>> DateTime(ticks=427).ticks
427L
>>> DateTime(2000, 1, 1, 77, 88, 99, 5240000).ticks
946972619000L
>>> DateTime(2000, 1, 1, 77, 88, 99, 5240000, 11).ticks
11L

static parse(timestring, format)

Creates an instance by parsing <timestring> using <format>.

>>> DateTime.parse("2007-05-07 19:22:11", "%Y-%m-%d %H:%M:%S")
2007-05-07 19:22:11:000
>>> DateTime.parse("2007-04-09 09:22:11", "%Y-%m-%d %H:%M:%S")
2007-04-09 09:22:11:000
>>> DateTime.parse("2007-04-09", "%Y-%m-%d")
2007-04-09 00:00:00:000

ticks

Gets the internal representation of date and time, which are ticks, meaning the number of milliseconds since the epoch.

>>> from datetime import date
>>> DateTime().ticks
0
>>> DateTime(ticks=300).ticks
300L
>>> DateTime(2000, 1, 1).ticks
946684800000L
>>>

date

Returns the date part, that is a DateTime with a time of 00:00:00:000.

>>> t = DateTime(2000, 3, 4) + Duration(ticks=5000)
>>> t
2000-03-04 00:00:05:000
>>> t.date
2000-03-04 00:00:00:000
>>>

totimeandms()

Gets the date and time parts as a tuple holding (time.time, milliseconds). Since this method uses time.gmtime, errors with negative tick values can arise when using CPython (not in IronPython).

This method is used internally but can also serve as an interface to python’s standard library time.

>>> DateTime(2011, 4, 5, 22, 00, 14).totimeandms()
(time.struct_time(tm_year=2011, tm_mon=4, tm_mday=5, tm_hour=22, tm_min=0, tm_sec=14, tm_wday=1, tm_yday=95, tm_isdst=0), 0L)
>>> DateTime(2011, 4, 5, 22, 00, 14, 333).totimeandms()
(time.struct_time(tm_year=2011, tm_mon=4, tm_mday=5, tm_hour=22, tm_min=0, tm_sec=14, tm_wday=1, tm_yday=95, tm_isdst=0), 333L)
>>> DateTime().totimeandms()
(time.struct_time(tm_year=1970, tm_mon=1, tm_mday=1, tm_hour=0, tm_min=0, tm_sec=0, tm_wday=3, tm_yday=1, tm_isdst=0), 0)

Supported operations:

Operation	Result
t1 == t2	t1.ticks == t2.ticks
t1 != t2	t1.ticks != t2.ticks
t1 >  t2	t1.ticks > t2.ticks
t1 >= t2	t1.ticks >= t2.ticks
t1 <  t2	t1.ticks < t2.ticks
t1 <= t2	t1.ticks <= t2.ticks
d2 = d1 +  duration	adds duration, returning a new DateTime
t += Duration	adds duration to t assigning new DateTime to t
int(DateTime)	returns ticks
math.trunc(DateTime)	returns itself

class teafiles.clockwise.Duration(weeks=0, days=0, hours=0, minutes=0, seconds=0, milliseconds=0, ticks=None)

Stores a duration as number of milliseconds. In combination with DateTime provides time arithmetic.

>>> Duration(ticks=7000)      # 7000 milliseconds
0 days 00:00:07:000
>>> Duration(days=3)          # factory functions
3 days 00:00:00:000
>>> Duration(days=14) + Duration(hours=3) + 144
14 days 03:00:00:144

Initialize a duration from a number holding its milliseconds.

>>> from teafiles.clockwise import *
>>> Duration()
0 days 00:00:00:000
>>> Duration(ticks=3)
0 days 00:00:00:003
>>> Duration(ticks=1003)
0 days 00:00:01:003
>>> Duration(ticks=86400 + 1050)
0 days 00:01:27:450
>>> Duration(ticks=86400000 + 1050)
1 days 00:00:01:050

ticks

Returns the underlying number of ticks, that is the number of milliseconds.

>>> Duration(ticks=1033).ticks
1033L

totimedelta()

Converts the duration to a datetime.timedelta instance.

>>> Duration(ticks=33).totimedelta()
datetime.timedelta(0, 0, 33000)
>>> Duration(seconds=33).totimedelta()
datetime.timedelta(0, 33)
>>> Duration(minutes=33).totimedelta()
datetime.timedelta(0, 1980)
>>> Duration(hours=33).totimedelta()
datetime.timedelta(1, 32400)
>>> Duration(days=33).totimedelta()
datetime.timedelta(33)

Supported Operations:

Operation	Result
d1 == d2	d1.ticks == d2.ticks
d1 != d2	d1.ticks != d2.ticks
d1 >  d2	d1.ticks > d2.ticks
d1 >= d2	d1.ticks >= d2.ticks
d1 <  d2	d1.ticks < d2.ticks
d1 <= d2	d1.ticks <= d2.ticks
d = d1 + 2	adds both durations, returning new Duration
d += d2	adds d2 to d, assigning new Duration to d
int(Duration)	returns ticks
math.trunc(Duration)	returns itself

Utility functions

teafiles.clockwise.range(*args)

Overrides the range method, allowing DateTime ranges. Requires exactly 3 arguments to have effect (otherwise normal range method is called): start (DateTime), end (DateTime) and step (Duration)

>>> for t in range(DateTime(2000, 9, 1), DateTime(2001, 1, 1), Duration(weeks=2)):
...     print t
...
2000-09-01 00:00:00:000
2000-09-15 00:00:00:000
2000-09-29 00:00:00:000
2000-10-13 00:00:00:000
2000-10-27 00:00:00:000
2000-11-10 00:00:00:000
2000-11-24 00:00:00:000
2000-12-08 00:00:00:000
2000-12-22 00:00:00:000

teafiles.clockwise.rangen(startdate, stepduration, count)

Simple creation of DateTime sequences. Generate <count> DateTimes starting with <startdate> incremented by <stepduration>.

>>> for t in rangen(DateTime(2000, 9, 1), Duration(days=1), 10):
...     print t
...
2000-09-01 00:00:00:000
2000-09-02 00:00:00:000
2000-09-03 00:00:00:000
2000-09-04 00:00:00:000
2000-09-05 00:00:00:000
2000-09-06 00:00:00:000
2000-09-07 00:00:00:000
2000-09-08 00:00:00:000
2000-09-09 00:00:00:000
2000-09-10 00:00:00:000

teafiles.clockwise.isdatetime(value)

teafiles.clockwise.isduration(value)