Python Datetime Datetime

A datetime.datetime object represents a date and time.

Usage

A datetime.date object is constructed as:

d1 = datetime.datetime(2020, 12, 31, 23, 59, 59, 999999, tzinfo=None)

While the year, month, and date are required, the remaining options are optional.

dt1 = datetime.datetime(2020, 12, 31)

The components can be accessed like:

dt1.year         # 2020
dt1.month        # 12
dt1.day          # 25
dt1.hour         # 23
dt1.minute       # 59
dt1.second       # 59
dt1.millisecond  # 999999
dt1.tzinfo       # None
dt1.fold         # 0

Note that fold is used to indicate a time that is 'repeated' (as in 'setting the clock back').

Class Functions

Combine

Construct a datetime.datetime from a datetime.date and a datetime.time.

dt1 = datetime.datetime.combine(d1, t1)

To override the tzinfo from the datetime.time object, pass the optional tzinfo argument.

FromIsoCalendar

Construct a datetime.datetime from the year, week, and weekday.

FromIsoFormat

To construct a datetime.datetime from most valid ISO 8601 strings, try:

import datetime

datetime.datetime.fromisoformat('2019-12-04')            #datetime.datetime(2019, 12, 4, 0, 0)
datetime.datetime.fromisoformat('20191204')              #datetime.datetime(2019, 12, 4, 0, 0)
datetime.datetime.fromisoformat('2011-11-04T00:05:23')   #datetime.datetime(2011, 11, 4, 0, 5, 23)
datetime.datetime.fromisoformat('2011-11-04T00:05:23Z')  #datetime.datetime(2011, 11, 4, 0, 5, 23, tzinfo=datetime.timezone.utc)

1. Ordinal dates are not supported by this function

2. The T separator is allowed to be any character

3. Timezone offsets are allowed to have fractional seconds

4. Hours and minutes are not allowed to be fractional

FromOrdinal

Construct a datetime.datetime from a proleptic Gregorian ordinal.

FromTimestamp

Construct a datetime.datetime from a string representing a POSIX timestamp.

May raise an OverflowError or OSError depending on the local libc (specifically the localtime() implementation).

To set the timezone, pass the optional tzinfo argument.

Now

A datetime.datetime representing the current date and time can be constructed like:

dt1 = datetime.datetime.now()

To set the timezone, pass the optional tzinfo argument.

StrPTime

Construct a datetime.datetime from a formatted string timestamp.

See here for an explanation of the directives.

Today

A datetime.datetime representing the current date and time (and no timezone information) can be constructed like:

dt1 = datetime.datetime.today()

UtcFromTimeStamp

Construct a datetime.datetime from a string representing a POSIX timestamp. The timezone is set to None.

May raise an OverflowError or OSError depending on the local libc (specifically the localtime() implementation).

UtcNow

A timezone naive datetime.datetime representing the current date and time in UTC.

datetime.datetime.now is preferred because naive datetime.datetime objects are assumed to be local, and this function defies that logic. Instead consider using:

import datetime

datetime.datetime(2023, 4, 12, 13, 59, 53, 654456, tzinfo=datetime.timezone.utc)

Methods

AsTimeZone

Return a copy of the datetime.datetime object with the timezone replaced and any appropriate offsets applied. If a timezone is not passed as an argument, the local timezone is used.

import datetime

dt1 = datetime.datetime.now(datetime.timezone.utc)
dt2 = dt1.astimezone(datetime.timezone(datetime.timedelta(hours=-5)))

CTime

Return a string like Wed Dec  4 20:30:40 2002.

Equivalent to time.ctime(time.mktime(dt1.timetuple())).

Date

Return a datetime.date object containing the time components (year, month, day).

Dst

A passthrough to datetime.timezone.dst for the tzinfo component of datetime.datetime.

If tzinfo is None, returns None.

IsoCalendar

Return a named tuple like datetime.IsoCalendarDate(year, week, weekday).

IsoFormat

Return a string like YYYY-MM-DDTHH:MM:SS. Appends microseconds like .ffffff if not 0. Appends timezone offset like +HH:MM[:SS[.ffffff]] if not timezone naive.

IsoWeekDay

Return the weekday as an integer between 1 (Monday) and 7 (Sunday).

Replace

Return a copy of the datetime.datetime object with the specified components replaced.

import datetime
dt1 = datetime.date(2020, 12, 25, 23, 59, 59, 999999, tzinfo=datetime.timezone.utc)
dt2 = dt1.replace(tzinfo=None)
dt3 = dt2.replace(year=2021)
dt4 = dt3.replace(hour=0)

StrFTime

Return a formatted string timestamp.

See here for an explanation of the directives.

Time

Return a datetime.time object containing the time components (hour, minute, second, millisecond, and fold). Compare to datetime.datetime.timetz.

TimeStamp

Return a float representing a POSIX timestamp.

May raise an OverflowError depending on the local libc (specifically the mktime() implementation).

TimeTuple

Return a time tuple like time.localtime().

Equivalent to time.struct_time((dt1.year, dt1.month, dt1.day, dt1.hour, dt1.minute, dt1.second, dt1.weekday(), dt1.toordinal() - datetime.date(dt1.year, 1, 1).toordinal() + 1, -1)).

Note the last argument would actually be 1 if datetime.datetime.dst returned any non-zero code, or 0 if it returned 0 specifically.

TimeTz

Return a datetime.time object containing the time components and the tzinfo.

ToOrdinal

Return the proleptic Gregorian ordinal.

TzName

A passthrough to datetime.timezone.tzname for the tzinfo component of datetime.datetime.

If the datetime.datetime object is timezone naive, returns None.

UtcOffset

A passthrough to datetime.timezone.utcoffset for the tzinfo component of datetime.datetime.

If the datetime.datetime object is timezone naive, returns None.

UtcTimeTuple

Same as datetime.datetime.timetuple except that the last argument is forced to 0.

If the datetime.datetime object is not timezone naive, the time is adjusted for UTC before generating the tuple.

WeekDay

Return the weekday as an integer between 0 (Monday) and 6 (Sunday).

Operations

datetime.datetime objects can be used with the following operators and functions.

Two datetime.datetime objects can only be used in operations together if both have timezone information, or both are naive to timezones. Mixing categories will raise a TypeError.

CategoryRicottone