datetime2 Documentation Release 0.7.6dev3 Francesco Ricciardi Jun 16, 2020 Contents 1 Indices and tables 5 1.1 Base classes...............................................5 1.2 Calendars.................................................9 1.3 Time of day................................................ 13 1.4 datetime2 customization......................................... 16 Python Module Index 21 Index 23 i ii datetime2 Documentation, Release 0.7.6dev3 A moment in history is independent from the way it is represented in different cultures. There are indeed many calendars in which the same day is represented in different ways. The datetime2 module detaches operations on time or date objects from their representation, and also allows to add other representations at run time. The module does all this in an efficient and syntactically clear way. A very simple internal representation has been chosen so that it becomes easy to convert this internal representation to the many different calendars. The idea, inspired by the excellent book “Calendrical Calculations”2, 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 the datetime2 module we write: >>> d1= Date(1) # January 1st, 1 >>> d2= Date(737109) # February 19th, 2019 However entering dates in this way is nearly useless, but the module comes in help. E.g. we can use the Gregorian calendar or the ISO calendar: >>> d3= Date.gregorian(1965,3,1) # Gregorian: 1965-03-01 >>> d4= Date.iso(2011,1,1) # ISO: 2011-W01-1 Similarly, each Date object can be printed with the internal representation: >>> print(d3) 717396 >>> print(d4) 734140 And again, this way of using the day is nearly useless. But you can use attributes also on Date objects to access different representations: >>> print(d1.gregorian) 0001-01-01 >>> print(d2.gregorian) 2019-02-19 >>> print(d4.gregorian) 2011-01-03 >>> print(d1.iso) 0001-W01-1 >>> print(d2.iso) 2019-W08-2 >>> print(d3.iso) 1965-W09-1 As you can see, it is not required to use the same calendar with which an object has been created. Each calendar also presents different attributes that can be accessed as usual. These may be components of the date, like in: >>> print(d2.gregorian.year) 2019 >>> print(d3.iso.week) 9 But also other date attributes: >>> print(d3.gregorian.weekday()) 1 (continues on next page) 2 “Calendrical Calculations: The Ultimate Edition”, E. M. Reingold, N. Dershowitz, Cambridge University Press, 2018, and all its previous versions Contents 1 datetime2 Documentation, Release 0.7.6dev3 (continued from previous page) >>> print(d3.gregorian.day_of_year()) 60 Finally, Date objects can often be created with other constructors: >>> print(Date.gregorian.year_day(2020, 120).gregorian) # the 120th day of 2020 2020-04-29 Although there exist much less time representations, the datetime2 module uses the same reasoning to represent the time of the day: a moment of the day is represented as a fraction of the day, starting from midnight. In the following examples we use the Decimal Time, a subdivision of days in 10 hours of 100 minutes, each minute being 100 seconds. >>> t1= Time((7, 10)) >>> print(t1.western) 16:48:00 >>> print(t1.decimal) 7:00:00 As with dates, also time can be entered and printed with different representations, and also the time of day representa- tions have attributes, methods and alternate constructors: >>> t2= Time.western(15, 47, 16) >>> t3= Time.decimal(4, 83, 18) >>> print(t2.decimal) 6:55:06 >>> print(t3.western) 11:35:46 >>> print(t3.western.minute) 35 >>> print(t3.western.to_hours()) Fraction(72477, 6250) >>> t4= Time.western.in_minutes(1000) >>> print(t4) 25/36 of a day >>> print(t4.western) 16:40:00 >>> print(t4.decimal) 6:94:44 The reference between time objects can be either implicit time, i.e. depending on implementation (it usually is the local time,but can also be UTC). It is also possible to have an explicit reference to UTC, passed as an additional parameter to the object constructor. In the first case the Time object is said to be “naive”, in the second case it is said to be “aware”. As in dates and time classes, also the time to UTC is indicated by a culturally independent value, i.e. a fraction of a day. Additional time representations can support naive references, or are implicitly aware. >>> t5= Time('2/3', to_utc=(1, 12)) >>> print(t8) 2/3 of a day, 1/12 of a day to UTC >>> print(t5.western) 16:00:00+02 >>> t6= Time.internet(456) >>> print(t6.western) 10:56:03+01 2 Contents datetime2 Documentation, Release 0.7.6dev3 The Internet time is by definition on Basel time zone. This is equivalent to central Europe time zone, but doesnt have daylight saving time. Other prominent features of the datetime2 module are the ability to add other representations at run time and the fact that representations do not consume memory unless they are effectively used (this is especially important for calendars, where many representation exists1 ). Currently (version 0.7.6dev3) the following calendars and time representations are available: Module Calendar(s) Time representation(s) datetime2.western Gregorian Western datetime2.modern ISO Internet See also: Module datetime Basic date and time types. Module calendar General calendar related functions. Module time Time access and conversions. 1 Well, this should be read as “will exist”, since current version (0.7.6dev3) only has two of them. Contents 3 datetime2 Documentation, Release 0.7.6dev3 4 Contents CHAPTER 1 Indices and tables 1.1 Base classes The heart of the datetime2 module is made of four base classes, each having a very simple definition. All base classes implement operations for date and time independently of the way they are created. datetime2 class names use the CapitalizedWords convention required by PEP 8, so they differ from the names of their similar counterparts in datetime module. 1.1.1 Date objects A Date object represents a date in an idealized calendar, just counting the days elapsed from Gregorian Dec 31st of year 0, i.e. January 1st of year 1 is day number 1, January 2nd of year 1 is day number 2, and so on. This calendar ideally extends indefinitely in both directions. There are two ways of creating a Date instance: class Date(day_count) Return an object that represent a date which is day_count - 1 days after January 1:sup:st of year 1 of the current Gregorian calendar. The argument is required and must be an integer; there is no restriction on its numeric value. Using any other type of parameter, a TypeError exception is raised. classmethod Date.today() Return a Date object that represents the current local date. Date instances are immutable, so they can be used as dictionary keys. They can also be pickled and unpickled. In boolean contexts, all Date instances are considered to be true. Date instances have one attribute: Date.day_count An integer that represents the number of days between the given date and January 1st, year 1. This attribute is read-only: an AttributeError exception is raised when trying to change it. Date has one instance method: 5 datetime2 Documentation, Release 0.7.6dev3 Date.__str__() Return R.D. followed by the day count. R.D. stands for Rata Die, the Latin for “fixed date”. The following table lists all available calendars and the attributes by which they are reachable: Calendar Access attribute Calendar class Module Gregorian gregorian GregorianCalendar datetime2.western ISO iso IsoCalendar datetime2.modern Supported operations Operation Result date2 = date1 + date2 is timedelta days after date1. Reverse addition (timedelta + timedelta date1) is allowed. (1) (2) date2 = date1 - date2 is timedelta days before date1. (1) (3) timedelta timedelta = date1 - A TimeDelta object is returned representing the number of days between date1 date2 and date2. (4) date1 < date2 date1 is less than date2 when it represents a day earlier that that of date2. (5) (6) Notes: (1)A ValueError exception is raised if timedelta is not an integral number of days. timedelta object with non- integral number of days must be added or subtracted from DateTime instances. (2) If timedelta is negative, date2 will be before date1. (3) If timedelta is negative, date2 will be after date1. (4) The timedelta instance created when subtracting Date instances will always have an integral number of days, positive if date1 is later than date2, negative otherwise. (5) In other words, date1 < date2 if and only if date1.day_count < date2.day_count. All other comparison operators (<=, >, >=, == and !=) behave similarly. (6) When comparing a Datee object and an object of another class, if the latter has a day_count attribute, NotImplemented is returned. This allows a Date-like instance to perform reflected comparison if it is the second operator. When the second object doesn’t have a day_count attribute, if the operator is equality(==) or inequality(!=), the value returned is always False and True respectively. If the operator is one of the other four (<=, >, >= or ==), a TypeError exception is raised. 1.1.2 Time objects Warning: This version of the documentation is under revision for the part concerning the correction of local time for UTC. Code and tests about this part are under development. An indication of time, independent of any particular day, expressed as a fraction of day. There might be an indication of time difference to UTC, e.g. due to time zone or daylight saving time. This time difference is expressed as fraction of a day and represents the time to be added to local time to get UTC. If there is this indication, the Time object is said to be “aware” and it is used to represent a precise moment (regardless of the day).