MAINT: Drop take_last kwarg from method signatures

Affected methods:

1) nlargest
2) nsmallest
3) duplicated
4) drop_duplicates

xref #10236, #10792, #10920.

Author: gfyoung <[email protected]>

Closes #15710 from gfyoung/create-last-kw-drop and squashes the following commits:

b416290 [gfyoung] MAINT: Drop take_last kwarg from method signatures

Author: gfyoung

asv_bench/benchmarks/series_methods.py

@@ -68,8 +68,8 @@ def setup(self):
         self.s4 = self.s3.astype('object')
 
     def time_series_nlargest1(self):
-        self.s1.nlargest(3, take_last=True)
-        self.s1.nlargest(3, take_last=False)
+        self.s1.nlargest(3, keep='last')
+        self.s1.nlargest(3, keep='first')
 
 
 class series_nlargest2(object):
@@ -83,8 +83,8 @@ def setup(self):
         self.s4 = self.s3.astype('object')
 
     def time_series_nlargest2(self):
-        self.s2.nlargest(3, take_last=True)
-        self.s2.nlargest(3, take_last=False)
+        self.s2.nlargest(3, keep='last')
+        self.s2.nlargest(3, keep='first')
 
 
 class series_nsmallest2(object):
@@ -98,8 +98,8 @@ def setup(self):
         self.s4 = self.s3.astype('object')
 
     def time_series_nsmallest2(self):
-        self.s2.nsmallest(3, take_last=True)
-        self.s2.nsmallest(3, take_last=False)
+        self.s2.nsmallest(3, keep='last')
+        self.s2.nsmallest(3, keep='first')
 
 
 class series_dropna_int64(object):

doc/source/whatsnew/v0.20.0.txt

@@ -769,6 +769,7 @@ Removal of prior version deprecations/changes
   in favor of ``iloc`` and ``iat`` as explained :ref:`here <whatsnew_0170.deprecations>` (:issue:`10711`).
 - The deprecated ``DataFrame.iterkv()`` has been removed in favor of ``DataFrame.iteritems()`` (:issue:`10711`)
 - The ``Categorical`` constructor has dropped the ``name`` parameter (:issue:`10632`)
+- The ``take_last`` parameter has been dropped from ``duplicated()``, ``drop_duplicates()``, ``nlargest()``, and ``nsmallest()`` methods (:issue:`10236`, :issue:`10792`, :issue:`10920`)
 
 .. _whatsnew_0200.performance:
 

pandas/core/base.py

@@ -1065,16 +1065,13 @@ def searchsorted(self, value, side='left', sorter=None):
             - ``first`` : Drop duplicates except for the first occurrence.
             - ``last`` : Drop duplicates except for the last occurrence.
             - False : Drop all duplicates.
-        take_last : deprecated
         %(inplace)s
 
         Returns
         -------
         deduplicated : %(klass)s
         """)
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     @Appender(_shared_docs['drop_duplicates'] % _indexops_doc_kwargs)
     def drop_duplicates(self, keep='first', inplace=False):
         inplace = validate_bool_kwarg(inplace, 'inplace')
@@ -1100,15 +1097,12 @@ def drop_duplicates(self, keep='first', inplace=False):
             - ``last`` : Mark duplicates as ``True`` except for the last
               occurrence.
             - False : Mark all duplicates as ``True``.
-        take_last : deprecated
 
         Returns
         -------
         duplicated : %(duplicated)s
         """)
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     @Appender(_shared_docs['duplicated'] % _indexops_doc_kwargs)
     def duplicated(self, keep='first'):
         from pandas.core.algorithms import duplicated

pandas/core/frame.py

@@ -77,8 +77,7 @@
                            OrderedDict, raise_with_traceback)
 from pandas import compat
 from pandas.compat.numpy import function as nv
-from pandas.util.decorators import (deprecate_kwarg, Appender,
-                                    Substitution)
+from pandas.util.decorators import Appender, Substitution
 from pandas.util.validators import validate_bool_kwarg
 
 from pandas.tseries.period import PeriodIndex
@@ -3169,8 +3168,6 @@ def dropna(self, axis=0, how='any', thresh=None, subset=None,
         else:
             return result
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     def drop_duplicates(self, subset=None, keep='first', inplace=False):
         """
         Return DataFrame with duplicate rows removed, optionally only
@@ -3185,7 +3182,6 @@ def drop_duplicates(self, subset=None, keep='first', inplace=False):
             - ``first`` : Drop duplicates except for the first occurrence.
             - ``last`` : Drop duplicates except for the last occurrence.
             - False : Drop all duplicates.
-        take_last : deprecated
         inplace : boolean, default False
             Whether to drop duplicates in place or to return a copy
 
@@ -3203,8 +3199,6 @@ def drop_duplicates(self, subset=None, keep='first', inplace=False):
         else:
             return self[-duplicated]
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     def duplicated(self, subset=None, keep='first'):
         """
         Return boolean Series denoting duplicate rows, optionally only
@@ -3221,7 +3215,6 @@ def duplicated(self, subset=None, keep='first'):
             - ``last`` : Mark duplicates as ``True`` except for the
               last occurrence.
             - False : Mark all duplicates as ``True``.
-        take_last : deprecated
 
         Returns
         -------

pandas/core/groupby.py

@@ -51,8 +51,8 @@
 from pandas.core.sorting import (get_group_index_sorter, get_group_index,
                                  compress_group_index, get_flattened_iterator,
                                  decons_obs_group_ids, get_indexer_dict)
-from pandas.util.decorators import (cache_readonly, Substitution, Appender,
-                                    make_signature, deprecate_kwarg)
+from pandas.util.decorators import (cache_readonly, Substitution,
+                                    Appender, make_signature)
 from pandas.formats.printing import pprint_thing
 from pandas.util.validators import validate_kwargs
 
@@ -94,12 +94,12 @@
     'corr', 'cov', 'diff',
 ]) | _plotting_methods
 
