Calendars

This chapter lists the calendars defined in the datetime2 package. The classes defining each calendar are not depending on the Date class.

All calendars listed here define the six standard comparison operators: <, >, ==, >=, <=, and !=, which return a meaningful result when comparing calendar objects of the same type. When comparing a calendar object with an object of a different type, the == and != operators always consider them to be unequal, while the <, >, >= and <= operators raise a TypeError exception.

Also, all calendars listed here conform to the rules listed in Customization. The descriptions below omit the comparison operators and the from_rata_die and to_rata_die methods.

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. Month will be between 1 and 12, day will be between 1 and the number of days in the corresponding month.

Two static method have been implemented to give 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 day of the year as an integer, 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 '-'.

    New in version 0.4: cformat() was added in version 0.4.

ISO calendar

The ISO calendar divides the days into weeks, from Monday to Sunday, and groups 52 or 53 whole weeks into a year. The first calendar week of a year is the one that includes the first Thursday of the corresponding Gregorian year. This definition can be seen also as: the first calendar weeks of a ISO year is the week including January, 4th Gregorian.

A good discussion of the ISO calendar can be read at The Mathematics of the ISO 8601 Calendar.

The constructor of an ISO calendar is:

class datetime2.modern.IsoCalendar(year, week, day)

Return an object that represents the date given with ISO year, week number and day. All arguments are required and must be integers. Values for week and day must lie in the following ranges:

  • 1 <= week <= number of weeks in the given year
  • 1 <= day <= 7

If an argument is outside those ranges, a ValueError exception is raised. They day number goes from 1 (Monday) to 7 (Sunday).

An IsoCalendar object has three attributes:

IsoCalendar.year
IsoCalendar.week
IsoCalendar.day

These attributes are read-only integer numbers. Week will be between 1 and the number of weeks in the ISO year (52 or 53), day will be between 1 and 7.

Two static method have been implmented to give details of an ISO year:

classmethod IsoCalendar.is_long_year(year)

Return True if year is a long year, i.e. a year with 53 weeks, in the ISO calendar, False otherwise. For example, IsoCalendar.is_leap_year(2004) == True.

classmethod IsoCalendar.weeks_in_year(year)

Return the number of weeks in a ISO year, either 52 or 53. For example, IsoCalendar.weeks_in_year(2009) == 53.

An instance of the IsoCalendar class has the following methods:

IsoCalendar.day_of_year()

Return the day of the year as an integer, from 1 to 364 (in short years) or 371 (in long years). For example, IsoCalendar(2008, 3, 1).day_of_year() == 62.

IsoCalendar.replace(year, week, day)

Returns a new IsoCalendar 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:

>>> iso = IsoCalendar(2004, 53, 3)
>>> print(iso.replace(week=26))
2004-W26-3
>>> iso.replace(year=2003)  # 2003 has 52 weeks
Traceback (most recent call last):
  |
ValueError: Week must be between 1 and number of weeks in year, while it is 53.
IsoCalendar.__str__()

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

>>> str(IsoCalendar(2002, 12, 4))
'2002-W12-4'
>>> str(IsoCalendar(-1, 1, 1))
'-0001-W01-1'
IsoCalendar.cformat(format)

Return a string representing the ISO 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)
%j Day of the year as a decimal number [001,371].  
%w Weekday as a decimal number [1 (Monday), 7 (Sunday)].  
%W Week number in the ISO year as a decimal number [01, 53].  
%y ISO year without century as a decimal number [00, 99]. (2)
%Y ISO year with century as a decimal number. At least four figures will be returned. (3)
%% A literal '%' character.  

Notes:

  1. The %a and %A 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 '-'.

    New in version 0.4: cformat() was added in version 0.4.