-
Notifications
You must be signed in to change notification settings - Fork 0
A quick overview of pandas.util
This page will document useful dev tools in pandas.util. TODO since I don't know much about these tools yet.
pandas.util.decorators contains a number of decorators that generally make everyone's life easier. TODO.
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(old_arg_name, new_arg_name) decorator, which will convert the old kwarg into the new one with a DeprecationWarning at call time.
If the values passed to the old keyword don't match the arguments to the new one, you can use the mapping keyword argument to deprecate_keyword to translate. For instance, suppose you want to refactor this:
def frob(thingum, do_foo=True):
"""
Frob the thingum.
Parameters
----------
do_foo : bool
Use method 'foo' (default). Otherwise use method 'baz'.
"""
...into this:
def frob(thingum, do='bar'):
"""
Frob the thingum.
Parameters
----------
do : ['foo', 'bar', 'baz']
Method to use. Default is 'bar'.
"""
...This is a backward-incompatible change, but it can be made compatible (well, almost— note the new default!) with a single line:
@deprecate_kwarg('do_foo', 'do', mapping={True: 'foo', False: 'baz'})
def frob(thingum, do='bar'):
"""
Frob the thingum.
Parameters
----------
do : ['foo', 'bar', 'baz']
Method to use. Default is 'bar'.
"""
...Be aware that when passing a dict to mapping, missing values will pass through unchanged. If you need to do something more complicated, or your inputs aren't hashable, you can pass a callable to mapping instead. In this case you will need / be able to do your own input validation.
When you deprecate a keyword argument, 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.