How do I parse an ISO 8601-formatted date

Question

I need to parse RFC 3339 strings like  2008-09-03T20 56 35 450686Z  into Python s datetime type   I have found strptime in the Python standard library  but it is not very convenient   What is the best way to do this

User · Answer

import re datetime s  2008-09-03T20 56 35 450686Z  d datetime datetime  map int  re split     d    s   -1

User · Answer

Several answers here suggest using datetime datetime strptime to parse RFC 3339 or ISO 8601 datetimes with timezones  like the one exhibited in the question   2008-09-03T20 56 35 450686Z   This is a bad idea   Assuming that you want to support the full RFC 3339 format  including support for UTC offsets other than zero  then the code these answers suggest does not work  Indeed  it cannot work  because parsing RFC 3339 syntax using strptime is impossible  The format strings used by Python s datetime module are incapable of describing RFC 3339 syntax   The problem is UTC offsets  The RFC 3339 Internet Date Time Format requires that every date-time includes a UTC offset  and that those offsets can either be Z  short for  Zulu time   or in  HH MM or -HH MM format  like  05 00 or -10 30   Consequently  these are all valid RFC 3339 datetimes    2008-09-03T20 56 35 450686Z 2008-09-03T20 56 35 450686 05 00 2008-09-03T20 56 35 450686-10 30   Alas  the format strings used by strptime and strftime have no directive that corresponds to UTC offsets in RFC 3339 format  A complete list of the directives they support can be found at https   docs python org 3 library datetime html strftime-and-strptime-behavior  and the only UTC offset directive included in the list is  z         z      UTC offset in the form  HHMM or -HHMM  empty string if the the object is naive        Example   empty    0000  -0400   1030   This doesn t match the format of an RFC 3339 offset  and indeed if we try to use  z in the format string and parse an RFC 3339 date  we ll fail       from datetime import datetime     datetime strptime  2008-09-03T20 56 35 450686Z     Y- m- dT H  M  S  f z   Traceback  most recent call last     File     line 1  in    File   usr lib python3 4  strptime py   line 500  in  strptime datetime     tt  fraction    strptime data string  format    File   usr lib python3 4  strptime py   line 337  in  strptime      data string  format   ValueError  time data  2008-09-03T20 56 35 450686Z  does not match format   Y- m- dT H  M  S  f z      datetime strptime  2008-09-03T20 56 35 450686 05 00     Y- m- dT H  M  S  f z   Traceback  most recent call last     File     line 1  in    File   usr lib python3 4  strptime py   line 500  in  strptime datetime     tt  fraction    strptime data string  format    File   usr lib python3 4  strptime py   line 337  in  strptime      data string  format   ValueError  time data  2008-09-03T20 56 35 450686 05 00  does not match format   Y- m- dT H  M  S  f z    Actually  the above is just what you ll see in Python 3  In Python 2 we ll fail for an even simpler reason  which is that strptime does not implement the  z directive at all in Python 2    The multiple answers here that recommend strptime all work around this by including a literal Z in their format string  which matches the Z from the question asker s example datetime string  and discards it  producing a datetime object without a timezone        datetime strptime  2008-09-03T20 56 35 450686Z     Y- m- dT H  M  S  fZ   datetime datetime 2008  9  3  20  56  35  450686   Since this discards timezone information that was included in the original datetime string  it s questionable whether we should regard even this result as correct  But more importantly  because this approach involves hard-coding a particular UTC offset into the format string  it will choke the moment it tries to parse any RFC 3339 datetime with a different UTC offset       datetime strptime  2008-09-03T20 56 35 450686 05 00     Y- m- dT H  M  S  fZ   Traceback  most recent call last     File     line 1  in    File   usr lib python3 4  strptime py   line 500  in  strptime datetime     tt  fraction    strptime data string  format    File   usr lib python3 4  strptime py   line 337  in  strptime      data string  format   ValueError  time data  2008-09-03T20 56 35 450686 05 00  does not match format   Y- m- dT H  M  S  fZ   Unless you re certain that you only need to support RFC 3339 datetimes in Zulu time  and not ones with other timezone offsets  don t use strptime  Use one of the many other approaches described in answers here instead

