gh-70647: Better promote how to safely parse yearless dates in datetime.

[gpshead]

Every four years people encounter this in part because it just isn't obvious that partial incomplete date parsing is not what datetime.strptime is designed for. This moves the footnote up to a more explanatory inline note with a code example.

We'd love the default year value for datetime to be different, but changing that could have other consequences for existing code. This documented workaround always works.

• Issue: datetime.strptime without a year fails on Feb 29 #70647

---

📚 Documentation preview 📚: https://cpython-previews--116179.org.readthedocs.build/

[encukou]

Perhaps this should be only merged to the backport branches, not main.

[willingc]

@gpshead Looks like this may need some tidying up if you are still interested.

[StanFromIreland]

This has already been partially implemented (the smaller note) do we still want to add the larger note since its deprecated anyway?

[gpshead]

docs folks: Do we have a way to do this ignoring of the DeprecationWarning in the doctest code without polluting the example code with something I don't want anyone to ever write in their code?

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. (see the earlier failing builds on this PR)

[encukou]

Here's a way, I don't know if it's the best way:

.. 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__()

.. testcleanup::

   catch_warnings.__exit__()

.. doctest::

    >>> from datetime import datetime
    >>> import warnings
    >>> 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)

[StanFromIreland]

Maybe the error is something to do with the C implementation. Depreciation errors don’t show up in the repl unless they are from a C extension resulting in them being forcibly displayed.