-_series_apply_whitelist = \
-    (_common_apply_whitelist - set(['boxplot'])) | \
-    frozenset(['dtype', 'unique'])
+_series_apply_whitelist = ((_common_apply_whitelist |
+                            {'nlargest', 'nsmallest'}) -
+                           {'boxplot'}) | frozenset(['dtype', 'unique'])
 
-_dataframe_apply_whitelist = \
-    _common_apply_whitelist | frozenset(['dtypes', 'corrwith'])
+_dataframe_apply_whitelist = (_common_apply_whitelist |
+                              frozenset(['dtypes', 'corrwith']))
 
 _cython_transforms = frozenset(['cumprod', 'cumsum', 'shift',
                                 'cummin', 'cummax'])
@@ -3025,20 +3025,6 @@ def nunique(self, dropna=True):
                       index=ri,
                       name=self.name)
 
-    @deprecate_kwarg('take_last', 'keep',
-                     mapping={True: 'last', False: 'first'})
-    @Appender(Series.nlargest.__doc__)
-    def nlargest(self, n=5, keep='first'):
-        # ToDo: When we remove deprecate_kwargs, we can remote these methods
-        # and include nlargest and nsmallest to _series_apply_whitelist
-        return self.apply(lambda x: x.nlargest(n=n, keep=keep))
-
-    @deprecate_kwarg('take_last', 'keep',
-                     mapping={True: 'last', False: 'first'})
-    @Appender(Series.nsmallest.__doc__)
-    def nsmallest(self, n=5, keep='first'):
-        return self.apply(lambda x: x.nsmallest(n=n, keep=keep))
-
     @Appender(Series.describe.__doc__)
     def describe(self, **kwargs):
         self._set_group_selection()

pandas/core/series.py

@@ -1211,14 +1211,10 @@ def unique(self):
             return result.asobject.values
         return result
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     @Appender(base._shared_docs['drop_duplicates'] % _shared_doc_kwargs)
     def drop_duplicates(self, keep='first', inplace=False):
         return super(Series, self).drop_duplicates(keep=keep, inplace=inplace)
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     @Appender(base._shared_docs['duplicated'] % _shared_doc_kwargs)
     def duplicated(self, keep='first'):
         return super(Series, self).duplicated(keep=keep)
@@ -1888,8 +1884,6 @@ def argsort(self, axis=0, kind='quicksort', order=None):
                 np.argsort(values, kind=kind), index=self.index,
                 dtype='int64').__finalize__(self)
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     def nlargest(self, n=5, keep='first'):
         """Return the largest `n` elements.
 
@@ -1901,7 +1895,6 @@ def nlargest(self, n=5, keep='first'):
             Where there are duplicate values:
             - ``first`` : take the first occurrence.
             - ``last`` : take the last occurrence.
-        take_last : deprecated
 
         Returns
         -------
@@ -1938,8 +1931,6 @@ def nlargest(self, n=5, keep='first'):
         return algorithms.select_n_series(self, n=n, keep=keep,
                                           method='nlargest')
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     def nsmallest(self, n=5, keep='first'):
         """Return the smallest `n` elements.
 
@@ -1951,7 +1942,6 @@ def nsmallest(self, n=5, keep='first'):
             Where there are duplicate values:
             - ``first`` : take the first occurrence.
             - ``last`` : take the last occurrence.
-        take_last : deprecated
 
         Returns
         -------

pandas/indexes/base.py

@@ -3500,14 +3500,10 @@ def unique(self):
         result = super(Index, self).unique()
         return self._shallow_copy(result)
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     @Appender(base._shared_docs['drop_duplicates'] % _index_doc_kwargs)
     def drop_duplicates(self, keep='first'):
         return super(Index, self).drop_duplicates(keep=keep)
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     @Appender(base._shared_docs['duplicated'] % _index_doc_kwargs)
     def duplicated(self, keep='first'):
         return super(Index, self).duplicated(keep=keep)

pandas/indexes/category.py

@@ -11,8 +11,7 @@
 from pandas.types.missing import array_equivalent
 
 
-from pandas.util.decorators import (Appender, cache_readonly,
-                                    deprecate_kwarg)
+from pandas.util.decorators import Appender, cache_readonly
 from pandas.core.config import get_option
 from pandas.indexes.base import Index, _index_shared_docs
 import pandas.core.base as base
@@ -301,8 +300,6 @@ def unique(self):
         return self._shallow_copy(result, categories=result.categories,
                                   ordered=result.ordered)
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     @Appender(base._shared_docs['duplicated'] % _index_doc_kwargs)
     def duplicated(self, keep='first'):
         from pandas._libs.hashtable import duplicated_int64

pandas/indexes/multi.py

@@ -755,8 +755,6 @@ def f(k, stringify):
                      for k, stringify in zip(key, self._have_mixed_levels)])
         return hash_tuples(key)
 
-    @deprecate_kwarg('take_last', 'keep', mapping={True: 'last',
-                                                   False: 'first'})
     @Appender(base._shared_docs['duplicated'] % _index_doc_kwargs)
     def duplicated(self, keep='first'):
         from pandas.core.sorting import get_group_index