Date/time module¶

Module functions¶

datetime.now()¶

Returns a new DateTime object that is set to the current date and time on this computer expressed as local time. The time zone is not stored in the returned object.

For example, if the computer clock shows January 1, 2001, at 1:37 pm UTC+2, the object will represent the date 2025-01-01T13:37:00.

Return type:

DateTime

datetime.utcNow()¶

Returns a new DateTime object that is set to the current date and time in the UTC+0 time zone based on the current date and time of this computer. The time zone is not stored in the returned object.

For example, if the computer clock shows January 1, 2001, at 1:37 pm UTC+2, the object will represent the date 2025-01-01T11:37:00.

Return type:

DateTime

datetime.today()¶

Returns a new DateTime that is set to today’s date, with the time component set to 00:00:00.0.

Return type:

DateTime

datetime.isLeapYear(year)¶

Returns true if the year, given as an integer, is a leap year.

Return type:

bool

datetime.date(year, month, day)¶

Returns a new DateTime object that is set to the given year, month and day. The time component of the datetime object will be set to 00:00:00.0. If any component of the date is outside the specified limits an exception is thrown.

Parameters:

• year (int) – Year between [1400, 9999].

• month (int) – Month between [1, 12].

• day (int) – Day between [1, 31].

Return type:

DateTime

datetime.date(year, month, day, hour, minute, second)

Returns a new DateTime object that is set to the given year, month, day, hour, minute and second. If any component of the date is outside the specified limits an exception is thrown.

Parameters:

• year (int) – Year between [1400, 9999].

• month (int) – Month between [1, 12].

• day (int) – Day between [1, 31].

• hour (int) – Hour between [0, 23].

• minute (int) – Minute between [0, 59].

• second (int) – Second between [0, 59].

Return type:

DateTime

datetime.dateWithTime(year, month, day, hour, minute, second, milliseconds)¶

Returns a new DateTime object that is set to the given year, month, day, hour, minute, second and milliseconds. If any component of the date is outside the specified limits an exception is thrown.

Parameters:

• year (int) – Year between [1400, 9999].

• month (int) – Month between [1, 12].

• day (int) – Day between [1, 31].

• hour (int) – Hour between [0, 23].

• minute (int) – Minute between [0, 59].

• second (int) – Second between [0, 59].

• milliseconds (int) – Milliseconds between [0, 999].

Return type:

DateTime

datetime.dateWithTimeAndMillis(year, month, day, hour, minute, second, milliseconds)¶

Returns a new DateTime object that is set to the given year, month, day, hour, minute, second and milliseconds. If any component of the date is outside the specified limits an exception is thrown.

Parameters:

• year (int) – Year between [1400, 9999].

• month (int) – Month between [1, 12].

• day (int) – Day between [1, 31].

• hour (int) – Hour between [0, 23].

• minute (int) – Minute between [0, 59].

• second (int) – Second between [0, 59].

• milliseconds (int) – Milliseconds between [0, 999].

Return type:

DateTime

datetime.fromEpochSeconds(epochSeconds)¶

Returns a new DateTime object that is set to the date and time corresponding to the given number of seconds since 1970-01-01T00:00:00 (the Unix epoch). The time zone is not stored in the returned object.

Parameters:

epochSeconds (int) – Number of seconds since 1970-01-01T00:00:00.

Return type:

DateTime

datetime.fromEpochMilliseconds(epochMilliseconds)¶

Returns a new DateTime object that is set to the date and time corresponding to the given number of milliseconds since 1970-01-01T00:00:00 (the Unix epoch). The time zone is not stored in the returned object.

Parameters:

epochMilliseconds (int) – Number of milliseconds since 1970-01-01T00:00:00.

Return type:

DateTime

datetime.parse(text, format)¶

Parses text according to the specified format string and returns a new DateTime object.

Supported format specifiers are listed in the Date format table. If parts of the date or time are missing, they default to today’s date or to 00:00:00.0 for the time.

The parser is case-insensitive for month, day, and AM/PM names. Invalid or out-of-range values (such as month=13, day=32, or hour=25) cause an error.

Parameters:

• text (string) – String to be converted to DateTime object.

• format (string) – Format to follow

Return type:

DateTime

datetime.span(nbHours, nbMinutes, nbSeconds)¶

datetime.span(nbDays, nbHours, nbMinutes, nbSeconds)

datetime.span(nbDays, nbHours, nbMinutes, nbSeconds, nbMilliseconds)

Returns a new TimeSpan object representing the given number of days plus hours, minutes, seconds and milliseconds. Depending on the signature of the method used, the number of days and milliseconds are optional. The returned duration may be negative.

Parameters:

• nbDays (int) – Number of days. Optional. Can be negative.

• nbHours (int) – Number of hours. Can be negative.

• nbMinutes (int) – Number of minutes. Can be negative.

• nbSeconds (int) – Number of seconds. Can be negative.

• nbMilliseconds (int) – Number of millis. Optional. Can be negative.

Return type:

TimeSpan

DateTime¶

Represents an instant in time, expressed as a date and time of day. The time is accurate to the millisecond.

The DateTime object does not contain any time zone information. It can handle dates from January 1, 1400 at 00:00:00.0 to December 31, 9999 at 23:59:59.999. Any date outside these limits will generate an exception.

Furthermore, all DateTime instances are immutable. In other words, manipulations on dates always return new objects without modifying the state of the current objects.

