datetime2.western - Gregorian calendar and western time

This module implements the calendar and time representation used in the western world:

Of course, they all conform to the requirements for interface classes listed in Customization.

Gregorian calendar

An instance of the GregorianCalendar class represents a day in the calendar as generally done in western countries. It is a solar calendar dividing day count in years of 365 or 366 days, each year is then divided in 12 months of 28 (or 29), 30 and 31 days.

The default constructor for a Gregorian day is:

class datetime2.western.GregorianCalendar(year, month, day)

Return an object that represents the date given with Gregorian year, month and day. Month is entered as a number, not as a string. All arguments are required and must be integers. Values for month and day must lie in the following ranges:

  • 1 <= month <= 12
  • 1 <= day <= number of days in the given month and year

If an argument is outside those ranges, a ValueError exception is raised.

Another constructor can be used if the day in the year is known:

classmethod GregorianCalendar.year_day(year, day_of_year)

Return an object that represents the day specified by a Gregorian year and the day in that year. Both arguments are required and must be integers. Value for day_of_year must be between 1 and the number of days in the year (either 365 or 366), otherwise a ValueError exception is raised.

A GregorianCalendar object has three attributes:

GregorianCalendar.year
GregorianCalendar.month
GregorianCalendar.day

These attributes are read-only integer numbers. There is no restriction on the value of the year. Month will be between 1 and 12. Day will be between 1 and the number of days in the corresponding month. These attributes are read-only: an AttributeError exception is raised when trying to change any of them.

Two static method have been implemented to return details of a Gregorian year:

static GregorianCalendar.is_leap_year(year)

Return True if year is a leap year in the Gregorian calendar. False otherwise. For example, GregorianCalendar.is_leap_year(2008) == True.

static GregorianCalendar.days_in_year(year)

Return 366 if year is a leap year in the Gregorian calendar, 365 otherwise. For example, GregorianCalendar.days_in_year(2100) == 365.

An instance of the GregorianCalendar class has the following methods:

GregorianCalendar.weekday()

Return the day of the week as an integer, where Monday is 1 and Sunday is 7. For example, GregorianCalendar(2002, 12, 4).weekday() == 3, a Wednesday. Note that this is the ISO convention for weekdays, not the one used by datetime.date.weekday(), where Monday is 0 and Sunday is 6.

GregorianCalendar.day_of_year()

Return the number of days elapsed since January 1st. The result is a number from 1 to 365 or 366 (in leap years). For example, GregorianCalendar(2008, 3, 1).day_of_year() == 61.

GregorianCalendar.replace(year, month, day)

Returns a new GregorianCalendar object with the same value, except for those parameters given new values by whichever keyword arguments are specified. All values are optional; if used, they must be integers. If any argument is outside its validity range or would create an invalid Gregorian date, a ValueError exception is raised. For example:

>>> greg = GregorianCalendar(2002, 12, 31)
>>> print(greg.replace(day=26))
2002-12-26
>>> greg.replace(month=11)         # November has 30 days
Traceback (most recent call last):
  |
ValueError: Day must be between 1 and number of days in month, while it is 31.
GregorianCalendar.__str__()

Return a string representing the date with the ‘YYYY-MM-DD’ format. Years above 9999 are represented adding necessary figures. Negative years are represented prepending the minus sign. For example:

>>> str(GregorianCalendar(2002, 12, 4))
'2002-12-04'
>>> str(GregorianCalendar(-1, 1, 1))
'-0001-01-01'
GregorianCalendar.cformat(format)

Return a string representing the date, controlled by an explicit format string. The formatting directives are a subset of those accepted by datetime.date.strftime(), and their meaning does not depend on the underlying C library (i.e. there are no platform variations). The table below lists the accepted formatting directives, all other character are not interpreted.

