CLN: Deprecate Index.summary (GH18217) (#20028)

Author: GGordonGordon

doc/source/whatsnew/v0.23.0.txt

@@ -738,6 +738,7 @@ Deprecations
 - :attr:`Timestamp.weekday_name`, :attr:`DatetimeIndex.weekday_name`, and :attr:`Series.dt.weekday_name` are deprecated in favor of :meth:`Timestamp.day_name`, :meth:`DatetimeIndex.day_name`, and :meth:`Series.dt.day_name` (:issue:`12806`)
 
 - ``pandas.tseries.plotting.tsplot`` is deprecated. Use :func:`Series.plot` instead (:issue:`18627`)
+- ``Index.summary()`` is deprecated and will be removed in a future version (:issue:`18217`)
 
 .. _whatsnew_0230.prior_deprecations:
 

pandas/core/frame.py

@@ -2005,7 +2005,7 @@ def info(self, verbose=None, buf=None, max_cols=None, memory_usage=None,
         lines = []
 
         lines.append(str(type(self)))
-        lines.append(self.index.summary())
+        lines.append(self.index._summary())
 
         if len(self.columns) == 0:
             lines.append('Empty %s' % type(self).__name__)

pandas/core/indexes/base.py

@@ -1384,7 +1384,19 @@ def _has_complex_internals(self):
         # to disable groupby tricks in MultiIndex
         return False
 
-    def summary(self, name=None):
+    def _summary(self, name=None):
+        """
+        Return a summarized representation
+
+        Parameters
+        ----------
+        name : str
+            name to use in the summary representation
+
+        Returns
+        -------
+        String with a summarized representation of the index
+        """
         if len(self) > 0:
             head = self[0]
             if (hasattr(head, 'format') and
@@ -1403,6 +1415,15 @@ def summary(self, name=None):
             name = type(self).__name__
         return '%s: %s entries%s' % (name, len(self), index_summary)
 
+    def summary(self, name=None):
+        """
+        Return a summarized representation
+        .. deprecated:: 0.23.0
+        """
+        warnings.warn("'summary' is deprecated and will be removed in a "
+                      "future version.", FutureWarning, stacklevel=2)
+        return self._summary(name)
+
     def _mpl_repr(self):
         # how to represent ourselves to matplotlib
         return self.values

pandas/core/indexes/datetimelike.py

@@ -1049,9 +1049,18 @@ def where(self, cond, other=None):
         return self._shallow_copy(result,
                                   **self._get_attributes_dict())
 
-    def summary(self, name=None):
+    def _summary(self, name=None):
         """
-        return a summarized representation
+        Return a summarized representation
+
+        Parameters
+        ----------
+        name : str
+            name to use in the summary representation
+
+        Returns
+        -------
+        String with a summarized representation of the index
         """
         formatter = self._formatter_func
         if len(self) > 0:

pandas/tests/indexes/datetimes/test_formats.py

@@ -182,7 +182,7 @@ def test_dti_summary(self):
 
         for idx, expected in zip([idx1, idx2, idx3, idx4, idx5, idx6],
                                  [exp1, exp2, exp3, exp4, exp5, exp6]):
-            result = idx.summary()
+            result = idx._summary()
             assert result == expected
 
     def test_dti_business_repr(self):
@@ -191,15 +191,15 @@ def test_dti_business_repr(self):
 
     def test_dti_business_summary(self):
         rng = pd.bdate_range(datetime(2009, 1, 1), datetime(2010, 1, 1))
-        rng.summary()
-        rng[2:2].summary()
+        rng._summary()
+        rng[2:2]._summary()
 
     def test_dti_business_summary_pytz(self):
-        pd.bdate_range('1/1/2005', '1/1/2009', tz=pytz.utc).summary()
+        pd.bdate_range('1/1/2005', '1/1/2009', tz=pytz.utc)._summary()
 
     def test_dti_business_summary_dateutil(self):
         pd.bdate_range('1/1/2005', '1/1/2009',
-                       tz=dateutil.tz.tzutc()).summary()
+                       tz=dateutil.tz.tzutc())._summary()
 
     def test_dti_custom_business_repr(self):
         # only really care that it works
@@ -209,12 +209,13 @@ def test_dti_custom_business_repr(self):
     def test_dti_custom_business_summary(self):
         rng = pd.bdate_range(datetime(2009, 1, 1), datetime(2010, 1, 1),
                              freq='C')
-        rng.summary()
-        rng[2:2].summary()
+        rng._summary()
+        rng[2:2]._summary()
 
     def test_dti_custom_business_summary_pytz(self):
-        pd.bdate_range('1/1/2005', '1/1/2009', freq='C', tz=pytz.utc).summary()
+        pd.bdate_range('1/1/2005', '1/1/2009', freq='C',
+                       tz=pytz.utc)._summary()
 
     def test_dti_custom_business_summary_dateutil(self):
         pd.bdate_range('1/1/2005', '1/1/2009', freq='C',
-                       tz=dateutil.tz.tzutc()).summary()
+                       tz=dateutil.tz.tzutc())._summary()

pandas/tests/indexes/period/test_formats.py

@@ -205,5 +205,5 @@ def test_summary(self):
                                   idx6, idx7, idx8, idx9],
                                  [exp1, exp2, exp3, exp4, exp5,
                                   exp6, exp7, exp8, exp9]):
-            result = idx.summary()
+            result = idx._summary()
             assert result == expected

pandas/tests/indexes/test_base.py

@@ -1055,14 +1055,21 @@ def test_is_all_dates(self):
         assert not self.intIndex.is_all_dates
 
     def test_summary(self):
-        self._check_method_works(Index.summary)
+        self._check_method_works(Index._summary)
         # GH3869
         ind = Index(['{other}%s', "~:{range}:0"], name='A')
-        result = ind.summary()
+        result = ind._summary()
         # shouldn't be formatted accidentally.
         assert '~:{range}:0' in result
         assert '{other}%s' in result
 
+    # GH18217
+    def test_summary_deprecated(self):
+        ind = Index(['{other}%s', "~:{range}:0"], name='A')
+
+        with tm.assert_produces_warning(FutureWarning):
+            ind.summary()
+
     def test_format(self):
         self._check_method_works(Index.format)
 

pandas/tests/indexes/timedeltas/test_formats.py

@@ -92,5 +92,5 @@ def test_summary(self):
 
         for idx, expected in zip([idx1, idx2, idx3, idx4, idx5],
                                  [exp1, exp2, exp3, exp4, exp5]):
-            result = idx.summary()
+            result = idx._summary()
             assert result == expected