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.datetime object is constructed as: 

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

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

dt2 = 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.datetime(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.

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

dt1 == dt2

returns True if dt1 represents the same UTC or timezone naive time as 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, except for the == and != operators (which will always indicate that the two are unlike)..

CategoryRicottone

Python/Datetime/Datetime (last edited 2023-04-12 15:17:54 by DominicRicottone)