API, DEPR: Raise and Deprecate Reshape for Pandas Objects
State: closed

`reshape` largely exists for compat reasons with `numpy` but in the interests of moving away from that, this PR will cause objects like `Series`, `Index`, and `Categorical` to deprecate OR raise when such a method is called.


Labels:
name: Compat
description: pandas objects compatability with Numpy or Python functions

Comments:
need these types of checks for Index as well. might as well combine the checks for Categorical,Index,Series (e.g. make a method to do it in core/base)

This is definitely a good idea :+1: 

had a glance. don't think you are handling `(-2, -1)`?

<strike>@jreback: Sure thing</strike>

@kawochen : Yikes, good catch.  Will fix.

@jreback : Actually, on second thought:

1) `Index` has no `reshape` method --> but is this PR the right place to add such a method (is it really necessary even?)

2) `Series` may not need such checks IMO because it passes `new_shape` to its `_values` attribute for reshaping.  AFAICT that `_values` attribute is either `ndarray` (or sub-class) OR `Categorical`.  Seems like duplicate work to have it validate in `Series` and then have to validate again in `_values`.  Thoughts?

`Index` should have one (that should just raise), as will `Series` in the next release. So this is just a bandaid. `Categorical` should raise as well, its an unsupported method.

1) The raising should be for a separate PR, right?
2) My point was that I saw no reason to perform validation twice given what `_values` can be.  In light of your first point, I do agree that this is only a band-aid at best.

see my point above

Ah, okay, I see.  Let them all raise then.  Should be relatively straightforward.

@gfyoung but `Series` you can't change now as its technically an API change. however, would be ok with deprecating it now.

Shouldn't we do the same with `Categorical` then?

yes, didn't realize that `.reshape` was already defined.

Alrighty, so I'll deprecate for both `Series` and `Categorical` and add a method for `Index` that raises.

## [Current coverage](https://codecov.io/gh/pydata/pandas/pull/13012?src=pr) is **84.38%**

> Merging [#13012](https://codecov.io/gh/pydata/pandas/pull/13012?src=pr) into [master](https://codecov.io/gh/pydata/pandas/branch/master?src=pr) will increase coverage by **<.01%**

``` diff
@@             master     #13012   diff @@
==========================================
  Files           142        142          
  Lines         51225      51235    +10   
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
+ Hits          43225      43234     +9   
- Misses         8000       8001     +1   
  Partials          0          0          
```

> Powered by [Codecov](https://codecov.io?src=pr). Last updated by [20de266...3ad161d](https://codecov.io/gh/pydata/pandas/compare/20de2661c8eff66e465248cbe28062eae0e0e3bb...3ad161df208b4784d8af582686623d74dbf78c09?src=pr)

@jreback : I've added deprecation and raising behaviour for `Series`, `Index`, and `Categorical`.  Travis gives a green light, so this is ready to merge if there is nothing else.

let's do this in 0.19.0

I pushed a v0.19.0 whatsnew (its not visible on doc-build), but there.

Thanks for letting me know!  Moved `whatsnew` comments to that doc.

@gfyoung Master is now targeted for 0.19.0? Can you rebase this (and move the whatsnew notes to the correct file)?

@jreback , @jorisvandenbossche : rebased onto `master` and Travis is happy.  Ready to merge if there are no other concerns.

@jreback : Made the requested changes, and Travis is still happy.  Ready to merge if there are no other concerns.

needs a rebase; couple of minor doc fixes. ping when green. (also make sure that we are not triggering the warnign in the tests at all), e.g. run the tests and see if any warnings pop up (if they do then you need to fix the test code). 

@jreback What is the reason of adding a `Index.reshape` that raises? That seems unnecessary to me (and only adds to the list of Index methods).

For people using `Series.reshape` (not sure why they would do it, but probably it is used in the wild), is `Series.values.reshape` the alternative they should use instead? 
If so, maybe add to the depr message?

@jorisvandenbossche we dont technically need this on `Index` as the idea is to raise on `Series/Categorical` in the future. (it _should_ have been added originally to `Index`). 

@jreback , @jorisvandenbossche : Made requested doc changes (no need to run Travis on those, hence the `[ci skip]`), so ready to merge if there are no other concerns.

@gfyoung See my comment from above: https://github.com/pydata/pandas/pull/13012#issuecomment-231687576

@jorisvandenbossche: Ah whoops, good point. Will do.

lgtm (minor doc comments). will need a rebase after #13147

@jreback : Made the requested doc changes as well as rebased, and Travis is still passing.  Ready to merge if there are no other concerns.

thanks @gfyoung