User · Answer

What is the exact error you get  Is it like the following    gt  gt  gt  datetime datetime strptime  2008-08-12T12 20 30 656234Z     Y- m- dT H  M  S Z   ValueError  time data did not match format   data 2008-08-12T12 20 30 656234Z  fmt  Y- m- dT H  M  S Z   If yes  you can split your input string on      and then add the microseconds to the datetime you got   Try this    gt  gt  gt  def gt dt str           dt     us  dt str partition              dt  datetime datetime strptime dt    Y- m- dT H  M  S           us  int us rstrip  Z    10          return dt   datetime timedelta microseconds us    gt  gt  gt  gt  2008-08-12T12 20 30 656234Z   datetime datetime 2008  8  12  12  20  30  656234

User · Answer

If you don t want to use dateutil  you can try this function   def from utc utcTime fmt   Y- m- dT H  M  S  fZ                Convert UTC time string to time struct time               change datetime datetime to time  return time struct time type     return datetime datetime strptime utcTime  fmt    Test   from utc  2007-03-04T21 08 12 123Z     Result   datetime datetime 2007  3  4  21  8  12  123000

User · Answer

Thanks to great Mark Amery s answer I devised function to account for all possible ISO formats of datetime   class FixedOffset tzinfo          Fixed offset in minutes   time   utc time   utc offset          def   init   self  offset           self   offset   timedelta minutes offset          hours  minutes   divmod offset  60           NOTE  the last part is to remind about deprecated POSIX GMT h timezones            that have the opposite sign in the name             the corresponding numeric value is not used e g   no minutes         self   name     lt   03d 02d gt   d     hours  minutes  -hours      def utcoffset self  dt None           return self   offset     def tzname self  dt None           return self   name     def dst self  dt None           return timedelta 0      def   repr   self           return  FixedOffset  d      self utcoffset   total seconds     60      def   getinitargs   self           return  self   offset total seconds   60    def parse isoformat datetime isodatetime       try          return datetime strptime isodatetime    Y- m- dT H  M  S  f       except ValueError          pass     try          return datetime strptime isodatetime    Y- m- dT H  M  S       except ValueError          pass     pat   r       -  d 2     d 2        temp   re sub pat  r  1 2   isodatetime      naive date str   temp  -5      offset str   temp -5       naive dt   datetime strptime naive date str    Y- m- dT H  M  S  f       offset   int offset str -4 -2   60   int offset str -2        if offset str 0      -           offset   -offset     return naive dt replace tzinfo FixedOffset offset

User · Answer

def parseISO8601DateTime datetimeStr       import time     from datetime import datetime  timedelta      def log date string when           gmt   time gmtime when          if time daylight and gmt 8               tz   time altzone         else              tz   time timezone         if tz  gt  0              neg   1         else              neg   0             tz   -tz         h  rem   divmod tz  3600          m  rem   divmod rem  60          if neg              offset    - 02d 02d     h  m          else              offset      02d 02d     h  m           return time strftime   d  b  Y  H  M  S    gmt    offset      dt   datetime strptime datetimeStr    Y- m- dT H  M  S  fZ       timestamp   dt timestamp       return dt   timedelta hours dt hour-time gmtime timestamp  tm hour    Note that we should look if the string doesn t ends with Z  we could parse using  z

User · Answer

Nowadays there s Maya  Datetimes for Humans     from the author of the popular Requests  HTTP for Humans    package    gt  gt  gt  import maya  gt  gt  gt  str    2008-09-03T20 56 35 450686Z   gt  gt  gt  maya MayaDT from rfc3339 str  datetime   datetime datetime 2008  9  3  20  56  35  450686  tzinfo  lt UTC gt

User · Answer

In these days  Arrow also can be used as a third-party solution    gt  gt  gt  import arrow  gt  gt  gt  date   arrow get  2008-09-03T20 56 35 450686Z    gt  gt  gt  date datetime datetime datetime 2008  9  3  20  56  35  450686  tzinfo tzutc

User · Answer