class DateTime¶

date¶

Returns the date component of the current DateTime instance. The returned object has the same date as this instance, and its time component set to midnight (00:00:00.0).

Return type:

DateTime

year¶

Gets the year component of the date represented by this DateTime instance.

Return type:

int

month¶

Gets the month component of the date represented by this DateTime instance. The month component is expressed as an integer between 1 and 12.

Return type:

int

day¶

Gets the day of the month represented by this DateTime instance. The day of the month is expressed as an integer between 1 and 31.

Return type:

int

dayOfWeek¶

Gets the day of the week represented by this DateTime instance. The day of the week is expressed as an integer between 1 and 7 where 1 represents Monday and 7 represents Sunday (according to ISO-8601 standard).

Return type:

int

dayOfYear¶

Gets the day of the year represented by this DateTime instance. The day of the year is expressed as an integer between 1 and 366.

Return type:

int

hour¶

Gets the hour component of the date represented by this DateTime instance. The hour component is expressed as an integer between 0 and 23.

Return type:

int

minute¶

Gets the minute component of the date represented by this DateTime instance. The minute component is expressed as an integer between 0 and 59.

Return type:

int

second¶

Gets the second component of the date represented by this DateTime instance. The second component is expressed as an integer between 0 and 59.

Return type:

int

millisecond¶

Gets the millisecond component of the date represented by this DateTime instance. The millisecond component is expressed as an integer between 0 and 999.

Return type:

int

add(timespan)¶

Returns a new DateTime object that adds the duration of the specified TimeSpan to the value of this instance.

The returned time can be before or after the time represented by the current instance, depending on whether the interval represents a positive or negative duration.

Instead of using this method, it is also possible to directly use the overload of the + operator which has the same effect: currentDate + timespan == currentDate.add(timespan).

Parameters:

timespan (TimeSpan) – A positive or negative time interval.

Return type:

DateTime

addYears(nbYears)¶

Returns a new DateTime object that adds the number of years to the value of this instance.

This method takes leap years into account as follows:

• If the date of the current object is not February 29, this method returns a new date added or subtracted from the specified number of years without further modification.

• If the current date is February 29 and the target year is also a leap year: the target is set to February 29. If the target year is not a leap year, the target date is set to February 28.

Parameters:

nbYears (int) – Positive or negative number of years.

Return type:

DateTime

addMonths(nbMonths)¶

Returns a new DateTime object that adds the number of months to the value of this instance.

To calculate the result, this method starts by removing the number of months specified in parameter, then adjusts the day part of the DateTime object to take into account the number of days in the target month and leap years. If the resulting day is not a valid day in the resulting month, the last valid day of the resulting month is used. For instance, October 31 + 1 month = November 30. March 31 - 1 month = February 28 for a non leap year, and February 29 for a leap year.

Parameters:

nbYears (int) – Positive or negative number of months.

Return type:

DateTime

addDays(nbDays)¶

Returns a new DateTime object that adds the number of days to the value of this instance. This method is a shortcut for currentDate.add(datetime.span(nbDays, 0, 0, 0)).

Parameters:

nbDays (int) – Positive or negative number of days.

Return type:

DateTime

addHours(nbHours)¶

Returns a new DateTime object that adds the number of hours to the value of this instance. This method is a shortcut for currentDate.add(datetime.span(nbHours, 0, 0)).

Parameters:

nbHours (int) – Positive or negative number of hours.

Return type:

DateTime

addMinutes(nbMinutes)¶

Returns a new DateTime object that adds the number of minutes to the value of this instance. This method is a shortcut for currentDate.add(datetime.span(0, nbMinutes, 0)).

Parameters:

nbMinutes (int) – Positive or negative number of minutes.

Return type:

DateTime

addSeconds(nbSeconds)¶

Returns a new DateTime object that adds the number of seconds to the value of this instance. This method is a shortcut for currentDate.add(datetime.span(0, 0, nbSeconds)).

Parameters:

nbHours (int) – Positive or negative number of seconds.

Return type:

DateTime

addMilliseconds(nbMillis)¶

Returns a new DateTime object that adds the number of milliseconds to the value of this instance. This method is a shortcut for currentDate.add(datetime.span(0, 0, 0, nbMilliseconds)).

Parameters:

nbMillis (int) – Positive or negative number of milliseconds.

Return type:

DateTime

format(fmt)¶

Formats the DateTime object as a string. Supported format specifiers are listed in the Date format table.

toEpochSeconds()¶

Converts the value of this instance to the number of seconds that have elapsed since 1970-01-01T00:00:00 (the Unix epoch).

Return type:

int

toEpochMilliseconds()¶

Converts the value of this instance to the number of milliseconds that have elapsed since 1970-01-01T00:00:00 (the Unix epoch).

Return type:

int

TimeSpan¶

class TimeSpan¶

days¶

hours¶

minutes¶

seconds¶

milliseconds¶

totalDays¶

totalHours¶

totalMinutes¶

totalSeconds¶

totalMilliseconds¶

add(timespan)¶

addDays(nbDays)¶

addHours(nbHours)¶

addMinutes(nbMinutes)¶

addSeconds(nbSeconds)¶

addMilliseconds(nbMillis)¶

Date format¶

The following table describes the custom date and time format specifiers that can be used with the DateTime.format() function.