Allow deprecate_kwarg to transform arguments
State: closed

This will allow deprecated kwargs to be transformed before being passed to a function.  For example, in #7963, one could write

``` python

@deprecate_kwarg(old_arg_name='infer_dst', new_arg_name='ambiguous',
                 mapping={True: 'infer', False: 'raise'})
def tz_localize(self, tz, ambiguous=None):
    ...

```

Open issues:
- should we test for a bad mapping at creation time?  (in this PR: yes)
- how much error checking should we do?  (in this PR: pass args unrecognized by a mapping through unchanged; assume a function will do its own error handling)
- should we support both mappings and callables?  (in this PR: yes)
- if so, how should we recognize mappings?  (in this PR: existence of a `get` method)


Labels:
name: Internals
description: Related to non-user accessible pandas implementation

Comments:
seems fine, can you squash

@ischwabacher pls squash this

@jorisvandenbossche ?

+1

@ischwabacher pls update the testsing wiki as well: https://github.com/pydata/pandas/wiki/Testing

I've been having free time in such short blocks lately that the bottleneck here has been, embarrassingly enough, getting a working python3 installation on my laptop.  Pip is being a recalcitrant pipsqueak.  I would like to get this done in the next 24 hours, but I'm decreasingly convinced that's going to happen.

Hrm... Somehow I get the feeling that this rebase was not as clean as intended.  Also I do not think that these changes warrant changes to that wiki.  Though I wish I'd found the wiki sooner.  Advice?

Yes, indeed. For only rebasing, this should normally work:

```
git fetch upstream
git rebase upstream/master
```

BTW, I am enjoying `conda` a lot, almost no more `pip` for me.

wiki needs to mention how to deprecate a kwargs 

@jreback Got it.

@jorisvandenbossche I don't see how that creates a branch that's pushable to `origin/patch-2`, since that branch is way behind `upstream/master`.

But you have to do those commands 'from' that branch, so, if 'patch-2' is your feature branch:

```
git checkout patch-2
git fetch upstream
git rebase upstream/master
git push -f origin patch-2
```

This will update your local 'patch-2' branch to be up to date with upstream master, and if you push this to the remote origin (your fork) version, then that version and automaticall the PR will be up to date. But you possibly have to do a force push (`-f`)

Yup, it was the force push that had eluded me.  Instead I had merged in `origin/master` and created a rebase conflict.  Lesson learned!

@jreback Here's the text I would add to the wiki, but I still don't see a good place to put it.  Maybe in a section immediately following [Testing for Warnings](https://github.com/pydata/pandas/wiki/Testing#testing-for-warnings)?

> ### Deprecating keyword arguments
> 
> If your PR renames a keyword argument or adds a new kwarg to a function such that the functionality of an existing kwarg is superseded, the old kwarg should be removed from the function's API and replaced with the `@deprecate_kwarg` decorator, which will convert the old kwarg into the new one with a `DeprecationWarning` at call time.  When you do this, it's a good idea to add a test to make sure that the warning is being generated and arguments are being converted properly, especially if you passed a mapping to `deprecate_kwarg`.

In here (just add a sub-section in the For Devvelopers): https://github.com/pydata/pandas/wiki

mainly this is to point people to when they need to do something (e.g. deprecate a kwarg!)

[Wiki updated](/pydata/pandas/wiki/A-quick-overview-of-pandas.util), though maybe that isn't the most obvious place for people to look.

@ischwabacher wiki update is good. Pls add to it! (other sections!)