DOC: Document that passing date_format=... to read_csv auto-enables parse_dates

[dlukes]

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#pandas-read-csv

Documentation problem

Passing a date_format argument to read_csv is enough to trigger datetime parsing, i.e. parse_dates=True is not needed:

import io
import pandas as pd
csv = io.StringIO("foo,bar\n2023-01-01,0\n2023-01-02,1\n2023-01-03,2")
df = pd.read_csv(csv, index_col="foo", date_format="%Y-%m-%d")
print(df.index)

Output:

DatetimeIndex(['2023-01-01', '2023-01-02', '2023-01-03'], dtype='datetime64[ns]', name='foo', freq=None)

This makes sense as a shortcut, but it would be nice to document this behavior, so that users know that it's intentional.

Suggested fix for documentation

The documentation for both the parse_dates and date_format kwargs to read_csv should mention that when parse_dates is not specified but date_format is, dates will be parsed.

[jfadia]

take

[jfadia]

If I've understood this correctly:

• parse_dates is automatically being set to True here
• Assuming that date_parser has not been passed in and date_format has been passed in, it looks like the condition would evaluate to False, thereby setting kwds["parse_dates"] = True
• However, if date_parser has been passed in along with date_format, we would still set kwds["parse_dates"] = False so the docs would have to account for this case
• If date_parser has been passed and parse_dates has not been set to True, it will still set kwds["parse_dates"] = True

I believe that it makes most sense to make this change here. I'll add something like "Automatically set to True if date_format or date_parser has been passed.".

[dlukes]

However, if date_parser has been passed in along with date_format, we would still set kwds["parse_dates"] = False so the docs would have to account for this case

Strictly speaking, I don't think this is the case -- translating the code you linked to pseudocode:

if parse_dates has its default value:
    if both date_parser and date_format have their default values:
        parse_dates = False
    otherwise (= if either date_parser or date_format has been set):
        parse_dates = True

But your PR looks fine, since you said "date_format or date_parser", not "date_format xor date_parser" :)

[jfadia]

However, if date_parser has been passed in along with date_format, we would still set kwds["parse_dates"] = False so the docs would have to account for this case

Strictly speaking, I don't think this is the case -- translating the code you linked to pseudocode:

if parse_dates has its default value:
    if both date_parser and date_format have their default values:
        parse_dates = False
    otherwise (= if either date_parser or date_format has been set):
        parse_dates = True

But your PR looks fine, since you said "date_format or date_parser", not "date_format xor date_parser" :)

Ah yes good catch. Thanks :)