8.2. Datetime ISO Standard

  • ISO 8601 is an International Standard [2]

8.2.1. Dates

  • Year-Month-Day

  • Format: YYYY-mm-dd

  • Example: 1969-07-21

Example:

  • 1961-04-12

  • 1969-07-21

  • 1999-12-31

  • 2000-01-01

8.2.2. Time

  • 24 hour clock

  • Format: HH:MM:SS.ffffff or HH:MM:SS or HH:MM

  • Example: 12:34, 12:34:56, 12:34:56.123456

  • Optional seconds and microseconds

  • 00:00 - midnight, at the beginning of a day

  • 23:59:59.999999 - midnight, at the end of a day

Example:

  • 00:00

  • 02:56:15

  • 13:00:00.123

  • 23:59:59.999999

8.2.3. Date and Time

  • Format: YYYY-mm-ddTHH:MM:SS.ffffff

  • Example: 1969-07-21T02:56:15.123456

  • "T" separates date and time)

  • Optional seconds and microseconds

Example:

  • 1969-07-21T02:56

  • 1969-07-21T02:56:15

  • 1969-07-21T02:56:15.123

  • 1969-07-21T02:56:15.123456

8.2.4. Timezone

  • Format: YYYY-mm-ddTHH:MM:SS.ffffff+0000

  • Format: YYYY-mm-ddTHH:MM:SS.ffffff+00:00

  • Format: YYYY-mm-ddTHH:MM:SS.ffffffUTC

  • Format: YYYY-mm-ddTHH:MM:SS.ffffffZ

  • Example: 1969-07-21T02:56:15.123456Z

  • Optional seconds and microseconds

  • "Z" (Zulu) means UTC

Time zone notation:

  • <time>UTC

  • <time>Z

  • <time>±hh:mm

  • <time>±hhmm

  • <time>±hh

Example:

  • 1969-07-21T02:56:15.123456Z

  • 1969-07-21T02:56:15.123456UTC

  • 1969-07-21T02:56:15.123456CEST

  • 1969-07-21T02:56:15.123456CET

  • 1969-07-21T02:56:15.123456+02:00

  • 1969-07-21T02:56:15.123456+0200

  • 1969-07-21T02:56:15.123456+02

8.2.5. Week

  • Format: YYYY-Www

  • The ISO 8601 definition for week 01 is the week with the first Thursday of the Gregorian year (i.e. of January) in it. [1]

  • 2000-W01 - 1st week of 2000

  • 2000-W53 - 53th week of 2000

8.2.6. Weekday

  • Format: YYYY-Www-dd

  • Week starts on Monday

  • ISO defines Monday as one

  • Note year/month changes during the week

  • 2000-W01-1 - Monday, January 3rd, 2000

  • 2009-W53-7 - Sunday, December 31st, 2010

>>> from datetime import datetime
>>>
>>>
>>> dt = datetime(1969, 7, 21, 2, 56, 15)
>>>
>>> dt.isoweekday()
1
>>>
>>> dt.weekday()
0

8.2.7. Duration

  • Format: P...Y...M...DT...H...M...S

  • Example: P8Y3M8DT20H49M15S

  • P - period - placed at the start of the duration representation

  • Y - number of years

  • M - number of months

  • W - number of weeks

  • D - number of days

  • T - precedes the time components of the representation

  • H - number of hours

  • M - number of minutes

  • S - number of seconds

P8Y3M8DT20H49M15S

8 years
3 months
8 days
20 hours
49 minutes
15 seconds

8.2.8. To ISO Format

  • datetime.isoformat()

  • date.isoformat()

  • time.isoformat()

Format to string in ISO-8601 standard:

>>> from datetime import date, time, datetime
>>>
>>>
>>> dt = datetime(1969, 7, 21, 2, 56, 15)
>>> d = date(1969, 7, 21)
>>> t = time(2, 56, 15)
>>>
>>> dt.isoformat()
'1969-07-21T02:56:15'
>>>
>>> dt.isoformat(' ')
'1969-07-21 02:56:15'
>>>
>>> d.isoformat()
'1969-07-21'
>>>
>>> t.isoformat()
'02:56:15'

