Python Datetime Datetime

A datetime.datetime object represents a date and time.

Contents

  1. Python Datetime Datetime
    1. Usage
    2. Class Functions
      1. Combine
      2. FromIsoCalendar
      3. FromIsoFormat
      4. FromOrdinal
      5. FromTimestamp
      6. Now
      7. StrPTime
      8. Today
      9. UtcFromTimeStamp
      10. UtcNow
    3. Methods
      1. AsTimeZone
      2. CTime
      3. Date
      4. Dst
      5. IsoCalendar
      6. IsoFormat
      7. IsoWeekDay
      8. Replace
      9. StrFTime
      10. Time
      11. TimeStamp
      12. TimeTuple
      13. TimeTz
      14. ToOrdinal
      15. TzName
      16. UtcOffset
      17. UtcTimeTuple
      18. WeekDay
    4. Operations

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.

Methods

AsTimeZone

CTime

Date

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

Dst

IsoCalendar

IsoFormat

IsoWeekDay

Replace

StrFTime

Time

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

TimeStamp

TimeTuple

TimeTz

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

ToOrdinal

TzName

UtcOffset

UtcTimeTuple

WeekDay

Operations

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

Operation

Meaning

dt1 + timedelta

returns a new datetime representing dt1 incremented by the duration

dt1 - timedelta

returns a new datetime representing dt1 decremented by the duration

dt1 - dt2

returns a datetime.timedelta

dt1 < dt2

returns True if dt1 is earlier than dt2 else False

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