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. Time zone 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 time zone, 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 time zone, 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 time zone is set to None.

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

UtcNow

A naive (i.e. time zone is stripped out) 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 time zone replaced and any appropriate offsets applied. If a timezone is not passed as an argument, the local time zone is used.

import datetime

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

CTime

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

IsoFormat

IsoWeekDay

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

Time

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

TimeStamp

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

TzName

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

If tzinfo is None, returns None.

UtcOffset

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

If tzinfo is None, returns None.

UtcTimeTuple

WeekDay

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