DEPR: Add warning for True for dropna of SeriesGroupBy.nth

Author: tnir

pandas/core/groupby.py

@@ -55,7 +55,7 @@
                                  compress_group_index, get_flattened_iterator,
                                  decons_obs_group_ids, get_indexer_dict)
 from pandas.util._decorators import (cache_readonly, Substitution,
-                                     Appender, make_signature)
+                                     Appender, make_signature, deprecate_kwarg)
 from pandas.io.formats.printing import pprint_thing
 from pandas.util._validators import validate_kwargs
 
@@ -1296,6 +1296,8 @@ def backfill(self, limit=None):
 
     @Substitution(name='groupby')
     @Appender(_doc_template)
+    @deprecate_kwarg(old_arg_name='dropna', new_arg_name='dropna',
+                     mapping={True: None})
     def nth(self, n, dropna=None):
         """
         Take the nth row from each group if n is an int, or a subset of rows

pandas/tests/groupby/test_nth.py

@@ -2,7 +2,10 @@
 import pandas as pd
 from pandas import DataFrame, MultiIndex, Index, Series, isna
 from pandas.compat import lrange
-from pandas.util.testing import assert_frame_equal, assert_series_equal
+from pandas.util.testing import (
+    assert_frame_equal,
+    assert_produces_warning,
+    assert_series_equal)
 
 from .common import MixIn
 
@@ -168,13 +171,6 @@ def test_nth(self):
         result = s.groupby(g, sort=False).nth(0, dropna='all')
         assert_series_equal(result, expected)
 
-        # doc example
-        df = DataFrame([[1, np.nan], [1, 4], [5, 6]], columns=['A', 'B'])
-        g = df.groupby('A')
-        result = g.B.nth(0, dropna=True)
-        expected = g.B.first()
-        assert_series_equal(result, expected)
-
         # test multiple nth values
         df = DataFrame([[1, np.nan], [1, 3], [1, 4], [5, 6], [5, 7]],
                        columns=['A', 'B'])
@@ -232,6 +228,17 @@ def test_nth_multi_index_as_expected(self):
                                          names=['A', 'B']))
         assert_frame_equal(result, expected)
 
+    def test_nth_dropna(self):
+        # PR XXXXX, related to issue 16442
+        # test nth with True for dropna produces DeprecationWarning
+        # old doc example
+        df = DataFrame([[1, np.nan], [1, 4], [5, 6]], columns=['A', 'B'])
+        g = df.groupby('A')
+        with assert_produces_warning(FutureWarning):
+            result = g.B.nth(0, dropna=True)
+        expected = g.B.first()
+        assert_series_equal(result, expected)
+
 
 def test_nth_empty():
     # GH 16064