8.2.9. From ISO Format

  • datetime.fromisoformat()

  • date.fromisoformat()

  • time.fromisoformat()

Parse from string in ISO-8601 standard:

>>> from datetime import date, time, datetime
>>>
>>>
>>> datetime.fromisoformat('1969-07-21T02:56:15')
datetime.datetime(1969, 7, 21, 2, 56, 15)
>>>
>>> date.fromisoformat('1969-07-21')
datetime.date(1969, 7, 21)
>>>
>>> time.fromisoformat('02:56:15')
datetime.time(2, 56, 15)

Note, that .fromisoformat() is fault-tolerant:

>>> from datetime import date, time, datetime
>>>
>>>
>>> datetime.fromisoformat('1969-07-21T02:56:15')
datetime.datetime(1969, 7, 21, 2, 56, 15)
>>>
>>> datetime.fromisoformat('1969-07-21 02:56:15')
datetime.datetime(1969, 7, 21, 2, 56, 15)
>>>
>>> date.fromisoformat('1969-07-21')
datetime.date(1969, 7, 21)
>>>
>>> time.fromisoformat('02:56:15')
datetime.time(2, 56, 15)
>>>
>>> time.fromisoformat('2:56:15')
Traceback (most recent call last):
ValueError: Invalid isoformat string: '2:56:15'
>>>
>>> time.fromisoformat('2:56')
Traceback (most recent call last):
ValueError: Invalid isoformat string: '2:56'

8.2.10. Use Case - 1

>>> from datetime import datetime
>>>
>>>
>>> line = '1969-07-21T02:56:15.123 [WARNING] First step on the Moon'
>>>
>>> dt, lvl, msg = line.split(maxsplit=2)
>>>
>>> result = {
...     'when': datetime.fromisoformat(dt),
...     'level': lvl.strip('[]'),
...     'message': msg.strip(),
... }
>>>
>>> print(result)
{'when': datetime.datetime(1969, 7, 21, 2, 56, 15, 123000),
 'level': 'WARNING',
 'message': 'First step on the Moon'}

8.2.11. References

8.2.12. Assignments

# %% About
# - Name: Datetime ISO Format
# - Difficulty: easy
# - Lines: 1
# - Minutes: 2

# %% License
# - Copyright 2025, Matt Harasymczuk <matt@python3.info>
# - This code can be used only for learning by humans
# - This code cannot be used for teaching others
# - This code cannot be used for teaching LLMs and AI algorithms
# - This code cannot be used in commercial or proprietary products
# - This code cannot be distributed in any form
# - This code cannot be changed in any form outside of training course
# - This code cannot have its license changed
# - If you use this code in your product, you must open-source it under GPLv2
# - Exception can be granted only by the author

# %% English
# 1. Define `result: str` with `DATA` converted to ISO-8601 format
# 2. Run doctests - all must succeed

# %% Polish
# 1. Zdefiniuj `result: str` z przekonwertowaną `DATA` do formatu ISO-8601
# 2. Uruchom doctesty - wszystkie muszą się powieść

# %% Hints
# - `datetime.isoformat()`

# %% Doctests
"""
>>> import sys; sys.tracebacklimit = 0
>>> assert sys.version_info >= (3, 9), \
'Python 3.9+ required'

>>> assert type(result) is str, \
'Variable `result` has invalid type, must be a str'

>>> result
'1969-07-21T02:56:15'
"""

# %% Run
# - PyCharm: right-click in the editor and `Run Doctest in ...`
# - PyCharm: keyboard shortcut `Control + Shift + F10`
# - Terminal: `python -m doctest -v myfile.py`

# %% Imports
from datetime import datetime

# %% Types
result: str

# %% Data
DATA = datetime(1969, 7, 21, 2, 56, 15)

