Make pandas.to_parquet handles partition columns better

[dclong]

Code Sample, a copy-pastable example if possible

Assuming frame is a pandas DataFrame which contains column cal_dt. If I want to write the DataFrame into a parquet partitioned by the column cal_dt, I have the following code without reading the doc carefully.

frame.to_parquet('partitioned_parquet', partition_cols='cal_dt')

Problem description

The above code raises an issue of "KeyError: 'c'", which is not clear enough to users.

Expected Output

Of course, I know the right way is to pass a list of columns to partition_cols (see the code below).

frame.to_parquet('partitioned_parquet', partition_cols=['cal_dt'])

However, as I mentioned that people will likely have the first example of code instead (expecting that passing a single column name would work) without reading the doc carefully. I think the method to_parquet should be enhanced to be either of the following.

1. Throws an exception with a clearer message saying that a list is required for partition_cols when a user passes a non-list object to it.
2. Support passing a single string to partition_cols in which it means to use that column as the partition column.
   Either way, the implementation is simple but it does improve user experience.

[TomAugspurger]

Does either parquet engine distinguish between a length-of-1 list partition_cols and a scalar partition_cols? If not, then option 2 seems fine.

[jorisvandenbossche]

Agreed the above is not a very nice user experience.

But it should maybe be the responsibility of the engines? (so report over there)

[jorisvandenbossche]

@dclong Interested in doing a PR for this?

[dclong]

@jorisvandenbossche Yes, this sounds like a very simple fix. I am very willing to submit a PR. However, I've never contributed a PR to pandas before. I will start reading the guidelines. It is greatly appreciated if you have additional tips on how to contributing.

[jorisvandenbossche]

The most difficult part is already OK: picking a good issue to tackle :)
And for the rest: if you have any questions about the workflow or the guide, feel free to ask (here or at the gitter channel https://gitter.im/pydata/pandas)

[ai006]

my team and I from the #PandasHack2019 in Bentonville were hoping to tackle the issue by implementing the 2nd option as well.