DOC: read_excel and read_csv have a new date_format parameter, but the format of this is not documented

[johnmreynolds]

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.read_csv.html
https://pandas.pydata.org/docs/dev/reference/api/pandas.read_excel.html

Documentation problem

In pandas 2.0 various data read functions have a new date_format parameter.

However, the documentation doesn't actually say what the format of this is.

I'm assuming it's supposed to be a strftime format, but it doesn't say.

(And separately, my testing suggests it doesn't work - but that's probably due to #44284 )

Suggested fix for documentation

Specify in the documentation what the format of the date_format parameter is.

[asishm-wk]

Thanks for the report.
The linked issue is unrelated - that is for writing excel files only.

And separately, my testing suggests it doesn't work

Can you provide a reproducible example?

[johnmreynolds]

Ah, so it turns out that my issue with the functionality was that parse_dates=True doesn't do what I expected. The behavior does match the documentation, it was just a bit of a surprise. Passing the name(s) of the date columns into parse_dates does seem to work.

[johnmreynolds]

And indeed, the format of date_format does seem to be strftime, so the original issue can be summarized as "date_format parameter documentation should say that it uses strftime format"

[johnmreynolds]

It also seems to support "ISO8601" and "mixed" like to_datetime. So it could possibly just reference the format in that. It does already link to to_datetime, but in the context of an alternative to use.

[lithomas1]

Thanks for reporting this issue.

I had a look, and I think you're right about it being a strftime format (I think it should be the same as foramt in to_datetime but I don't use the date stuff in pandas a lot).

Would you like to raise a pull request to document this?

[rsm-23]

take

[brendan-m-murphy]

Any chance this could be sign-posted in the current 2.12 docs?