diff --git a/CHANGELOG.md b/CHANGELOG.md index e6e6cad..2b068a2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -26,6 +26,7 @@ * Fixed: `datetime.tzname` returns a `str` in Python 2.7, not a `unicode` * Change `METH_VARARGS` to `METH_O`, enhancing performance. ([#130](https://github.com/closeio/ciso8601/pull/130)) * Added support for ISO week dates, ([#139](https://github.com/closeio/ciso8601/pull/139)) +* Added support for ordinal dates, ([#140](https://github.com/closeio/ciso8601/pull/140)) # 2.x.x diff --git a/README.rst b/README.rst index cb7d7c4..c732daf 100644 --- a/README.rst +++ b/README.rst @@ -16,16 +16,9 @@ ciso8601 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, 3.10, 3.11. -.. |datetime.fromisoformat| replace:: ``datetime.fromisoformat`` -.. _datetime.fromisoformat: https://docs.python.org/3/library/datetime.html#datetime.datetime.fromisoformat - -**Note:** ciso8601 doesn't support the entirety of the ISO 8601 spec; but supports `a superset`_ of what is supported by Python itself (|datetime.fromisoformat|_). - .. _ISO 8601: https://en.wikipedia.org/wiki/ISO_8601 .. _RFC 3339: https://tools.ietf.org/html/rfc3339 -.. _`a superset`: https://github.com/closeio/ciso8601#supported-subset-of-iso-8601 - (Interested in working on projects like this? `Close`_ is looking for `great engineers`_ to join our team) .. _Close: https://close.com @@ -203,9 +196,6 @@ Tested on Linux 5.15.49-linuxkit using the following modules: .. -**Note:** ciso8601 doesn't support the entirety of the ISO 8601 spec; but supports `a superset`_ of what is supported by Python itself (|datetime.fromisoformat|_). - - For full benchmarking details (or to run the benchmark yourself), see `benchmarking/README.rst`_ .. _`benchmarking/README.rst`: https://github.com/closeio/ciso8601/blob/master/benchmarking/README.rst @@ -213,6 +203,9 @@ For full benchmarking details (or to run the benchmark yourself), see `benchmark Supported subset of ISO 8601 ---------------------------- +.. |datetime.fromisoformat| replace:: ``datetime.fromisoformat`` +.. _datetime.fromisoformat: https://docs.python.org/3/library/datetime.html#datetime.datetime.fromisoformat + ``ciso8601`` only supports a subset of ISO 8601, but supports a superset of what is supported by Python itself (|datetime.fromisoformat|_), and supports the entirety of the `RFC 3339`_ specification. Date formats @@ -233,8 +226,18 @@ The following date formats are supported: ``YYYY-Www`` (week date) ``2009-W01`` ✅ ``YYYYWwwD`` (week date) ``2009W011`` ✅ ``YYYYWww`` (week date) ``2009W01`` ✅ - ``YYYY-DDD`` (ordinal date) ``1981-095`` ❌ - ``YYYYDDD`` (ordinal date) ``1981095`` ❌ + ``YYYY-DDD`` (ordinal date) ``1981-095`` ✅ + ``YYYYDDD`` (ordinal date) ``1981095`` ✅ + ============================= ============== ================== + +Uncommon ISO 8601 date formats are not supported: + +.. table:: + :widths: auto + + ============================= ============== ================== + Format Example Supported + ============================= ============== ================== ``--MM-DD`` (omitted year) ``--04-29`` ❌ ``--MMDD`` (omitted year) ``--0429`` ❌ ``±YYYYY-MM`` (>4 digit year) ``+10000-04`` ❌ diff --git a/benchmarking/README.rst b/benchmarking/README.rst index 71d1907..aa2e35a 100644 --- a/benchmarking/README.rst +++ b/benchmarking/README.rst @@ -7,9 +7,7 @@ Benchmarking ciso8601 Introduction ------------ -``ciso8601``'s goal is to be the world's fastest ISO 8601 datetime parser for Python (**Note:** ciso8601 `only supports a subset of ISO 8601`_). - -.. _`only supports a subset of ISO 8601`: https://github.com/closeio/ciso8601#supported-subset-of-iso-8601 +``ciso8601``'s goal is to be the world's fastest ISO 8601 datetime parser for Python. In order to see how we compare, we run benchmarks against each other known ISO 8601 parser. diff --git a/why_ciso8601.md b/why_ciso8601.md index 2848e2d..b340f4c 100644 --- a/why_ciso8601.md +++ b/why_ciso8601.md @@ -6,7 +6,6 @@ This document aims to describe some considerations to make when choosing a times - [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) - [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) @@ -14,35 +13,24 @@ This document aims to describe some considerations to make when choosing a times ```mermaid graph TD; + A[Do you care about the performance of timestamp parsing?] + A--yes-->Y; + A--no-->C; + C[Do you need to support Python 2.7?]; - C--yes-->DD + C--yes-->Y C--no-->E E[Do you need strict RFC 3339 parsing?]; - E--yes-->YY; - E--no-->AA; - - AA[Do you care about the performance of timestamp parsing?] - AA--yes-->D; - AA--no-->H; + E--yes-->Y; + E--no-->H; H[Do you need to support Python < 3.11?] H--yes-->V; H--no-->Z; - 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--yes-->Y; - D--no-->W; - V[Use `backports.datetime_fromisoformat`] - W[Use `pendulum.parsing.parse_iso8601`] - WW[Use `pendulum.parsing.parse_iso8601`] Y[Use `ciso8601`] - YY[Use `ciso8601`] Z[Use `datetime.fromisoformat`] ``` @@ -59,17 +47,6 @@ If you really, truly want to use the fastest parser, then `ciso8601` aims to be 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 subset of ISO 8601](https://github.com/closeio/ciso8601#supported-subset-of-iso-8601) that is supported by Python itself. - -If not, consider [`pendulum`](https://github.com/sdispater/pendulum)'s `parsing.parse_iso8601` instead: - -```python -from pendulum.parsing import parse_iso8601 -parse_iso8601(timestamp) -``` - ## 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).