ENH: provide "inplace" argument to set_axis()
State: closed

 - [x] closes #14636
 - [x] tests added / passed
 - [x] passes ``git diff master -u -- "*.py" | flake8 --diff``
 - [x] whatsnew entry

This completes what was attempted in #14656 with tests and docstring.

In principle, ``set_axis`` could be mentioned somewhere in the docs (``set_index`` [is](http://pandas.pydata.org/pandas-docs/stable/indexing.html#set-an-index))... but I'm dubious because the API is horrible and inconsistent, in particular with ``Series``, where it obliges the user to do ``s.set_axis(0, [...])``. In other words, while I tended to agree with [the suggestion](https://github.com/pandas-dev/pandas/pull/15104#issuecomment-272319791) that once ``.set_axis`` supports ``inplace=False``, we wouldn't need any ``.relabel()``, now that I see how it looks, I changed my mind (this is not the best place to discuss this, just explaining why I'm against "publicizing" ``set_axis`` too much).

Notice that in order to alleviate the problem, I changed the signature: ``axis`` and ``labels`` are now named parameters, so that one can do ``s.set_axis(labels=[...])``. I admit the utility of this is debatable.

Labels:
name: Enhancement
name: Indexing
description: Related to indexing on series/frames, not to indexes themselves
name: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=h1) Report
> Merging [#16994](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/0bd871fb9634e8b73efcc1aeabb93961fbc43d53?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/16994/graphs/tree.svg?token=eZ4WkYLtcO&width=650&src=pr&height=150)](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #16994      +/-   ##
==========================================
- Coverage   90.99%   90.97%   -0.02%     
==========================================
  Files         161      161              
  Lines       49290    49299       +9     
==========================================
  Hits        44851    44851              
- Misses       4439     4448       +9
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.75% <100%> (ø)` | :arrow_up: |
| #single | `40.19% <27.27%> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `92.33% <100%> (+0.03%)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.76% <0%> (-0.1%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=footer). Last update [0bd871f...02c370f](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=h1) Report
> Merging [#16994](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/811bcbcf4daf6a1118eb898e4e55320c68ec5159?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/16994/graphs/tree.svg?width=650&height=150&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #16994      +/-   ##
==========================================
- Coverage   91.02%   91.01%   -0.02%     
==========================================
  Files         161      161              
  Lines       49351    49363      +12     
==========================================
+ Hits        44924    44927       +3     
- Misses       4427     4436       +9
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `88.78% <100%> (ø)` | :arrow_up: |
| #single | `40.25% <15%> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/groupby.py](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS5weQ==) | `92.07% <100%> (ø)` | :arrow_up: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `92.05% <100%> (+0.05%)` | :arrow_up: |
| [pandas/core/reshape/pivot.py](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS9waXZvdC5weQ==) | `95.18% <100%> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <0%> (-58.34%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.75% <0%> (-0.1%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=footer). Last update [811bcbc...8fb9d0f](https://codecov.io/gh/pandas-dev/pandas/pull/16994?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

> We could in principle switch the order of the parameters, e.g.

Aha, right! Would I emit a ``DeprecationWarning`` with the old signature?
> Aha, right! Would I emit a DeprecationWarning with the old signature?

``FutureWarning``
Hello @toobaz! Thanks for updating the PR.











Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on July 23, 2017 at 20:58 Hours UTC
Should I document the signature change in the "Other API Changes" section of the whatsnew (despite the old version still being supported)?
> Should I document the signature change in the "Other API Changes" section of the whatsnew (despite the old version still being supported)?

Yes, you should.  Users might pass in these arguments positionally, so this signature change would break their code unless they were informed.
> Users might pass in these arguments positionally, so this signature change would break their code unless they were informed.

We don't break anything (for now). This is precisely why I'm asking.
> We don't break anything (for now). This is precisely why I'm asking. 

True, but we still should let people know because there are many people who use the library, and we have no idea whose code we would break.
> True, but we still should let people know because there are many people who use the library, and we have no idea whose code we would break.

The number of users is not a measure of the quality of refactoring... the question is just "should we mention an API change despite it _not_ breaking anything? Or should we mention it only in the future, when the compatibility mode is removed?"

You're welcome to suggest a sentence.
> the question is just "should we mention an API change despite it not breaking anything?

You should mention it now because you changed the signature by switching the position of the arguments (that's all you need to mention that it's a signature change).  That's going to break anyone's code whose function calls use positional arguments.
> you changed the signature by switching the position of the arguments

Maybe I see the misunderstanding: have you actually seen [the code](https://github.com/pandas-dev/pandas/pull/16994/files#diff-03b380f521c43cf003207b0711bac67fR534), [the tests](https://github.com/pandas-dev/pandas/pull/16994/files#diff-94d3a90081235f45a32e3f794ed69604R266) or the [discussion above](https://github.com/pandas-dev/pandas/pull/16994#pullrequestreview-50478441)?
@toobaz : I have in fact, and my point still stands.  You may have added deprecation warnings, but you should still mention the change as an API change because the new signature is the recommended way to pass in arguments.
> the new signature is the recommended way

Great, now we are on the same page. Will try to add a sentence.
> test with axis ='index' and axis='columns' (should work)

Already there (see lines 923-924)
> If this is going to complement remove the need for .relabel

Despite the new signature, I'm not 100% convinced. Can we wait for a bit more [discussion](https://github.com/pandas-dev/pandas/issues/14829#issuecomment-315785238)? I will add there a summary of pros and cons and, once a decision is made, take care of the docs you mention.
@jreback Some change requests still show up, but I should have solved them all in the last rebase.

(except the [additional docs](https://github.com/pandas-dev/pandas/pull/16994#pullrequestreview-50774738), for which I will wait #14829 and then provide another PR)
> minor comment. pls add to api.rst as well where appropriate.

Done for ``Series``, was already present for ``DataFrame``.
thanks!