The python-dateutil will throw an exception if parsing invalid date strings  so you may want to catch the exception   from dateutil import parser ds    2012-60-31  try    dt   parser parse ds  except ValueError  e    print    s  is an invalid date    ds

User · Answer

I m the author of iso8601 utils  It can be found on GitHub or on PyPI  Here s how you can parse your example    gt  gt  gt  from iso8601utils import parsers  gt  gt  gt  parsers datetime  2008-09-03T20 56 35 450686Z   datetime datetime 2008  9  3  20  56  35  450686

User · Answer

The python-dateutil package can parse not only RFC 3339 datetime strings like the one in the question  but also other ISO 8601 date and time strings  that don t comply with RFC 3339  such as ones with no UTC offset  or ones that represent only a date     gt  gt  gt  import dateutil parser  gt  gt  gt  dateutil parser isoparse  2008-09-03T20 56 35 450686Z     RFC 3339 format datetime datetime 2008  9  3  20  56  35  450686  tzinfo tzutc     gt  gt  gt  dateutil parser isoparse  2008-09-03T20 56 35 450686     ISO 8601 extended format datetime datetime 2008  9  3  20  56  35  450686   gt  gt  gt  dateutil parser isoparse  20080903T205635 450686     ISO 8601 basic format datetime datetime 2008  9  3  20  56  35  450686   gt  gt  gt  dateutil parser isoparse  20080903     ISO 8601 basic format  date only datetime datetime 2008  9  3  0  0      Note that dateutil parser isoparse is presumably stricter than the more hacky dateutil parser parse  but both of them are quite forgiving and will attempt to interpret the string that you pass in  If you want to eliminate the possibility of any misreads  you need to use something stricter than either of these functions   The Pypi name is python-dateutil  not dateutil  thanks code3monk3y    pip install python-dateutil   If you re using Python 3 7  have a look at this answer about datetime datetime fromisoformat

User · Answer

An another way is to use specialized parser for ISO-8601 is to use isoparse function of dateutil parser   from dateutil import parser  date   parser isoparse  2008-09-03T20 56 35 450686 01 00   print date    Output   2008-09-03 20 56 35 450686 01 00   This function is also mentioned in the documentation for the standard Python function datetime fromisoformat      A more full-featured ISO 8601 parser  dateutil parser isoparse is   available in the third-party package dateutil

User · Answer

If you are working with Django  it provides the dateparse module that accepts a bunch of formats similar to ISO format  including the time zone   If you are not using Django and you don t want to use one of the other libraries mentioned here  you could probably adapt the Django source code for dateparse to your project

User · Answer

I have found ciso8601 to be the fastest way to parse ISO 8601 timestamps  As the name suggests  it is implemented in C   import ciso8601 ciso8601 parse datetime  2014-01-09T21 48 00 921000 05 30     The GitHub Repo README shows their  10x speedup versus all of the other libraries listed in the other answers   My personal project involved a lot of ISO 8601 parsing  It was nice to be able to just switch the call and go 10x faster      Edit  I have since become a maintainer of ciso8601  It s now faster than ever

User · Answer

For something that works with the 2 X standard library try   calendar timegm time strptime date split      0   UTC     Y- m- dT H  M  S Z      calendar timegm is the missing gm version of time mktime

User · Answer