Directive Meaning Notes
%a Abbreviated weekday name. (1)
%A Full weekday name. (1)
%b Abbreviated month name. (1)
%B Full month name. (1)
%d Day of the month as a decimal number [01, 31].  
%j Day of the year as a decimal number [001, 366].  
%m Month as a decimal number [01, 12].  
%U Week number of the year (Sunday as the first day of the week) as a decimal number [00, 53]. All days in a new year preceding the first Sunday are considered to be in week 0.  
%w Weekday as a decimal number [1 (Monday), 7 (Sunday)].  
%W Week number of the year (Monday as the first day of the week) as a decimal number [00, 53]. All days in a new year preceding the first Monday are considered to be in week 0.  
%y Year without century as a decimal number [00, 99]. (2)
%Y Year with century as a decimal number. At least four figures will be returned. (3)
%% A literal '%' character.  

Notes:

  1. The %a, %A, %b and %B directives return a localized name in Standard C++. This is not true for datetime2, which only returns English names.
  2. Since this is a truncated representation, negative years will not have a sign.
  3. Negative years will have a trailing '-'.

Western time

An instance of the WesternTime class represents a moment of a day as generally done in western countries, dividing each day in 24 hours, each hour in 60 minutes and each minute in 60 seconds.

The default western time constructor is:

class datetime2.western.WesternTime(hour, minute, second, timezone=None)

Return an object that represents the moment of a day in hour, minute and second elapsed from midnight. This representation does not take into account the possibility of one or two additional seconds that sometimes are added in specific dates to compensate earth rotation. All arguments except timezone are required. The following requirements must be satisfied:

  • hour must be an integer and 0 <= hour < 24
  • minute must be an integer and 0 <= minute < 60
  • second must be a rational number and its value must be 0 <= second < 60
  • timezone, if present, must be a rational number and its value must be -24 <= timezone <= 24

Here a rational number is anything that can be passed to the fractions.Fraction constructor, i.e. an integer, a float, another Fraction, a Decimal number or a string representing an integer, a float or a fraction.

If an argument is not of the accepted type, a TypeError exception is raised. If an argument is outside its accepted range, a ValueError exception is raised.

The timezone argument, if present, makes the object aware and defines the number of hours that must be added to UTC to get local time.

Note

The timezone parameter is likely to change its values in future.

A WesternTime object has four attributes, all of which are read-only numbers: an attempt to change them will raise an AttributeError exception. These attributes store the corresponding values in the constructor:

WesternTime.hour

An integer with values between 0 and 23.

WesternTime.minute

An integer with values between 0 and 59.

WesternTime.second

A Python Fraction with value grater or equal to 0 and less than 60.

WesternTime.timezone

If this attribute is not None, it a Python Fraction with values between -24 and 24.

An instance of the WesternTime class has the following methods:

WesternTime.replace(hour, minute, second, *, timezone)

Returns a new WesternTime object with the same value, except for those parameters given new values by whichever keyword arguments are specified. The value, if given, they must respect the same requirements of the default constructor, otherwise a TypeError or ValueError exception is raised. timezone parameter can be replaced only for aware instances. For example:

>>> my_time = WesternTime(19, 6, 29)
>>> print(my_time.replace(minute=38))
19:38:29
>>> my_time.replace(hour=24)
Traceback (most recent call last):
  |
ValueError: Hour must be between 0 and 23, while it is 24.
>>> my_time.replace(timezone=1)
Traceback (most recent call last):
  |
TypeError: Can replace timezone only in aware instances.
WesternTime.__str__()

For a naive instance, return a string representing the time with the ‘HH:MM:SS’ format. For an aware instance, the format is ‘HH:MM:SS+HH:MM’. The number of seconds in the time part and the number of minutes in the timezone part will be truncated. For example:

>>> str(WesternTime(12, 44, 14.8))
'12:44:14'
>>> str(WesternTime(12, 34, 56.7, timezone=12.256))
'12:34:56+12:15'
WesternTime.cformat(format)

Return a string representing the time, controlled by an explicit format string. The formatting directives are a subset of those accepted by datetime.date.strftime(), and their meaning does not depend on the underlying C library (i.e. there are no platform variations). The table below lists the accepted formatting directives, all other characters are not interpreted.

