DOC: how to_datetime %S differs from strptime

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/dev/reference/api/pandas.to_datetime.html?highlight=to_datetime#pandas.to_datetime

Documentation problem

The documentation says that the formatting strings used by pandas.to_datetime are the same as datetime.strptime, other than the number of digits %f handles.

This is not quite true, there is another difference. pandas.to_datetime with %S (without %f) will capture microseconds. strptime will throw an error. (Which makes pandas.to_datetime more useful than strptime)

import pandas as pd
import datetime as dt
fmt = "%Y/%m/%d %H:%M:%S"
s= "2021/01/01 12:01:01.123"
assert pd.to_datetime(s, format=fmt).microsecond > 0
dt.datetime.strptime(s, fmt)

The second-last line passes, the last line throws ValueError: unconverted data remains: .123.

Suggested fix for documentation

Change:

Note that “%f” will parse all the way up to nanoseconds.

to:

Note that “%S” without “%f” will capture fractional seconds up to nanoseconds, Note that “%f” will parse all the way up to nanoseconds. “%S” without “%f” will capture all the way up to nanoseconds if present as decimal places, but will also handle the case where the number of seconds is an integer.

[mdavis-xyz]

Yes I think this issue is still open. That PR was closed as stale. I think the reviewers wanted examples included.

[MarcoGorelli]

Part of this needs reverting, https://github.com/pandas-dev/pandas/issues/49231