From 830dff91720182949d18002876494627a9a1e340 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Fri, 1 Mar 2024 07:58:14 +0000 Subject: [PATCH 1/2] gh-70647: Better promote how to safely parse yearless dates in datetime. Every four years people encounter this because it just isn't obvious. This moves the footnote up to a note with a code example. We'd love to change the default year value for datetime but doing that could have other consequences for existing code. This documented workaround *always* works. --- Doc/library/datetime.rst | 26 +++++++++++++++++++++++--- 1 file changed, 23 insertions(+), 3 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index b21c142cd80666..faaf1586416a9c 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -2526,7 +2526,24 @@ Broadly speaking, ``d.strftime(fmt)`` acts like the :mod:`time` module's For the :meth:`.datetime.strptime` class method, the default value is ``1900-01-01T00:00:00.000``: any components not specified in the format string -will be pulled from the default value. [#]_ +will be pulled from the default value. + +.. note:: + When used to parse partial dates lacking a year, :meth:`~.datetime.strptime` + will raise when encountering February 29 because its default year of 1900 is + *not* a leap year. Always add a default leap year to partial date strings + before parsing:: + + .. doctest:: + + >>> from datetime import datetime + >>> value = "2/29" + >>> datetime.strptime(value, "%m/%d") + Traceback (most recent call last): + ... + ValueError: day is out of range for month + >>> datetime.strptime(f"1904 {value}", "%Y %m/%d") + datetime.datetime(1904, 2, 29, 0, 0) Using ``datetime.strptime(date_string, format)`` is equivalent to:: @@ -2652,6 +2669,11 @@ Notes: for formats ``%d``, ``%m``, ``%H``, ``%I``, ``%M``, ``%S``, ``%j``, ``%U``, ``%W``, and ``%V``. Format ``%y`` does require a leading zero. +(10) + Parsing dates without a year using :meth:`~.datetime.strptime` will fail on + representations of February 29 as that date does not exist in the default + year of 1900. + .. rubric:: Footnotes .. [#] If, that is, we ignore the effects of Relativity @@ -2665,5 +2687,3 @@ Notes: .. [#] See R. H. van Gent's `guide to the mathematics of the ISO 8601 calendar `_ for a good explanation. - -.. [#] Passing ``datetime.strptime('Feb 29', '%b %d')`` will fail since 1900 is not a leap year. From ae1f29e5199d57943fe83f75a7c262f6aea113c9 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith [Google LLC]" Date: Fri, 1 Mar 2024 08:25:25 +0000 Subject: [PATCH 2/2] doctest code within note is bad, dedent. --- Doc/library/datetime.rst | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index faaf1586416a9c..0f2f5eb07d8599 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -2532,18 +2532,18 @@ will be pulled from the default value. When used to parse partial dates lacking a year, :meth:`~.datetime.strptime` will raise when encountering February 29 because its default year of 1900 is *not* a leap year. Always add a default leap year to partial date strings - before parsing:: + before parsing. - .. doctest:: +.. doctest:: - >>> from datetime import datetime - >>> value = "2/29" - >>> datetime.strptime(value, "%m/%d") - Traceback (most recent call last): - ... - ValueError: day is out of range for month - >>> datetime.strptime(f"1904 {value}", "%Y %m/%d") - datetime.datetime(1904, 2, 29, 0, 0) + >>> from datetime import datetime + >>> value = "2/29" + >>> datetime.strptime(value, "%m/%d") + Traceback (most recent call last): + ... + ValueError: day is out of range for month + >>> datetime.strptime(f"1904 {value}", "%Y %m/%d") + datetime.datetime(1904, 2, 29, 0, 0) Using ``datetime.strptime(date_string, format)`` is equivalent to::