You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Michael Twomey 406db6f23f Update license years 3 months ago
.github/workflows Add an `__all__` to `__init.py__` 8 months ago
docs Add an `__all__` to `__init.py__` 8 months ago
iso8601 Add an `__all__` to `__init.py__` 8 months ago
.editorconfig Remove python 2 compatibility 12 months ago
.envrc Remove python 2 compatibility 12 months ago
.gitignore Add sphinx-build to nox build 8 months ago
.pre-commit-config.yaml Add an `__all__` to `__init.py__` 8 months ago
.tool-versions Preparing for 1.0 release 8 months ago
LICENSE Update license years 3 months ago Preparing for 1.0 release 8 months ago
README.rst Add an `__all__` to `__init.py__` 8 months ago Add an `__all__` to `__init.py__` 8 months ago
poetry.lock Add an `__all__` to `__init.py__` 8 months ago
pyproject.toml Add an `__all__` to `__init.py__` 8 months ago


Simple module to parse ISO 8601 dates

This module parses the most common forms of ISO 8601 date strings (e.g. 2007-01-14T20:34:22+00:00) into datetime objects.

>>> import iso8601 >>> iso8601.parse_date("2007-01-25T12:00:00Z") datetime.datetime(2007, 1, 25, 12, 0, tzinfo=<iso8601.Utc>) >>>

See the LICENSE file for the license this package is released under.

If you want more full featured parsing look at:

Parsed Formats

You can parse full date + times, or just the date. In both cases a datetime instance is returned but with missing times defaulting to 0, and missing days / months defaulting to 1.


  • YYYY-MM (defaults to 1 for the day)
  • YYYY (defaults to 1 for month and day)


  • hh:mm:ss.nn
  • hhmmss.nn
  • hh:mm (defaults to 0 for seconds)
  • hhmm (defaults to 0 for seconds)
  • hh (defaults to 0 for minutes and seconds)

Time Zones

  • Nothing, will use the default timezone given (which in turn defaults to UTC).
  • Z (UTC)
  • +/-hh:mm
  • +/-hhmm
  • +/-hh

Where it Differs From ISO 8601

Known differences from the ISO 8601 spec:

  • You can use a " " (space) instead of T for separating date from time.
  • Days and months without a leading 0 (2 vs 02) will be parsed.
  • If time zone information is omitted the default time zone given is used (which in turn defaults to UTC). Use a default of None to yield naive datetime instances.




  1. poetry install
  2. poetry run nox

Note that you need all the pythons installed to perform a tox run (see below). pyenv helps hugely, use pyenv install for the versions you need then use 'pyenv local version ...' to link them in (the tox-pyenv plugin will pick them up).

Alternatively, to test only with your current python:

  1. poetry install
  2. pytest


  1. Ensure there is a new version committed to main (use poetry version <action> to bump).
  2. Ensure README.rst changelog is up to date.
  3. Note new and previous version.
  4. rm -rf dist
  5. poetry build
  6. git log --oneline $LAST_VERSION..@ > git_log.txt
  7. gh release create --notes-file git_log.txt --title $(poetry version -s) $(poetry version -s) dist/*
  8. poetry publish

Supported Python Versions

Tested against:

  • Python 3.6
  • Python 3.7
  • Python 3.8
  • Python 3.9
  • Python 3.10
  • PyPy 3

Python 3 versions < 3.6 are untested but should work.




  • Add missing py.typed file (as per PEP 561), keeps mypy happy :D


  • Drop python < 3.6 support
  • Add type annotations to code
  • Remove external type annotations in pyi
  • Switch to poetry for packaging
  • Simplify internals and remove old compatability code
  • Switch to nox for testing
  • Lots of small project development changes



  • Include .pyi files in built wheels and source tarballs


  • Add GitHub build actions for project
  • Add project URLs in (thanks to Steve Piercy)
  • Update README links (thanks to Steve Piercy)
  • Fix handling of README in (encoding fun in 3.5, 3.6 and pypy3)
  • Fix README links (thanks to Chris Barker)
  • Add Python 3.9 to test matrix (thanks to Luciano Mammino)
  • Add type hints (thanks to Brett Cannon)
  • Derive ParseError from ValueError (thanks to Lex Robinson)


  • Move to GitHub ( Thanks go to Martin Häcker for pointing out the bitbucket project had been deleted by Atlassian!
  • Remove python 2.6, 3.2, 3.3 and 3.4 from tests
  • Add python 3.7 and 3.8 to tests










  • The default_timezone argument wasn't being passed through correctly, UTC was being used in every case. Fixes issue 10.


  • Fixed the microsecond handling, the generated microsecond values were way too small. Fixes issue 9.


  • Adding ParseError to __all__ in iso8601 module, allows people to import it. Addresses issue 7.
  • Be a little more flexible when dealing with dates without leading zeroes. This violates the spec a little, but handles more dates as seen in the field. Addresses issue 6.
  • Allow date/time separators other than T.


  • When parsing dates without a timezone the specified default is used. If no default is specified then UTC is used. Addresses issue 4.