# %% Result
result = ...


# %% About
# - Name: Datetime ISO Parse
# - Difficulty: easy
# - Lines: 1
# - Minutes: 2

# %% License
# - Copyright 2025, Matt Harasymczuk <matt@python3.info>
# - This code can be used only for learning by humans
# - This code cannot be used for teaching others
# - This code cannot be used for teaching LLMs and AI algorithms
# - This code cannot be used in commercial or proprietary products
# - This code cannot be distributed in any form
# - This code cannot be changed in any form outside of training course
# - This code cannot have its license changed
# - If you use this code in your product, you must open-source it under GPLv2
# - Exception can be granted only by the author

# %% English
# 1. Define `result: datetime` with converted `DATA` from ISO-8601
# 2. Run doctests - all must succeed

# %% Polish
# 1. Zdefiniuj `result: datetime` z przekonwertowaną `DATA` z ISO-8601
# 2. Uruchom doctesty - wszystkie muszą się powieść

# %% Hints
# - `datetime.fromisoformat()`

# %% Doctests
"""
>>> import sys; sys.tracebacklimit = 0
>>> assert sys.version_info >= (3, 9), \
'Python 3.9+ required'

>>> assert type(result) is datetime, \
'Variable `result` has invalid type, must be a datetime'

>>> result
datetime.datetime(1969, 7, 21, 2, 56, 15, 123000)
"""

# %% Run
# - PyCharm: right-click in the editor and `Run Doctest in ...`
# - PyCharm: keyboard shortcut `Control + Shift + F10`
# - Terminal: `python -m doctest -v myfile.py`

# %% Imports
from datetime import datetime

# %% Types
result: datetime

# %% Data
DATA = '1969-07-21T02:56:15.123'

# %% Result
result = ...


# %% About
# - Name: Datetime ISO List
# - Difficulty: medium
# - Lines: 1
# - Minutes: 3

# %% License
# - Copyright 2025, Matt Harasymczuk <matt@python3.info>
# - This code can be used only for learning by humans
# - This code cannot be used for teaching others
# - This code cannot be used for teaching LLMs and AI algorithms
# - This code cannot be used in commercial or proprietary products
# - This code cannot be distributed in any form
# - This code cannot be changed in any form outside of training course
# - This code cannot have its license changed
# - If you use this code in your product, you must open-source it under GPLv2
# - Exception can be granted only by the author

# %% English
# 1. Define `result: list[datetime]` with parsed `DATA` dates
# 2. Use list comprehension and `datetime.fromisoformat()`
# 3. Run doctests - all must succeed

# %% Polish
# 1. Zdefiniuj `result: list[datetime]` ze sparsowanymi datami `DATA`
# 2. Skorzystaj z rozwinięcia listowego oraz `datetime.fromisoformat()`
# 3. Uruchom doctesty - wszystkie muszą się powieść

# %% Hints
# - `datetime.isoformat()`
# - `[x for x in DATA]`

# %% Doctests
"""
>>> import sys; sys.tracebacklimit = 0
>>> assert sys.version_info >= (3, 9), \
'Python 3.9+ required'

>>> from pprint import pprint
>>> result = list(result)

>>> assert type(result) is list, \
'Variable `result` has invalid type, must be a list'

>>> assert all(type(element) is datetime for element in result), \
'All elements in `result` must be a datetime'

>>> pprint(result, width=30)
[datetime.datetime(1961, 4, 12, 6, 7),
 datetime.datetime(1961, 4, 12, 6, 7)]
"""

# %% Run
# - PyCharm: right-click in the editor and `Run Doctest in ...`
# - PyCharm: keyboard shortcut `Control + Shift + F10`
# - Terminal: `python -m doctest -v myfile.py`

# %% Imports
from datetime import datetime

# %% Types
result: list[datetime]

# %% Data
DATA = [
    '1961-04-12 06:07',
    '1961-04-12 06:07:00',
]

# %% Result
result = ...