datetime2
introduction¶
The definition of a moment in history is independent from the way it is
represented in different cultures. Indeed the same day is represented in
different ways by different calendars. The datetime2
module detaches
operations on date and time objects from their representation, and allows to
add other representations at run time. The module does all this in an
efficient and syntactically clear way.
We can create a date object by calling the relevant access attribute of the
base class Date
:
>>> d1 = Date.gregorian(1965, 3, 1) # Gregorian: 1965-03-01
>>> d2 = Date.iso(2011, 23, 4) # ISO: 2011-W23-4
Each of these date objects can be printed and has its own attributes and methods:
>>> print(d1.gregorian)
1965-03-01
>>> print(d1.gregorian.month)
3
>>> print(d1.gregorian.weekday())
1
>>> print(d2.iso)
2011-W23-4
>>> print(d2.iso.week)
23
>>> print(d2.iso.day_of_year())
158
One of the strength of datetime2
is that we can mix these attributes,
independently from how the date object is built:
>>> print(d1.iso)
1965-W09-1
>>> print(d1.iso.week)
9
>>> print(d1.iso.day_of_year())
57
>>> print(d2.gregorian)
2011-06-09
>>> print(d2.gregorian.month)
6
>>> print(d2.gregorian.weekday())
4
The same strength is true also for time, where different representations can be mixed like in dates:
>>> t1 = Time.western(15, 47, 16, timezone=-6)
>>> t2 = Time.internet(895)
>>> print(t1.western)
15:47:16-06:00
>>> print(t1.internet)
@949
>>> print(t2.western)
21:28:48+01:00
>>> print(t2.western.minute)
28
The relation between time objects can be either implicit, i.e. depending on
implementation, or explicit, which means that the objects know how they
relate to each other. Then standard way for the latter is with UTC. An object
of the first kind is said to be naive, of the second kind is called aware
(like in Aware and Naive Objects of the datetime
module). For
aware objects a second value is used in the constructor to indicate the
distance from UTC.
Many representations of the time of day of this module are aware by definition, so in those cases the UTC offset must not be given. E.g., the Internet time representation is based on Basel time zone (UTC+1).
Internal representation¶
In order to be able to convert between the different calendars and between
the different times of day, a generic and culturally independent way of
internally representing them has been chosen. For calendars, the idea,
inspired by the excellent book “Calendrical Calculations”[1], is to
identify each day by simply counting the days starting with 1 for January
1st of year 1, 2 for January 2nd is day 2, and so on. Using
the datetime2
module we write:
>>> d3 = Date(1)
>>> d4 = Date(737109)
These dates can then be handled like above:
>>> print(d3.gregorian)
0001-01-01
>>> print(d3.iso)
0001-W01-1
>>> print(d4.gregorian)
2019-02-19
>>> print(d4.iso)
2019-W08-2
Similarly, each Date
object can be printed with the internal
representation (even if it is of little use):
>>> print(d1)
R.D. 717396
>>> print(d2)
R.D. 734297
Where R.D.
stands for Rata Die, the Latin for “fixed date”.
There are similar generic representations for all base classes of the
datetime2
module:
Time
: a moment of the day is represented as a fraction of the day, starting from midnight. Distance from UTC, if given is also given as a fraction of a day.
>>> print(t1)
14209/21600 of a day, -1/4 of a day from UTC
>>> print(t2)
179/200 of a day, 1/24 of a day from UTC
>>> t3 = Time(7, 10)
>>> t4 = Time(0.796875, utcoffset="1/4")
>>> print(t3.western)
16:48:00
>>> print(t4.western)
19:07:30+06:00
>>> print(t4.internet)
@588
TimeDelta
: a time interval is given in number of days, possibly fractional to account for parts of day.
>>> td1 = TimeDelta(8, 10)
>>> print(td1)
4/5 of a day
>>> print(td1.western)
19 hours, 12 minutes
>>> td2 = TimeDelta(118, 12)
>>> print(td2)
9 days and 5/6 of a day
>>> print(td2.western)
9 days and 20 hours
Index¶
datetime2
- New date and time typesdatetime2.western
- Gregorian calendar and western time- Gregorian calendar
GregorianCalendar
GregorianCalendar.year_day()
GregorianCalendar.year
GregorianCalendar.month
GregorianCalendar.day
GregorianCalendar.is_leap_year()
GregorianCalendar.days_in_year()
GregorianCalendar.weekday()
GregorianCalendar.day_of_year()
GregorianCalendar.replace()
GregorianCalendar.__str__()
GregorianCalendar.cformat()
- Western time
- Western time interval
- Gregorian calendar
datetime2.modern
- ISO calendar and Internet time- datetime2 customization