From 8f795802dd29e2ef8fe903a9ad400e74a800297e Mon Sep 17 00:00:00 2001 From: Michael Overmeyer Date: Sat, 26 Nov 2022 16:11:35 -0500 Subject: [PATCH] Update the docs --- CHANGELOG.md | 3 ++- README.rst | 20 ++++++++++---------- why_ciso8601.md | 2 +- 3 files changed, 13 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 91857f5..e6e6cad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ - [Version 2.0.0](#version-200) - [Breaking changes](#breaking-changes) - [Other Changes](#other-changes) - - [v1.x.x -> 2.0.0 Migration guide](#v1xx---200-migration-guide) + - [v1.x.x -\> 2.0.0 Migration guide](#v1xx---200-migration-guide) - [ValueError instead of None](#valueerror-instead-of-none) - [Tightened ISO 8601 conformance](#tightened-iso-8601-conformance) - [`parse_datetime_unaware` has been renamed](#parse_datetime_unaware-has-been-renamed) @@ -25,6 +25,7 @@ * Removed improper ability to call `FixedOffset`'s `dst`, `tzname` and `utcoffset` without arguments * 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)) # 2.x.x diff --git a/README.rst b/README.rst index c410d9b..50b8536 100644 --- a/README.rst +++ b/README.rst @@ -16,12 +16,15 @@ 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. -**Note:** ciso8601 doesn't support the entirety of the ISO 8601 spec, `only a popular subset`_. +.. |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; only `the subset`_ supported by Python itself (|datetime.fromisoformat|_). .. _ISO 8601: https://en.wikipedia.org/wiki/ISO_8601 .. _RFC 3339: https://tools.ietf.org/html/rfc3339 -.. _`only a popular subset`: https://github.com/closeio/ciso8601#supported-subset-of-iso-8601 +.. _`the subset`: 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) @@ -191,7 +194,8 @@ Tested on Linux 5.10.16.3-microsoft-standard-WSL2 using the following modules: .. -**Note:** ciso8601 doesn't support the entirety of the ISO 8601 spec, `only a popular subset`_. +**Note:** ciso8601 doesn't support the entirety of the ISO 8601 spec; only `the subset`_ supported by Python itself (|datetime.fromisoformat|_). + For full benchmarking details (or to run the benchmark yourself), see `benchmarking/README.rst`_ @@ -200,7 +204,7 @@ For full benchmarking details (or to run the benchmark yourself), see `benchmark Supported Subset of ISO 8601 ---------------------------- -``ciso8601`` only supports the most common subset of ISO 8601. +``ciso8601`` only supports the subset of ISO 8601 that is supported by Python itself (|datetime.fromisoformat|_) Date Formats ^^^^^^^^^^^^ @@ -215,7 +219,7 @@ The following date formats are supported: ============================= ============== ================== ``YYYY-MM-DD`` ``2018-04-29`` ✅ ``YYYY-MM`` ``2018-04`` ✅ - ``YYYYMMDD`` ``20180429`` ✅ + ``YYYYMMDD`` ``20180429`` ✅ ``--MM-DD`` (omitted year) ``--04-29`` ❌ ``--MMDD`` (omitted year) ``--0429`` ❌ ``±YYYYY-MM`` (>4 digit year) ``+10000-04`` ❌ @@ -223,7 +227,7 @@ The following date formats are supported: ``-YYYY-MM`` (negative -) ``-2018-04`` ❌ ============================= ============== ================== -Week dates or ordinal dates are not currently supported. +Ordinal dates are not currently supported. .. table:: :widths: auto @@ -231,10 +235,6 @@ Week dates or ordinal dates are not currently supported. ============================= ============== ================== Format Example Supported ============================= ============== ================== - ``YYYY-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`` ❌ ============================= ============== ================== diff --git a/why_ciso8601.md b/why_ciso8601.md index 322823b..0fdd4b9 100644 --- a/why_ciso8601.md +++ b/why_ciso8601.md @@ -72,7 +72,7 @@ RFC 3339 can be (roughly) thought of as a subset of ISO 8601. If you need strict ## 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). +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: