Same parameter name for specifying column names in pd.read_csv and pd.DataFrame

[regstrtn]

The two most common ways of creating a new dataframe use different parameters for taking a list of column names as input.
In pd.read_csv, the syntax is:
pandas.read_csv(filepath, sep=',', delimiter=None, header='infer', names=None)

In pd.DataFrame, the syntax is:
pandas.DataFrame(data=None, index=None, columns=None)

And then again, in df.to_csv, we use the name columns.
df.to_csv(self, path_or_buf=None, sep=', ', na_rep='', float_format=None, columns=None)

Can they both be changed to columns?

[rushabh-v]

Should I go with changing the parameter "names" to "columns" in pandas.read_csv @jbrockmendel ?

[jbrockmendel]

@WillAyd any ides on this?

[WillAyd]

Hmm I think reasonable. @datapythonista maybe has thoughts

[datapythonista]

I'm always confused myself about those parameters, so this sounds good in general. But this will break a lot of code, even more if the one we change is the read_csv one.

I don't have a strong opinion, but I probably wouldn't make this change at this point, and wait until some bigger refactoring happens. Or after 1.0, so there is time for users to address the deprecation warning somehow knowing when the code will break (in 2.0).

Also if we make the IO adapters more like plugins, may be we can implement this in a parallel csv module, so users can just use the new one when they feel ready to it, and they see value in the transition.

As I said, not a strong opinion, and not opposed to change this if people is happy, but I think this can be the backwards compatibility change we do in pandas until now, and it's probably worth to think well on the strategy if we move forward.

[regstrtn]

Agree with the code breaking part. This will break a lot of code.
I am not familiar with the design guidelines in pandas, but could we support both parameters - name and columns in pd.read_csv?

[datapythonista]

It makes sense to me to rename the names in read_csv to columns, keep names as an alias, and may be in the future start to raise a deprecation warning.

@pandas-dev/pandas-core what do you think?

[gfyoung]

If we're planning to do this later down the road, IMO the better question is: can we improve upon these names? columns and names both don't fully convey the semantic of "column names".

I would actually suggest that we rename across the board to something like colnames.

[jorisvandenbossche]

There are some semantic differences between names in read_csv and columns in DataFrame / to_csv, though.

The names keyword in read_csv is only about giving names to the columns you read. While in DataFrame, it is also used to select columns (if your data already has names), and in to_csv it is only used to select columns, not to specify the names to use in the csv file. While in read_csv, there is also usecols to select columns.

So in that sense I agree with @gfyoung that also "columns" doesn't fully convey the meaning.

For the rest, I doubt it is worth breaking a lot of peoples code for such a rename. So if we want to do something, I would also do it (or at least start) with an alias. But also aliases increase possibilities and thus potential user confusion ..

[datapythonista]

+1. col_names or column_names would probably be my first preference, but in any case, sounds good.

[jorisvandenbossche]

When starting fresh, I would also vote for column_names I think. But for me the question is then: if it doesn't make it consistent with the other keyword names in DataFrame and to_csv (which was the original reason to start this discussion), is it worth renaming names to column_names ?

(in itself I find column_names certainly clearer than names)

[gfyoung]

@jorisvandenbossche : You bring up a good point regarding the difference in how this column (names) parameter is used across those three functions. It does seem that part of the confusion stemmed from having the same variable name used for two of the functions.

I would also be open then to renaming all of the parameters so that we convey they're about column names, but how they're used is slightly different between functions to indicate their use for selecting vs. labeling, for example.