|
Size: 2378
Comment:
|
Size: 8013
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 13: | Line 13: |
| A datetime.date object is constructed as: {{{ d1 = datetime.datetime(2020, 12, 31, 23, 59, 59, 999999, tzinfo=None) |
A `datetime.datetime` object is constructed as: {{{ dt1 = datetime.datetime(2020, 12, 31, 23, 59, 59, 999999, tzinfo=None) |
| Line 22: | Line 22: |
| d2 = datetime.datetime(2020, 12, 31) | dt2 = datetime.datetime(2020, 12, 31) |
| Line 28: | 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: | 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. Timezone 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 timezone, 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 timezone, 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 timezone is set to `None`. May raise an `OverflowError` or `OSError` depending on the local `libc` (specifically the `localtime()` implementation). ---- |
|
| Line 87: | Line 160: |
| 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) }}} |
|
| Line 97: | Line 180: |
| 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))) }}} ---- |
|
| Line 101: | Line 195: |
| Return a string like `Wed Dec 4 20:30:40 2002`. Equivalent to `time.ctime(time.mktime(dt1.timetuple()))`. ---- |
|
| Line 105: | Line 205: |
| Return a `datetime.date` object containing the time components (`year`, `month`, `day`). ---- |
|
| Line 109: | Line 213: |
| A passthrough to `datetime.timezone.dst` for the `tzinfo` component of `datetime.datetime`. If `tzinfo` is None, returns None. ---- |
|
| Line 113: | Line 223: |
| Return a named tuple like `datetime.IsoCalendarDate(year, week, weekday)`. ---- |
|
| Line 117: | Line 231: |
| 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. ---- |
|
| Line 121: | Line 239: |
| Return the weekday as an integer between 1 (Monday) and 7 (Sunday). ---- |
|
| Line 125: | Line 247: |
| 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 129: | Line 263: |
| Return a formatted string timestamp. See [[Python/Datetime#StrFTime_and_StrPTime|here]] for an explanation of the directives. ---- |
|
| Line 133: | Line 273: |
| Return a `datetime.time` object containing the time components (`hour`, `minute`, `second`, `millisecond`, and `fold`). Compare to `datetime.datetime.timetz`. ---- |
|
| Line 137: | Line 281: |
| Return a float representing a POSIX timestamp. May raise an `OverflowError` depending on the local `libc` (specifically the `mktime()` implementation). ---- |
|
| Line 141: | Line 291: |
| 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 303: |
| Return a `datetime.time` object containing the time components ''and'' the `tzinfo`. ---- |
|
| Line 149: | Line 311: |
| Return the proleptic Gregorian ordinal. ---- |
|
| Line 153: | Line 319: |
| A passthrough to `datetime.timezone.tzname` for the `tzinfo` component of `datetime.datetime`. If the `datetime.datetime` object is timezone naive, returns None. ---- |
|
| Line 157: | Line 329: |
| A passthrough to `datetime.timezone.utcoffset` for the `tzinfo` component of `datetime.datetime`. If the `datetime.datetime` object is timezone naive, returns None. ---- |
|
| Line 161: | Line 339: |
| 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. ---- |
|
| Line 165: | Line 349: |
| Return the weekday as an integer between 0 (Monday) and 6 (Sunday). |
|
| Line 173: | Line 359: |
| ||'''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` || |
Python Datetime Datetime
A datetime.datetime object represents a date and time.
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)- Ordinal dates are not supported by this function
The T separator is allowed to be any character
- Timezone 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 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.
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.