API: read_csv,from_csv/to_csv keyword consistency

[rmorgans]

method naming consistency issue #577

• to_csv uses line_terminator and read_csv uses lineterminator
• compression kw ENH: DataFrame.to_csv support for "compression='gzip'" #7615 (ENH: added compression kw to to_csv GH7615 #11219)
• sep/delimiter read_csv/to_csv sep/delimiter inconsistency #7662
• from_csv differs from read_csv DataFrame.from_csv undocumented behavior of index_col #9556 (DOC: clarify purpose of DataFrame.from_csv (GH4191) #10163)
• decimal Add support of 'decimal' option to Series.to_csv and Dataframe.to_csv #8448 (671c4b3)

[jreback]

@rmorgans yep. I created a master issue for things that I recall, but I am sure there are some more. Would you like to do a full comparison of the read_csv/to_csv options to see if there any other conventions that are inconsisten (and include from_csv) here as well.

Ideally we would like to make most consistent name work and deprecate the others. Would you like to do a pull-request?

[Dobatymo]

all other issues referenced here are closed.
only

to_csv uses line_terminator and read_csv uses lineterminator

still applies.

[jreback]

@Dobatymo updated. would you like to do a PR to deprecate line_terminator in .to_csv?

[Dobatymo]

Not sure how to deprecate something. Should I add lineterminator and add to the docs that line_terminator is deprecated? Or directly delete it?

[TomAugspurger]

Not sure how to deprecate something

If you look in pandas/utils/_decorators.py you'll see a deprecate_kwarg. You can use that to and it'll emit a warning if the incorrect version is passed.

We'll also want to

1. update all the docs and tests to use lineterminator
2. Add a new tests that uses line_terminator and checks that the deprecation warning was emitted
3. Add a release note to whatsnew/v0.21.1.txt (@jreback we're OK with adding deprecation warnings in point releases, correct?)

[jorisvandenbossche]

Add a release note to whatsnew/v0.21.1.txt (@jreback we're OK with adding deprecation warnings in point releases, correct?)

Let's keep that for 0.22.0. Introducing deprecation warnings is somehow changing behaviour in the sense that it gives annoying warnings one needs to change code for to get rid of them. I would keep 0.21.1 for essential bug fixes.

But apart from that, actual question: is there a reason we would prefer lineterminator over line_terminator ? (I find the latter more readable)

[jreback]

most 2 word options are not _ separates in read_csv and we chose previously not to change them
so lineterminator is consistent (agree it’s not as nice)

no depreciations in point release so this for 0.22

[jorisvandenbossche]

most 2 word options are not _ separates in read_csv and we chose previously not to change them
so lineterminator is consistent (agree it’s not as nice)

That is not completely true (I mean we have both), eg: index_col, mangle_dupe_cols, true_values, na_values, keep_default_na, skip_blank_lines, parse_dates, infer_datetime_format, ... etc all use the _ naming scheme.
It seems that it are mainly the keyword inherited from the stdlib csv module that are not with underscores. And, lineterminator is one of those. So in read_csv we followed the csv module, in to_csv not.

Personally I find that not enough reason to choose for lineterminator in to_csv.
Another option is also to document it as line_terminator but still accept lineterminator in read_csv for compatibility with csv dialects.

[jreback]

yes I think we have an issue about accepting both. personally I would just do that, its really no big deal to do that.

[GGordonGordon]

@jreback / @jorisvandenbossche - I was thinking of picking this up and working on it but wanted to clarify is the objective for this issue to still deprecate line_terminator in to_csv and replace it with lineterminator to mirror read_csv or is the objective to allow both parameters in both locations?

[mangecoeur]

Bumping/adding to this: it would be good to have symmetry in the header keyword, when writing you set header=False to skip the header but when reading you set header=None (header=False is an error).

df.to_csv(header=False)

#Currently allowed
df = pd.read_csv(header=None)

#Currently an error
df = pd.read_csv(header=False)

[pv8473h12]

If no-one else is working on this, I'd like to give it a go.

[jbrockmendel]

#35399 didn't achieve any consensus. In isolation I like line_terminator better, but for consistency with stdlib csv think we should standardize on lineterminator.

[phofl]

closed by #45302