API: Have pd.pivot mirror pivot instead of pivot_simple

[mroeschke]

To pivot, there's currently:

pd.pivot_table / df.pivot_table

pandas/pandas/core/reshape/pivot.py

Line 28 in d30c4a0

def pivot_table(data, values=None, index=None, columns=None, aggfunc='mean',

df.pivot

pandas/pandas/core/reshape/reshape.py

Line 386 in d30c4a0

def pivot(self, index=None, columns=None, values=None):

pivot_simple (Importable at the top level as pd.pivot)

pandas/pandas/core/reshape/reshape.py

Line 411 in d30c4a0

def pivot_simple(index, columns, values):

I'm not sure why pd.pivot currently doesn't mirror df.pivot like how pd.pivot_table mirrors df.pivot_table, but it would clearer if these were in sync.

[gfyoung]

cc @jreback

[mroeschke]

There's also a quote in reshaping.rst that doesn't seem to be true:

To reshape the data into this form, we use the DataFrame.pivot() method (also implemented as a top level function pivot())

but pivot() that is referred above uses the pivot_simple implementation instead of the pivot implementation.

[jorisvandenbossche]

Reopening this one instead of opening a new issue.

So PR #22209 changed the top-level pd.pivot to match the behaviour of DataFrame.pivot. This is however a breaking change, so I think we should discuss in more detail if we want this, and if so, at least deprecate the current behaviour.

One option is to deprecate the current behaviour (and from the passed values, I think we should be able to infer if the old or new behaviour is wanted).

But, we maybe first need to discuss if we want to fully deprecate the old behaviour.

[TomAugspurger]

Anyone have thoughts here? Is this blocking for 0.24.0?

[jreback]

not blocking

[mroeschke]

Closing as this change has persisted since 0.24.0 and no complaints so far.