gh-124549: Document that strptime uses the last directive when a time unit is over-specified

[Mariatta]

---

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

• Issue: datetime.strptime accepts incompatible arguments #124549

[StanFromIreland]

Is a note here the best place for this?

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35250757 | 📁 Comparing f8937f1 against main (2d81eae)

  🔍 Preview build  

1 file changed

± library/datetime.html

[StanFromIreland]

Suggested change

	.. note::
	When parsing a string using :meth:`.datetime.strptime` or
	:meth:`.date.strptime`, if more than one directive for the same time unit
	is used, only the last directive is parsed and applied to the resulting
	object. For example, if the format string contains both ``%Y`` and ``%y``,
	like ``%Y%y``, only the last directive in the string (``%y``) determines
	the year of the result.
	.. note::
	If a :meth:`~.datetime.strptime` format string contains more than
	one directive for the same field, for example both ``%Y`` and ``%y``,
	every directive must still match the input, but only the value of the
	last one is used. For example, parsing ``200099`` with ``%Y%y`` gives
	the year 1999. Repeating the same directive, like ``%Y%Y``, raises an error.

A few little suggestions merged (sorry, it was easier with wrapping this way, feel free to split as you see fit!):

• De-duplicate strptime.
• "only the last directive is parsed": I fear "parsed" is a little misleading, as they do still have to match.
• "same time unit": technically it's not so simple, e.g. %j always wins over %d due to parsing implementation details.
• Also suggest adding a concrete example.