diff --git a/README.rst b/README.rst index eab719a..c410d9b 100644 --- a/README.rst +++ b/README.rst @@ -57,6 +57,13 @@ See `CHANGELOG`_ for the Migration Guide. .. _CHANGELOG: https://github.com/closeio/ciso8601/blob/master/CHANGELOG.md +When should I not use ``cis8601``? +---------------------------------- + +``ciso8601`` is not necessarily the best solution for every use case (especially since Python 3.11). See `Should I use ciso8601?`_ + +.. _`Should I use ciso8601?`: https://github.com/closeio/ciso8601/blob/master/why_ciso8601.md + Error Handling -------------- diff --git a/why_ciso8601.md b/why_ciso8601.md new file mode 100644 index 0000000..322823b --- /dev/null +++ b/why_ciso8601.md @@ -0,0 +1,96 @@ +# Should I use ciso8601? + +`ciso8601`'s goal is to be the world's fastest ISO 8601 datetime parser for Python. +However, `ciso8601` is not the right choice for all use cases. +This document aims to describe some considerations to make when choosing a timestamp parsing library. + +- [Do you care about the performance of timestamp parsing?](#do-you-care-about-the-performance-of-timestamp-parsing) +- [Do you need strict RFC 3339 parsing?](#do-you-need-strict-rfc-3339-parsing) +- [Are you OK with the subset of ISO 8601 supported by ciso8601?](#are-you-ok-with-the-subset-of-iso-8601-supported-by-ciso8601) +- [Are you only parsing timestamps produced by `datetime.isoformat`?](#are-you-only-parsing-timestamps-produced-by-datetimeisoformat) +- [Do you need to support Python \< 3.11?](#do-you-need-to-support-python--311) +- [Do you need to support Python 2.7?](#do-you-need-to-support-python-27) + +### Flowchart + +```mermaid +graph TD; + A[Do you care about the performance of timestamp parsing?] + A--yes-->D; + A--no-->C; + C[Do you need to support Python 2.7?]; + C--yes-->DD + C--no-->E + E[Do you need strict RFC 3339 parsing?]; + E--yes-->YY; + E--no-->G; + G[Are you only parsing timestamps produced by `datetime.isoformat`?] + G--yes-->F; + G--no-->H; + F[Do you need to support Python < 3.7?] + F--yes-->V; + F--no-->Z; + + H[Do you need to support Python < 3.11?] + H--no-->Z; + H--yes--->D; + + DD[Are you OK with the subset of ISO 8601 supported by ciso8601?] + DD--no-->WW; + DD--yes-->YY; + + + D[Are you OK with the subset of ISO 8601 supported by ciso8601?] + D--no-->I; + D--yes--->Y; + + I[Do you need to support Python < 3.11?] + I--yes-->W; + I--no-->ZZ; + + V[Use `backports.datetime_fromisoformat`] + W[Use `pendulum.parsing.parse_iso8601`] + WW[Use `pendulum.parsing.parse_iso8601`] + Y[Use `cis8601`] + YY[Use `cis8601`] + Z[Use `datetime.fromisoformat`] + ZZ[Use `datetime.fromisoformat`] +``` + +## Do you care about the performance of timestamp parsing? + +In most Python programs, performance is not a primary concern. +Even for performance-sensitive programs, timestamp parsing performance is often a negligible portion of the time spent, and not a performance bottleneck. + +**Note:** Since Python 3.11+, the performance of cPython's `datetime.fromisoformat` is now very good. See [the benchmarks](https://github.com/closeio/ciso8601#benchmark). + +If you really, truly want to use the fastest parser, then `ciso8601` aims to be the fastest. See [the benchmarks](https://github.com/closeio/ciso8601#benchmark) to see how it compares to other options. + +## Do you need strict RFC 3339 parsing? + +RFC 3339 can be (roughly) thought of as a subset of ISO 8601. If you need strict timestamp parsing that will complain if the given timestamp isn't strictly RFC 3339 compliant, then [`ciso8601` has a `parse_rfc3339` method](https://github.com/closeio/ciso8601#strict-rfc-3339-parsing). + +## Are you OK with the subset of ISO 8601 supported by ciso8601? + +You probably are. `ciso8601` [supports the most commonly seen subset of ISO 8601 timestamps](https://github.com/closeio/ciso8601#supported-subset-of-iso-8601). + +If not, consider [`pendulum`](https://github.com/sdispater/pendulum)'s `parsing.parse_iso8601` instead: + +```python +from pendulum.parsing import parse_iso8601 +parse_iso8601(timestamp) +``` + +## Are you only parsing timestamps produced by `datetime.isoformat`? + +Since Python 3.7, `datetime.fromisoformat` supports parsing any timestamp output by `datetime.isoformat`, and the cPython implementation is [very performant](https://github.com/closeio/ciso8601#benchmark). + +If you need to support older versions of Python 3, consider [`backports.datetime_fromisoformat`](https://github.com/movermeyer/backports.datetime_fromisoformat). + +## Do you need to support Python < 3.11? + +Since Python 3.11, `datetime.fromisoformat` supports parsing nearly any ISO 8601 timestamp, and the cPython implementation is [very performant](https://github.com/closeio/ciso8601#benchmark). + +## Do you need to support Python 2.7? + +`ciso8601` still supports Python 2.7, and is [much faster](https://github.com/closeio/ciso8601#benchmark) than other options for this [deprecated version of Python](https://pythonclock.org/).