Repository: pandas-dev/pandas

Issue:
Deprecate Index.summary
```python
In [88]: idx = pd.Index([1, 2, 3])

In [89]: idx.summary()
Out[89]: 'Int64Index: 3 entries, 1 to 3'
```


Discussion:
this is also a useless method and should be deprecated 
Well, `Index` has no summary methods like `.info` or `.describe` (vs. `DataFrame` or `Series`).  Might be worthwhile to beef this up so that we can return more meaningful info.
I would also deprecate this, and separately we can think whether it is worth to add a `info()` method to Index?
Apologies if any of this is super naive. I'm new.

Deleting the method and any tests directly targeting it isn't enough. There are other failures like

```
__ TestDataFrameReprInfoEtc.test_info_duplicate_columns_shows_correct_dtypes ___

self = <pandas.tests.frame.test_repr_info.TestDataFrameReprInfoEtc object at 0x7f34597891d0>

    def test_info_duplicate_columns_shows_correct_dtypes(self):
        # GH11761
        io = StringIO()

        frame = DataFrame([[1, 2.0]],
                          columns=['a', 'a'])
        frame.info(buf=io)
        io.seek(0)
        lines = io.readlines()
>       assert 'a    1 non-null int64\n' == lines[3]
E       AssertionError: assert 'a    1 non-null int64\n' == 'a    1 non-null float64\n'
E         - a    1 non-null int64
E         ?                 ^^
E         + a    1 non-null float64
E         ?                 ^^^^
```

The reason is the output of `summary` is included in the output of `pandas.DataFrame.info`.

```
In [11]: # pretend the variables in the test are available here

In [12]: lines
Out[12]: 
["<class 'pandas.core.frame.DataFrame'>\n",
 'RangeIndex: 1 entries, 0 to 0\n',
 'Data columns (total 2 columns):\n',
 'a    1 non-null int64\n',
 'a    1 non-null float64\n',
 'dtypes: float64(1), int64(1)\n',
 'memory usage: 96.0 bytes\n']
```

(That second element is the output from `summary`.)

Would it be more appropriate to
* replace `Index.summary` with `Index.info`,
* make `info` more useful (per above comments), and
* update tests?

An alternative is to update the tests to make them pass, but I don't know if that's a good idea.
I would

1. Rename `Index.summary` to `Index._summary`
2. Change anywhere in pandas where we currently use `Index.summary` to `Index._summary`
3. Make a new `Index.summary` that looks like

```python
def summary(self):
    warnings.warn("Index.summary is deprecated and will be removed in a future version")
    return self._summary()
```
Thanks for the feedback. Works for me. I'll get to this soon.

On Wed, Nov 29, 2017 at 6:31 PM, Tom Augspurger <notifications@github.com>
wrote:

> I would
>
>    1. Rename Index.summary to Index._summary
>    2. Change anywhere in pandas where we currently use Index.summary to
>    Index._summary
>    3. Make a new Index.summary that looks like
>
> def summary(self):
>     warnings.warn("Index.summary is deprecated and will be removed in a future version")
>     return self._summary()
>
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/issues/18217#issuecomment-348063576>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/AGJ2sN9r904XWOs12ZZwRFsFJSPhFqi1ks5s7hNsgaJpZM4QZwWi>
> .
>


Resolving patch:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
--- a/pandas/core/frame.py
+++ b/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__)
diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py
--- a/pandas/core/indexes/base.py
+++ b/pandas/core/indexes/base.py
@@ -1385,7 +1385,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
@@ -1404,6 +1416,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
diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py
--- a/pandas/core/indexes/datetimelike.py
+++ b/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:


Test patch:
diff --git a/pandas/tests/indexes/datetimes/test_formats.py b/pandas/tests/indexes/datetimes/test_formats.py
--- a/pandas/tests/indexes/datetimes/test_formats.py
+++ b/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()
diff --git a/pandas/tests/indexes/period/test_formats.py b/pandas/tests/indexes/period/test_formats.py
--- a/pandas/tests/indexes/period/test_formats.py
+++ b/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
diff --git a/pandas/tests/indexes/test_base.py b/pandas/tests/indexes/test_base.py
--- a/pandas/tests/indexes/test_base.py
+++ b/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)
 
diff --git a/pandas/tests/indexes/timedeltas/test_formats.py b/pandas/tests/indexes/timedeltas/test_formats.py
--- a/pandas/tests/indexes/timedeltas/test_formats.py
+++ b/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