Time of day

This chapter lists the time representations classes defined in the datetime2 package. These classes are not depending on the Time class. Note that these time representations do not have any notion of time correction like daylight saving time or time zone.

All time representations listed here define the six standard comparison operators: <, >, ==, >=, <=, and !=, which return a meaningful result when comparing time representation objects of the same type. When comparing a time representation 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 time representations listed here conform to the rules listed in Customization. The descriptions below omit the comparison operators and the from_day_frac and to_day_frac methods.

In the following we will call a Python number anything that can be passed to a Fraction constructor, i.e. an integer, a float, another Fraction, a Decimal number or a string representing an integer, a float or a fraction.

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.

There are four constructors for a western time. The default one is:

class western.WesternTime(hour, minute, second)

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 are required and must satisfy the following requirements:

  • hour must be an integer and 0 <= month <= 23
  • minute must be an integer and 0 <= minute <= 59
  • second must be a Python number; its value must be 0 <= second < 60

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 other three constructors are:

class datetimeWesternTime.in_hours(hour)

Return an object that represents the moment of the day specified in hours, possibly fractional, elapsed from midnight. The argument must be a Python number, otherwise a TypeError exception is raised. Its value must be greater or equal to 0 and less than 24, otherwise a ValueError exception is raised.

class WesternTime.in_minutes(minute)

Return an object that represents the moment of the day specified in minutes, possibly fractional, elapsed from midnight. The argument must be a Python number, otherwise a TypeError exception is raised. Its value must be greater or equal to 0 and less than 1440, otherwise a ValueError exception is raised.

class WesternTime.in_seconds(second)

Return an object that represents the moment of the day specified in seconds, possibly fractional, elapsed from midnight. The argument must be a Python number, otherwise a TypeError exception is raised. Its value must be greater or equal to 0 and less than 86400, otherwise a ValueError exception is raised.

A WesternTime object has three attributes:

western.hour
western.minute
western.second

These attributes are read-only numbers. The first two are integers; the last one is a Python Fraction. The three attributes will respect the value requirements listed in the default constructor description.

An instance of the WesternTime class has the following methods:

western.as_hours()

Return a Python Fraction representing the moment of the day in hours. Thus the returned value will be equal or greater than 0, and less than 24.

western.as_minutes()

Return a Python Fraction representing the moment of the day in minutes. Thus the returned value will be equal or greater than 0, and less than 1440.

western.as_seconds()

Return a Python Fraction representing the moment of the day in seconds. Thus the returned value will be equal or greater than 0, and less than 86400.

western.replace(hour, minute, second)

Returns a new WesternTime 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 respect the requirements of the default constructor, otherwise a TypeError or ValueError exception is raised. 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.
western_time.__str__()

Return a string representing the time with the ‘HH:MM:SS’ format. Any decimal will be truncated from the number of seconds. For example:

>>> str(WesternTime(12, 44, 14.8))
'12:44:14'
western_time.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 character 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].  
%% 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.

Internet time

The Internet Time (or beat time) is a decimal time concept introduced in 1998, marketed by a large Swiss watch company, and divides the day in 1000 parts, called “beats”. A beat is equivalent to 1 minute and 26.4 seconds. A Wikipedia article well describes the Internet time.

The default constructor for Internet time is:

class datetime2.InternetTime(beat)

Return an object that represents the time in thousandths of a day. The beat argument is required and must be Python number; its value must be equal or greater than 0 and less than 1000. If the argument is not a Python number, a TypeError exception is raised. If the argument is outside its accepted range, a ValueError exception is raised.

An InternetTime object has one attribute:

internet_time.beat

This attribute is a read-only Python Fraction greater than or equal 0 and less than 1000.

and the following methods:

internet_time.__str__()

Return a string representing the moment of the day in beats, '@BBB‘ format. For example:

>>> str(InternetTime(345.25))
'@345'
internet_time.cformat(format)

Return a string representing the Internet time, controlled by an explicit format string with formatting directives close to that used in C. The table below lists the accepted formatting directives, all other character are not interpreted.

Directive Meaning Notes
%b Integer number of beats [000, 999].  
%f Thousandths of a beat, zero-padded on the left [000, 999]. (1)

Notes:

  1. One thousandth of a beat is a millionth of a day, i.e. 86.4 milliseconds.