From: Gregory P. Smith <68491+gpshead@users.noreply.github.com>
Date: Sun, 21 Dec 2025 07:03:24 +0000 (-0800)
Subject: [3.13] gh-70647: Better promote how to safely parse yearless dates in datetime. ... 
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=9b7a6286327b0e03d258316dde7419ca0a7e10f3;p=thirdparty%2FPython%2Fcpython.git

[3.13] gh-70647: Better promote how to safely parse yearless dates in datetime. (GH-116179) (#143038)

* gh-70647: Better promote how to safely parse yearless dates in datetime. (GH-116179)

* 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.

* doctest code within note is bad, dedent.

* Update to match the error message.

* remove no longer referenced footnote

* ignore the warning in the doctest

* use Petr's suggestion for the docs to hide the warning processing

* cover date.strptime (3.14) as well

* remove date.strptime mentions from 3.14
---

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 99a979038adb..64356c9b6b04 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -2589,7 +2589,40 @@ 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 the default year of 1900 is
+   *not* a leap year.  Always add a default leap year to partial date strings
+   before parsing.
+
+
+.. testsetup::
+
+    # doctest seems to turn the warning into an error which makes it
+    # show up and require matching and prevents the actual interesting
+    # exception from being raised.
+    # Manually apply the catch_warnings context manager
+    import warnings
+    catch_warnings = warnings.catch_warnings()
+    catch_warnings.__enter__()
+    warnings.simplefilter("ignore")
+
+.. testcleanup::
+
+    catch_warnings.__exit__()
+
+.. doctest::
+
+    >>> from datetime import datetime
+    >>> value = "2/29"
+    >>> datetime.strptime(value, "%m/%d")
+    Traceback (most recent call last):
+    ...
+    ValueError: day 29 must be in range 1..28 for month 2 in year 1900
+    >>> datetime.strptime(f"1904 {value}", "%Y %m/%d")
+    datetime.datetime(1904, 2, 29, 0, 0)
 
 Using ``datetime.strptime(date_string, format)`` is equivalent to::
 
@@ -2720,7 +2753,7 @@ Notes:
    include a year in the format.  If the value you need to parse lacks a year,
    append an explicit dummy leap year.  Otherwise your code will raise an
    exception when it encounters leap day because the default year used by the
-   parser is not a leap year.  Users run into this bug every four years...
+   parser (1900) is not a leap year.  Users run into that bug every leap year.
 
    .. doctest::
 
@@ -2747,5 +2780,3 @@ Notes:
 .. [#] See R. H. van Gent's `guide to the mathematics of the ISO 8601 calendar
        <https://web.archive.org/web/20220531051136/https://webspace.science.uu.nl/~gent0113/calendar/isocalendar.htm>`_
        for a good explanation.
-
-.. [#] Passing ``datetime.strptime('Feb 29', '%b %d')`` will fail since 1900 is not a leap year.