Package: ciso8601-wheels
Note: this fork is just for building binary wheels and uploading to pypi, under
the ``ciso8601-wheels`` package name!ciso8601ciso8601convertsISO 8601orRFC 3339date time strings into Python datetime objects.Since it’s written as a C module, it is much faster than other Python libraries.
Tested with cPython 2.7, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9.Note:ciso8601 doesn’t support the entirety of the ISO 8601 spec,only a popular subset.(Interested in working on projects like this?Closeis looking forgreat engineersto join our team)Contentsciso8601Quick StartMigration to v2Error HandlingBenchmarkSupported Subset of ISO 8601Date FormatsTime FormatsTime Zone InformationStrict RFC 3339 ParsingIgnoring Timezone Information While ParsingQuick Start%pipinstallciso8601In[1]:importciso8601In[2]:ciso8601.parse_datetime('2014-12-05T12:30:45.123456-05:30')Out[2]:datetime.datetime(2014,12,5,12,30,45,123456,tzinfo=pytz.FixedOffset(330))In[3]:ciso8601.parse_datetime('20141205T123045')Out[3]:datetime.datetime(2014,12,5,12,30,45)Migration to v2Version 2.0.0 ofciso8601changed the core implementation. This was not entirely backwards compatible, and care should be taken when migrating
SeeCHANGELOGfor the Migration Guide.Error HandlingStarting in v2.0.0,ciso8601offers strong guarantees when it comes to parsing strings.parse_datetime(dt: String): datetimeis a function that takes a string and either:Returns a properly parsed Python datetime,if and only iftheentirestring conforms to the supported subset of ISO 8601Raises aValueErrorwith a description of the reason why the string doesn’t conform to the supported subset of ISO 8601If time zone information is provided, an aware datetime object will be returned. Otherwise, a naive datetime is returned.BenchmarkParsing a timestamp with no time zone information (ex.2014-01-09T21:48:00):ModulePython 3.8Python 3.7Python 3.6Python 3.5Python 3.4Python 2.7Relative Slowdown (versus ciso8601, Python 3.8)ciso8601201 nsec157 nsec160 nsec139 nsec148 nsec147 nsecN/Apendulum215 nsec232 nsec234 nsec205 nsec192 nsec9.44 usec1.1xudatetime906 nsec1.06 usec767 nsec702 nsec819 nsec923 nsec4.5xstr2date5.96 usec7.75 usec7.27 usec6.84 usec7.6 usecIncorrect Result(None)29.7xisodate10.3 usec10 usec11.1 usec11.9 usec12.3 usec43.6 usec51.3xiso8601utils10.3 usec8.63 usec9.16 usec10.3 usec9.58 usec11.1 usec51.5xiso860110.9 usec11.1 usec10.5 usec11.2 usec11.5 usec25.6 usec54.2xPySO860113.9 usec21.9 usec20.2 usec15.9 usec23.7 usec16.4 usec69.4xaniso860114.5 usec15 usec15.8 usec15.9 usec16.1 usec17.2 usec72.5xzulu25.3 usec29.9 usec28.2 usec27.4 usec33 usecN/A126.3xmaya42.9 usec57.4 usec58.2 usec67.5 usec87.6 usec100 usec213.7xarrow85.7 usec81.8 usec75.7 usec78.7 usecN/A93.9 usec427.1xpython-dateutil122 usec82.7 usec72.2 usec77.1 usec74.4 usec131 usec609.5xmoment3.81 msec4.46 msec3.12 msec3.66 msecN/A3.59 msec19011.9xciso8601 takes 201 nsec, which is1.1x faster than pendulum, the next fastest ISO 8601 parser in this comparison.Parsing a timestamp with time zone information (ex.2014-01-09T21:48:00-05:30):ModulePython 3.8Python 3.7Python 3.6Python 3.5Python 3.4Python 2.7Relative Slowdown (versus ciso8601, Python 3.8)ciso8601207 nsec219 nsec282 nsec262 nsec264 nsec360 nsecN/Apendulum249 nsec225 nsec209 nsec212 nsec209 nsec12.9 usec1.2xudatetime806 nsec866 nsec817 nsec827 nsec792 nsec835 nsec3.9xstr2date7.57 usec10.7 usec7.98 usec8.48 usec9.06 usecIncorrect Result(None)36.7xisodate12 usec13.5 usec14.7 usec15.4 usec18.8 usec47.6 usec58.3xiso860112.8 usec14.6 usec14.6 usec15.2 usec17.7 usec30 usec61.8xaniso860119.4 usec30.4 usec22.1 usec20.5 usec21.9 usec20.1 usec94.0xiso8601utils22.5 usec25.3 usec26.4 usec25.7 usec27 usec26.9 usec108.9xzulu25.6 usec31.2 usec30 usec32.3 usec30.7 usecN/A124.1xPySO860125.9 usec35.4 usec25.6 usec29.5 usec27.7 usec25.7 usec125.2xmaya48.5 usec46.6 usec51.3 usec63.2 usec68.1 usec125 usec234.9xpython-dateutil79.3 usec88.5 usec101 usec89.8 usec91.9 usec160 usec384.2xarrow86.2 usec95.2 usec95 usec101 usecN/A103 usec417.2xmomentIncorrect Result(None)Incorrect Result(None)Incorrect Result(None)Incorrect Result(None)N/AIncorrect Result(None)3442935.3xciso8601 takes 207 nsec, which is1.2x faster than pendulum, the next fastest ISO 8601 parser in this comparison.Tested on Darwin 18.7.0 using the following modules:aniso8601==8.0.0arrow==0.15.2ciso8601==2.1.2iso8601==0.1.12iso8601utils==0.1.2isodate==0.6.0maya==0.6.1moment==0.8.2pendulum==2.0.5PySO8601==0.2.0python-dateutil==2.8.0str2date==0.905udatetime==0.0.16zulu==1.1.1Note:ciso8601 doesn’t support the entirety of the ISO 8601 spec,only a popular subset.For full benchmarking details (or to run the benchmark yourself), seebenchmarking/README.rstSupported Subset of ISO 8601ciso8601only supports the most common subset of ISO 8601.Date FormatsThe following date formats are supported:FormatExampleSupportedYYYY-MM-DD2018-04-29✅YYYY-MM2018-04✅YYYYMMDD2018-04✅--MM-DD(omitted year)--04-29❌--MMDD(omitted year)--0429❌±YYYYY-MM(>4 digit year)+10000-04❌+YYYY-MM(leading +)+2018-04❌-YYYY-MM(negative -)-2018-04❌Week dates or ordinal dates are not currently supported.FormatExampleSupportedYYYY-Www(week date)2009-W01❌YYYYWww(week date)2009W01❌YYYY-Www-D(week date)2009-W01-1❌YYYYWwwD(week date)2009-W01-1❌YYYY-DDD(ordinal date)1981-095❌YYYYDDD(ordinal date)1981095❌Time FormatsTimes are optional and are separated from the date by the letterT.Consistent withRFC 3339,ciso860also allows either a space character, or a lower-caset, to be used instead of aT.The following time formats are supported:FormatExampleSupportedhh11✅hhmm1130✅hh:mm11:30✅hhmmss113059✅hh:mm:ss11:30:59✅hhmmss.ssssss113059.123456✅hh:mm:ss.ssssss11:30:59.123456✅hhmmss,ssssss113059,123456✅hh:mm:ss,ssssss11:30:59,123456✅Midnight (special case)24:00:00✅hh.hhh(fractional hours)11.5❌hh:mm.mmm(fractional minutes)11:30.5❌Note:Python datetime objects only have microsecond precision (6 digits). Any additional precision will be truncated.Time Zone InformationTime zone information may be provided in one of the following formats:FormatExampleSupportedZZ✅zz✅±hh+11✅±hhmm+1130✅±hh:mm+11:30✅While the ISO 8601 specification allows the use of MINUS SIGN (U+2212) in the time zone separator,ciso8601only supports the use of the HYPHEN-MINUS (U+002D) character.Consistent withRFC 3339,ciso860also allows a lower-casezto be used instead of aZ.Strict RFC 3339 Parsingciso8601parses ISO 8601 datetimes, which can be thought of as a superset ofRFC 3339(roughly). In cases where you might want strict RFC 3339 parsing,ciso8601offers aparse_rfc3339method, which behaves in a similar manner toparse_datetime:parse_rfc3339(dt: String): datetimeis a function that takes a string and either:Returns a properly parsed Python datetime,if and only iftheentirestring conforms to RFC 3339.Raises aValueErrorwith a description of the reason why the string doesn’t conform to RFC 3339.Ignoring Timezone Information While ParsingIt takes more time to parse timestamps with time zone information, especially if they’re not in UTC. However, there are times when you don’t care about time zone information, and wish to produce naive datetimes instead.
For example, if you are certain that your program will only parse timestamps from a single time zone, you might want to strip the time zone information and only output naive datetimes.In these limited cases, there is a second function provided.parse_datetime_as_naivewill ignore any time zone information it finds and, as a result, is faster for timestamps containing time zone information.In[1]:importciso8601In[2]:ciso8601.parse_datetime_as_naive('2014-12-05T12:30:45.123456-05:30')Out[2]:datetime.datetime(2014,12,5,12,30,45,123456)NOTE:parse_datetime_as_naiveis only useful in the case where your timestamps have time zone information, but you want to ignore it. This is somewhat unusual.
If your timestamps don’t have time zone information (i.e. are naive), simply useparse_datetime. It is just as fast.