DEPR: Deprecate cols in several functions

[jsexauer]

closes #6680 -- Deprecate cols in drop_duplicates() and duplicated() (rename to subset)
closes #6645 -- Deprecate cols in to_csv() and to_excel() (rename to columns)
releated to #6686
Related #5505 -- Deprecate cols and rows in pivot_table() and crosstab() (rename to columns and index)

Related #6581 -- Reminder to come back in 0.16, remove deprecation warnings, and use new arguments

[jreback]

maybe should refactor the code that does this cols deprecation check to a function (and also need to change the ones u did already, eg pivot and such)

maybe stick it in pandas.util.misc or something (their is a decorator deprecate already in pandas.util.decorators but not sure if that would work or maybe it would)

[jsexauer]

Made a new decorator that deprecates a keyword argument of a function and implemented on the 6 functions in question.

[jreback]

can you move these to the deprecations section

[jsexauer]

Thanks for catching the bone-headed overlook of not using the decorator on to_csv and to_excel

[jreback]

looks good

@jorisvandenbossche ?

[jorisvandenbossche]

There should be some wrapping of the function in order to keep its name and docstring.

[jreback]

you can use functools.wraps to propogate name/docstrings

[jorisvandenbossche]

I was trying this, but I first couldn't get it to work (with the double wrapper for providing the arguments, but now found where the wrap should come. It's like this:

from functools import wrap
...
def deprecate_kwarg(old_arg_name, new_arg_name):
    def _deprecate_kwarg(func):
        @wraps(func)                       # <-----
        def wrapper(*args, **kwargs):
            ...
            return func(*args, **kwargs)
        return wrapper
    return _deprecate_kwarg

[jreback]

maybe just assign directly, e.g func.__name__ = ....; func.__doc__ = ....

[jorisvandenbossche]

@jreback Is there a downside to using functools.wraps?

[jreback]

no....its more future proof...so ideally use it over manual assigning....but usually name/doc good enough

[jankatins]

wouldn't it make sense to add a version to the decorator, so that this information can be printed as well and maybe make this fail in case some env variable is present (TRAVIS) and pandas version is higher (automatic failures on version update :-) )

[jreback]

@JanSchulz why would you need a version in this - its already versioned by definition as its in master.

Even though we have created an issue to take this out for good (say in 0.16), that might get changed until its actually removed. Their are some very old deprecations thatreally do need to get taken out.

[jankatins]

I mean something like this: deprecate_kwarg(old_arg_name="old", new_arg_name="new", version="0.5") will output "old is deprecated, use new instead (old will be removed in version 0.5)" and tests using old will fail on travis if pd.version is higher than 0.5.

[jreback]

can't do it because what happens when that 0.5 changes to 0.6 (eg we didn't remove it when we said but later)

it's not always clear how long to deprecate and when to remove

in theory you are right but practically it's a problem

[jsexauer]

Added wraps decorator

[jreback]

merged via 599156f

thanks!