Differences between revisions 1 and 6 (spanning 5 versions)

Python Datetime Datetime

A datetime.datetime object represents a date and time.

Contents

Python Datetime Datetime

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)

Ordinal dates are not supported by this function
The T separator is allowed to be any character
Time zone offsets are allowed to have fractional seconds
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.

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

-  ⇤ ← Revision 1 as of 2023-04-11 23:21:03 → 
  Size: 2378
  Editor: DominicRicottone
  Comment:
+   ← Revision 6 as of 2023-04-12 14:11:54 → ⇥
  Size: 6863
  Editor: DominicRicottone
  Comment:
-Deletions are marked like this.
+Additions are marked like this.
 Line 22:
-d2 = datetime.datetime(2020, 12, 31)
+dt1 = datetime.datetime(2020, 12, 31)
 Line 28:
-d1.year         # 2020
d1.month        # 12
d1.day          # 25
d1.hour         # 23
d1.minute       # 59
d1.second       # 59
d1.millisecond  # 999999
d1.tzinfo       # None
d1.fold         # 0
+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
 Line 51:
+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.

----
-Line 55:
+Line 65:
+Construct a `datetime.datetime` from the year, week, and weekday.

----
-Line 59:
+Line 73:
+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

----
-Line 63:
+Line 94:
+Construct a `datetime.datetime` from a proleptic Gregorian ordinal.

----
-Line 67:
+Line 102:
+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.

----
-Line 71:
+Line 114:
+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.

----
-Line 75:
+Line 128:
+Construct a `datetime.datetime` from a formatted string timestamp.

See [[Python/Datetime#StrFTime_and_StrPTime|here]] for an explanation of the directives. 

----
-Line 79:
+Line 138:
+A `datetime.datetime` representing the current date and time (and no timezone information) can be constructed like:

{{{
dt1 = datetime.datetime.today()
}}}

----
-Line 83:
+Line 150:
+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). 

----
-Line 87:
+Line 160:
+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)
}}}
-Line 97:
+Line 180:
+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)))
}}}

----
-Line 105:
+Line 199:
+Return a `datetime.date` object containing the time components (`year`, `month`, `day`).

----
-Line 109:
+Line 207:
+A passthrough to `datetime.timezone.dst` for the `tzinfo` component of `datetime.datetime`.

If `tzinfo` is None, returns None.

----
-Line 125:
+Line 229:
+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)
}}}

----
-Line 133:
+Line 249:
+Return a `datetime.time` object containing the time components (`hour`, `minute`, `second`, `millisecond`, and `fold`). Compare to `datetime.datetime.timetz`.

----
-Line 141:
+Line 261:
+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.

----
-Line 145:
+Line 273:
+Return a `datetime.time` object containing the time components ''and'' the `tzinfo`.

----
-Line 153:
+Line 285:
+A passthrough to `datetime.timezone.tzname` for the `tzinfo` component of `datetime.datetime`.

If `tzinfo` is None, returns None.

----
-Line 157:
+Line 295:
+A passthrough to `datetime.timezone.utcoffset` for the `tzinfo` component of `datetime.datetime`.

If `tzinfo` is None, returns None.

----
-Line 173:
+Line 317:
-||'''Operation'''  ||'''Meaning'''                                                       ||
||`d1 + timedelta` ||returns a new datetime representing `d1` incremented by the duration||
||`d1 - timedelta` ||returns a new datetime representing `d1` decremented by the duration||
||`d1 - d2`        ||returns a `datetime.timedelta`                                      ||
||`d1 < d2`        ||returns `True` if `d1` is earlier than `d2` else `False`            ||
+||'''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`           ||

Diff for "Python/Datetime/Datetime"

Python Datetime Datetime

Usage

Class Functions

Combine

FromIsoCalendar

FromIsoFormat

FromOrdinal

FromTimestamp

Now

StrPTime

Today

UtcFromTimeStamp

UtcNow

Methods

AsTimeZone

CTime

Date

Dst

IsoCalendar

IsoFormat

IsoWeekDay

Replace

StrFTime

Time

TimeStamp

TimeTuple

TimeTz

ToOrdinal

TzName

UtcOffset

UtcTimeTuple

WeekDay

Operations