https://github.com/python/cpython/commit/3eb7a9024b91d67d1c137633038e64e361b6fcd4
commit: 3eb7a9024b91d67d1c137633038e64e361b6fcd4
branch: 3.12
author: Gregory P. Smith <g...@krypto.org>
committer: gpshead <g...@krypto.org>
date: 2025-03-20T21:50:10-07:00
summary:
[3.12] gh-70647: update docs to mention the datetime 1900 year default 2/29
issue (#131534)
* 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.
files:
M Doc/library/datetime.rst
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index b21c142cd80666..0f2f5eb07d8599 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
<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.
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