Directive Meaning Notes
%H Hour (24-hour clock) as a zero-padded decimal number [00, 23].  
%I Hour (12-hour clock) as a zero-padded decimal number [01, 12].  
%p Returns ‘AM’ if hour is between 0 and 11, ‘PM’ if hour is between 12 and 23. (1)
%M Minute as a zero-padded decimal number [00, 59].  
%S Second as a zero-padded decimal number [00, 59].  
%f Microsecond as a decimal number, zero-padded on the left [000000, 999999].  
%z UTC offset in the form ±HHMM[SS[.ffffff]] (empty string if the object is naive).  
%% A literal '%' character.  

Notes:

  1. The %p directive returns a localized string in Standard C++. This is not true for datetime2, which only returns the English string.

Western time interval

An instance of the WesternTimeDelta class represents a time interval given in days, hours, minutes and seconds.

The default constructor is:

class datetime2.western.WesternTimeDelta(days, hours, minutes, seconds)

Return an object that represents a time interval in hours, minutes and seconds. All arguments are required. hours, minutes and seconds must have the same sign of days. The types and absolute values of each parameter are listed below:

  • days must be an integer of any value
  • hours must be an integer and its absolute value must be 0 <= hours <= 23
  • minutes must be an integer and its absolute value must be 0 <= minutes <= 59
  • seconds must be a rational number and its absolute value must be 0 <= second < 60

Here a rational number is anything that can be passed to the fractions.Fraction constructor, i.e. an integer, a float, another Fraction, a Decimal number or a string representing an integer, a float or a fraction.

If an argument is not of the accepted type, a TypeError exception is raised. If an argument is outside its accepted range or all parameter haven’t the same sign, a ValueError exception is raised.

A WesternTimeDelta object has four attributes, all of which are read-only numbers: an attempt to change them will raise an AttributeError exception. These attributes store the corresponding values in the constructor:

WesternTime.days

An integer of any value.

WesternTime.hours

An integer of the same sign as days and with absolute value between 0 and 23.

WesternTime.minutes

An integer of the same sign as days and with absolute value between 0 and 59.

WesternTime.seconds

A Python Fraction of the same sign as days and with absolute value grater or equal to 0 and less than 60.

An instance of the WesternTimeDelta class has the following methods:

WesternTimeDelta.replace(days, hours, minutes, seconds)

Returns a new WesternTimeDelta object with the same value, except for those parameters given new values by whichever keyword arguments are specified. The value, if given, they must respect the same requirements of the default constructor, otherwise a TypeError or ValueError exception is raised. For example:

>>> my_td = WesternTimeDelta(1, 23, 45, 6)
>>> print(my_td.replace(minutes=0))
1 day, 23 hours and 6 seconds
>>> my_td.replace(hours=24)
Traceback (most recent call last):
  |
ValueError: Hours must be between 0 and 23, while it is 24.
>>> my_time.replace(secondsì'33')
Traceback (most recent call last):
  |
ValueError: Seconds must be of the same sign of 'days'.
WesternTimeDelta.__str__()

Return a string representing the time interval. When a component of the interval is zero, it is not printed. The number of seconds will be truncated. For example:

>>> str(WesternTimeDelta(9, 8, 7, 6.5))
'9 days, 8 hours, 7 minutes and 6 seconds'
>>> str(WesternTimeDelta(0, 0, -5, -2))
'-5 minutes and -2 seconds'
WesternTimeDelta.cformat(format)

Return a string representing the time, controlled by an explicit format string. The formatting directives are a subset of those accepted by datetime.date.strftime(), and their meaning does not depend on the underlying C library (i.e. there are no platform variations). The table below lists the accepted formatting directives, all other characters are not interpreted.

Directive Meaning
%d Full days as a decimal number.
%H Hours as a zero-padded decimal number [00, 23].
%M Minutes as a zero-padded decimal number [00, 59].
%S Seconds as a zero-padded decimal number [00, 59].
%f Microseconds as a zero-padded decimal number [000000, 999999].
%% A literal '%' character.