DateTime#

class DateTime(**kwargs)#

Struct to store date, time and timezone information altogether. DateTime is refcounted and immutable.

Date information is handled using the proleptic Gregorian calendar.

Provides basic creation functions and accessor functions to its fields.

Constructors#

class DateTime
classmethod new(tzoffset: float, year: int, month: int, day: int, hour: int, minute: int, seconds: float) → DateTime | None#

Creates a new DateTime using the date and times in the gregorian calendar in the supplied timezone.

year should be from 1 to 9999, month should be from 1 to 12, day from 1 to 31, hour from 0 to 23, minutes and seconds from 0 to 59.

Note that tzoffset is a float and was chosen so for being able to handle some fractional timezones, while it still keeps the readability of representing it in hours for most timezones.

If value is -1 then all over value will be ignored. For example if month == -1, then DateTime will be created only for year. If day == -1, then DateTime will be created for year and month and so on.

Parameters:

  • tzoffset – Offset from UTC in hours.

  • year – the gregorian year

  • month – the gregorian month

  • day – the day of the gregorian month

  • hour – the hour of the day

  • minute – the minute of the hour

  • seconds – the second of the minute

classmethod new_from_g_date_time(dt: DateTime | None = None) → DateTime | None#

Creates a new DateTime from a DateTime object.

Parameters:

dt – the DateTime.

classmethod new_from_iso8601_string(string: str) → DateTime | None#

Tries to parse common variants of ISO-8601 datetime strings into a DateTime. Possible input formats are (for example): 2012-06-30T22:46:43Z, 2012, 2012-06, 2012-06-30, 2012-06-30T22:46:43-0430, 2012-06-30T22:46Z, 2012-06-30T22:46-0430, 2012-06-30 22:46, 2012-06-30 22:46:43, 2012-06-00, 2012-00-00, 2012-00-30, 22:46:43Z, 22:46Z, 22:46:43-0430, 22:46-0430, 22:46:30, 22:46 If no date is provided, it is assumed to be “today” in the timezone provided (if any), otherwise UTC.

Parameters:

string – ISO 8601-formatted datetime string.

classmethod new_from_unix_epoch_local_time(secs: int) → DateTime | None#

Creates a new DateTime using the time since Jan 1, 1970 specified by secs. The DateTime is in the local timezone.

Parameters:

secs – seconds from the Unix epoch

classmethod new_from_unix_epoch_local_time_usecs(usecs: int) → DateTime | None#

Creates a new DateTime using the time since Jan 1, 1970 specified by usecs. The DateTime is in the local timezone.

Added in version 1.18.

Parameters:

usecs – microseconds from the Unix epoch

classmethod new_from_unix_epoch_utc(secs: int) → DateTime | None#

Creates a new DateTime using the time since Jan 1, 1970 specified by secs. The DateTime is in the UTC timezone.

Parameters:

secs – seconds from the Unix epoch

classmethod new_from_unix_epoch_utc_usecs(usecs: int) → DateTime | None#

Creates a new DateTime using the time since Jan 1, 1970 specified by usecs. The DateTime is in UTC.

Added in version 1.18.

Parameters:

usecs – microseconds from the Unix epoch

classmethod new_local_time(year: int, month: int, day: int, hour: int, minute: int, seconds: float) → DateTime | None#

Creates a new DateTime using the date and times in the gregorian calendar in the local timezone.

year should be from 1 to 9999, month should be from 1 to 12, day from 1 to 31, hour from 0 to 23, minutes and seconds from 0 to 59.

If month is -1, then the DateTime created will only contain year, and all other fields will be considered not set.

If day is -1, then the DateTime created will only contain year and month and all other fields will be considered not set.

If hour is -1, then the DateTime created will only contain year and month and day, and the time fields will be considered not set. In this case minute and seconds should also be -1.

Parameters:

  • year – the gregorian year

  • month – the gregorian month, or -1

  • day – the day of the gregorian month, or -1

  • hour – the hour of the day, or -1

  • minute – the minute of the hour, or -1

  • seconds – the second of the minute, or -1

classmethod new_now_local_time() → DateTime | None#

Creates a new DateTime representing the current date and time.

classmethod new_now_utc() → DateTime | None#

Creates a new DateTime that represents the current instant at Universal coordinated time.

classmethod new_y(year: int) → DateTime | None#

Creates a new DateTime using the date and times in the gregorian calendar in the local timezone.

year should be from 1 to 9999.

Parameters:

year – the gregorian year

classmethod new_ym(year: int, month: int) → DateTime | None#

Creates a new DateTime using the date and times in the gregorian calendar in the local timezone.

year should be from 1 to 9999, month should be from 1 to 12.

If value is -1 then all over value will be ignored. For example if month == -1, then DateTime will created only for year.

Parameters:

  • year – the gregorian year

  • month – the gregorian month

classmethod new_ymd(year: int, month: int, day: int) → DateTime | None#

Creates a new DateTime using the date and times in the gregorian calendar in the local timezone.

year should be from 1 to 9999, month should be from 1 to 12, day from 1 to 31.

If value is -1 then all over value will be ignored. For example if month == -1, then DateTime will created only for year. If day == -1, then DateTime will created for year and month and so on.

Parameters:

  • year – the gregorian year

  • month – the gregorian month

  • day – the day of the gregorian month

Methods#

class DateTime
get_day() → int#

Returns the day of the month of this DateTime.

get_hour() → int#

Retrieves the hour of the day represented by datetime in the gregorian calendar. The return is in the range of 0 to 23.

get_microsecond() → int#

Retrieves the fractional part of the seconds in microseconds represented by datetime in the gregorian calendar.

get_minute() → int#

Retrieves the minute of the hour represented by datetime in the gregorian calendar.

get_month() → int#

Returns the month of this DateTime. January is 1, February is 2, etc..

get_second() → int#

Retrieves the second of the minute represented by datetime in the gregorian calendar.

get_time_zone_offset() → float#

Retrieves the offset from UTC in hours that the timezone specified by datetime represents. Timezones ahead (to the east) of UTC have positive values, timezones before (to the west) of UTC have negative values. If datetime represents UTC time, then the offset is zero.

get_year() → int#

Returns the year of this DateTime. Call has_year() before, to avoid warnings.

has_day() → bool#
has_month() → bool#
has_second() → bool#
has_time() → bool#
has_year() → bool#
to_g_date_time() → DateTime | None#

Creates a new DateTime from a fully defined DateTime object.

to_iso8601_string() → str | None#

Create a minimal string compatible with ISO-8601. Possible output formats are (for example): 2012, 2012-06, 2012-06-23, 2012-06-23T23:30Z, 2012-06-23T23:30+0100, 2012-06-23T23:30:59Z, 2012-06-23T23:30:59+0100