`strptime` token support and documentation modernization

[jyalim]

import datetime
# this will fail
datetime.datetime.strptime('2025-10-26','%F') 
# this will succeed
d0 = datetime.datetime.strptime('15:00:00','%T') 
print(d0.strftime('%FT%T'))

Example above ('%F', C99+ time.h format token) requires simple fix in the code; requires larger alignment in documentation.

Example Code Patch

To support '%F' in strptime requires adding a single line of code. The example above is fixed with the following line added to the TimeRE class __init__ method in Lib/_strptime.py,

base.__setitem__('F', self.pattern('%Y-%m-%d'))

just like existing code in that method for %T support (https://github.com/python/cpython/blob/main/Lib/_strptime.py#L421)

Documentation

The documentation refers to C89 (https://github.com/python/cpython/blob/main/Doc/library/datetime.rst?plain=1#L2498-L2636) and does not fully document the current level of strptime support.

Final thoughts

A larger discussion should be had on modernizing datetime and fully supporting C99 (ideally newer) time.h format tokens.

Linked PRs

• gh-140715: provide support for %F token in strptime; add test for it and %T #140647

[picnixz]

%F is not required by C89 but by C99 so this one is a feature request and the docs only promise C89 support. Adding a single additional format string would not be useful (it'd be better to add all C99 formats in this case). In addition, we already have datetime.fromisoformat() which parses ISO format. I'm closing this one as not planned (or duplicated) for now, and I think we have an umbrella issue for that (cc @StanFromIreland).

[jyalim]

I disagree that it would not be useful. %F would also not be the first C99+ format token, as stated in the original post. datetime.fromisoformat() is very useful but introduces new software patterns.

I am glad that an umbrella issue exists and work is being done on it. I could not find such an issue before posting this one, but did find this now closed PR [1] and its parent issue [2] to be substantially different and alarming enough (e.g., a discussion of "making %F useful for nanoseconds") to raise this one (for a larger modernization project).

[hugovk]

%F is not required by C89 but by C99 so this one is a feature request and the docs only promise C89 support.

Elsewhere in the docs, we require a C11 compiler to build CPython.

https://docs.python.org/3/using/configure.html

---

A larger discussion should be had on modernizing datetime and fully supporting C99 (ideally newer) time.h format tokens.

Adding a single additional format string would not be useful (it'd be better to add all C99 formats in this case).

What are the other C99 formats? Links to docs/specs would help.

---

but did find this now closed PR [1] and its parent issue [2] to be substantially different and alarming enough (e.g., a discussion of "making %F useful for nanoseconds") to raise this one (for a larger modernization project).

The rejection (#100929 (comment)):

I think the format you specified is already something you can parse with fromisoformat. Obviously this feature is more general than that, but if the vast majority of the time the person is trying to solve the problem of possibly-truncated ISO formatted datetime strings (as has been the case in previous iterations of this issue), then I think we can just leave it with fromisoformat for those use cases, and try-except blocks for the rare exceptions.

@jyalim Is your use case different, and why would it warrant the change this time instead of using fromisoformat?

[picnixz]

Requiring a C11 compiler is not the same as exposing the same functionalities. For instance we do not provide all C11 math functions but only provide C99 (and not all!).

[StanFromIreland]

What are the other C99 formats? Links to docs/specs would help.

See section 7.23.3.5 of ISO 9899:1999.

Requiring a C11 compiler is not the same as exposing the same functionalities.

Since we call strftime (with some minor preprocessing) we actually do expose the functionality.

[picnixz]

That's not because we call strftime that we need to expose all C11 functionalities supported by that function. The fact that we have an alternative that is fromisoformat() should be sufficient. Since fromisoformat() is also slightly different, having %F as well may be confusing since they would do slightly different things despite their names.

As asked on the other issue, is there a need for strict ISO parsing that cannot be achieved by fromisoformat()?

[StanFromIreland]

Discussed the state of the current table with Paul and we decided that I will update the table (once I relearn emacs🙃) to list all format codes as provided by C11, with an additional column that clearly states whether it is supported by strptime too, so as to not rely on the notes so much.

[jyalim]

@jyalim Is your use case different, and why would it warrant the change this time instead of using fromisoformat?

@hugovk, I appreciate your feedback! I think modern token support on its own is important for consistency and provides greater flexibility, especially when parsing non-ISO dates. As an example for %F, I've encountered the equivalent of %FT%TZ%z [e.g., 2025-10-28T13:57:30Z-07:00], which fromisoformat (correctly, per the standard) does not parse. This specific token saves the programmer time, adheres to ISO, and is jarring to find unsupported in Python's core strptime especially when its sister, non-C89 token, %T IS supported (and since %F is asymmetrically supported in strftime). Along that last parenthetical comment, a date -> str with %F currently CANNOT be converted back to a date with the same generating token!

import datetime
# this works
datetime.datetime.fromisoformat(datetime.datetime.now().strftime('%F'))
# this does not work! (ValueError: 'F' is a bad directive in format '%F')
datetime.datetime.strptime(datetime.datetime.now().strftime('%F'),'%F')