Initially I tried with   from operator import neg  pos from time import strptime  mktime from datetime import datetime  tzinfo  timedelta  class MyUTCOffsetTimezone tzinfo        staticmethod     def with offset offset no signal  signal      type   str  str  - gt  MyUTCOffsetTimezone         return MyUTCOffsetTimezone  pos if signal        else neg                datetime strptime offset no signal    H  M   - datetime 1900  1  1              total seconds          def   init   self  offset  name None           self offset   timedelta seconds offset          self name   name or self   class     name        def utcoffset self  dt           return self offset      def tzname self  dt           return self name      def dst self  dt           return timedelta 0    def to datetime tz dt      type   str  - gt  datetime     fmt     Y- m- dT H  M  S  f      if dt -6  in frozenset        -             dt  sign  offset   strptime dt  -6   fmt   dt -6   dt -5           return datetime fromtimestamp mktime dt                                         tz MyUTCOffsetTimezone with offset offset  sign       elif dt -1      Z           return datetime strptime dt  fmt    Z       return datetime strptime dt  fmt    But that didn t work on negative timezones  This however I got working fine  in Python 3 7 3   from datetime import datetime   def to datetime tz dt      type   str  - gt  datetime     fmt     Y- m- dT H  M  S  f      if dt -6  in frozenset        -             return datetime strptime dt  fmt     z       elif dt -1      Z           return datetime strptime dt  fmt    Z       return datetime strptime dt  fmt    Some tests  note that the out only differs by precision of microseconds  Got to 6 digits of precision on my machine  but YMMV   for dt in  dt out in             2019-03-11T08 00 00 000Z    2019-03-11T08 00 00              2019-03-11T08 00 00 000 11 00    2019-03-11T08 00 00 11 00              2019-03-11T08 00 00 000-11 00    2019-03-11T08 00 00-11 00              isoformat   to datetime tz dt in  isoformat       assert isoformat    dt out             format isoformat  dt out

User · Answer

One straightforward way to convert an ISO 8601-like date string to a UNIX timestamp or datetime datetime object in all supported Python versions without installing third-party modules is to use the date parser of SQLite      usr bin env python from   future   import with statement  division  print function import sqlite3 import datetime  testtimes          2016-08-25T16 01 26 123456Z        2016-08-25T16 01 29     db   sqlite3 connect   memory    c   db cursor   for timestring in testtimes      c execute  SELECT strftime   s         timestring        converted   c fetchone   0      print   s is  s after epoch     timestring  converted       dt   datetime datetime fromtimestamp int converted       print  datetime is  s    dt    Output   2016-08-25T16 01 26 123456Z is 1472140886 after epoch datetime is 2016-08-25 12 01 26 2016-08-25T16 01 29 is 1472140889 after epoch datetime is 2016-08-25 12 01 29

User · Answer

Try the iso8601 module  it does exactly this   There are several other options mentioned on the WorkingWithTime page on the python org wiki

User · Answer

Django s parse datetime   function supports dates with UTC offsets   parse datetime  2016-08-09T15 12 03 65478Z     datetime datetime 2016  8  9  15  12  3  654780  tzinfo  lt UTC gt     So it could be used for parsing ISO nbsp 8601 dates in fields within entire project   from django utils import formats from django forms fields import DateTimeField from django utils dateparse import parse datetime  class DateTimeFieldFixed DateTimeField       def strptime self  value  format           if format     iso-8601               return parse datetime value          return super   strptime value  format   DateTimeField strptime   DateTimeFieldFixed strptime formats ISO INPUT FORMATS  DATETIME INPUT FORMATS   insert 0   iso-8601

User · Answer

Note in Python 2 6  and Py3K  the  f character catches microseconds    gt  gt  gt  datetime datetime strptime  2008-09-03T20 56 35 450686Z     Y- m- dT H  M  S  fZ     See issue here

User · Answer

Starting from Python 3 7  strptime supports colon delimiters in UTC offsets  source   So you can then use   import datetime datetime datetime strptime  2018-01-31T09 24 31 488670 00 00     Y- m- dT H  M  S  f z     EDIT   As pointed out by Martijn  if you created the datetime object using isoformat    you can simply use datetime fromisoformat

User · Answer

Just use the python-dateutil module    gt  gt  gt  import dateutil parser as dp  gt  gt  gt  t    1984-06-02T19 05 00 000Z   gt  gt  gt  parsed t   dp parse t   gt  gt  gt  print parsed t  datetime datetime 1984  6  2  19  5  tzinfo tzutc      Documentation

User · Answer

