[3.12] gh-70647: update docs to mention the datetime 1900 year default 2/29 issue...

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

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index b21c142cd80666a9b8bbeac06a71e6d538dbc15e..0f2f5eb07d85991760e7ac2d03dfa7433198bcea 100644 (file)
--- 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
        <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.