A simple option from one of the comments  replace  Z  with   00 00  - and use Python 3 7  s fromisoformat  from datetime import datetime  s    quot 2008-09-03T20 56 35 450686Z quot   datetime fromisoformat s replace  Z     00 00      datetime datetime 2008  9  3  20  56  35  450686  tzinfo datetime timezone utc   Although strptime can parse the  Z  character to UTC  fromisoformat is faster by   x40  see also  A faster strptime    timeit datetime fromisoformat s replace  Z     00 00    346 ns    22 3 ns per loop  mean    std  dev  of 7 runs  1000000 loops each    timeit datetime strptime s    Y- m- dT H  M  S  f z   14 2   s    452 ns per loop  mean    std  dev  of 7 runs  100000 loops each    timeit dateutil parser parse s  80 1   s    3 32   s per loop  mean    std  dev  of 7 runs  10000 loops each    Python 3 8 7 x64 on Windows 10

User · Answer

Because ISO 8601 allows many variations of optional colons and dashes being present  basically CCYY-MM-DDThh mm ss Z    - hh mm   If you want to use strptime  you need to strip out those variations first   The goal is to generate a utc datetime object   If you just want a basic case that work for UTC with the Z suffix like 2016-06-29T19 36 29 3453Z   datetime datetime strptime timestamp translate None    -      Y m dT H M S  fZ      If you want to handle timezone offsets like 2016-06-29T19 36 29 3453-0400 or 2008-09-03T20 56 35 450686 05 00 use the following  These will convert all variations into something without variable delimiters like  20080903T205635 450686 0500 making it more consistent easier to parse   import re   this regex removes all colons and all    dashes EXCEPT for the dash indicating   or - utc offset for the timezone conformed timestamp   re sub r       -       d 2     d 2     d 4             timestamp  datetime datetime strptime conformed timestamp    Y m dT H M S  f z       If your system does not support the  z strptime directive  you see something like ValueError   z  is a bad directive in format   Y m dT H M S  f z   then you need to manually offset the time from Z  UTC   Note  z may not work on your system in python versions  lt  3 as it depended on the c library support which varies across system python build type  i e  Jython  Cython  etc     import re import datetime    this regex removes all colons and all    dashes EXCEPT for the dash indicating   or - utc offset for the timezone conformed timestamp   re sub r       -       d 2     d 2     d 4             timestamp     split on the offset to remove it  use a capture group to keep the delimiter split timestamp   re split r    -   conformed timestamp  main timestamp   split timestamp 0  if len split timestamp     3      sign   split timestamp 1      offset   split timestamp 2  else      sign   None     offset   None    generate the datetime object without the offset at UTC time output datetime   datetime datetime strptime main timestamp   Z     Y m dT H M S  fZ    if offset        create timedelta based on offset     offset delta   datetime timedelta hours int sign offset  -2    minutes int sign offset -2           offset datetime with timedelta     output datetime   output datetime   offset delta

User · Answer

New in Python 3 7     The datetime standard library introduced a function for inverting datetime isoformat        classmethod datetime fromisoformat date string        Return a datetime corresponding to a date string in one of the formats   emitted by date isoformat   and datetime isoformat          Specifically  this function supports strings in the format s        YYYY-MM-DD  HH  MM  SS  mmm mmm      HH MM  SS  ffffff          where   can match any single character        Caution  This does not support parsing arbitrary ISO 8601 strings - it is only intended as the inverse   operation of datetime isoformat      Example of use   from datetime import datetime  date   datetime fromisoformat  2017-01-01T12 30 59 000000

User · Answer

This works for stdlib on Python 3 2 onwards  assuming all the timestamps are UTC    from datetime import datetime  timezone  timedelta datetime strptime timestamp    Y- m- dT H  M  S  fZ   replace      tzinfo timezone timedelta 0      For example    gt  gt  gt  datetime utcnow   replace tzinfo timezone timedelta 0        datetime datetime 2015  3  11  6  2  47  879129  tzinfo datetime timezone utc

User · Answer

I ve coded up a parser for the ISO 8601 standard and put it on GitHub  https   github com boxed iso8601  This implementation supports everything in the specification except for durations  intervals  periodic intervals  and dates outside the supported date range of Python s datetime module   Tests are included   P

[python] How do I parse an ISO 8601-formatted date?

Examples related to python

Examples related to datetime

Examples related to iso8601

Examples related to datetime-parsing

Examples related to rfc3339