Rename summarylevel to describelevel (#11)

CHANGELOG.rst

@@ -3,6 +3,9 @@
 Changelog
 =========
 
+* :py:func:`~core.describelevel` superseedes the as-of-now deprecated
+  :py:func:`~core.summarylevel` :pull:`11`
+
 v0.2.4 (2023-05-03)
 ------------------------------------------------------------
 

src/pandas_indexing/__init__.py

@@ -11,6 +11,7 @@
     alignlevel,
     alignlevels,
     assignlevel,
+    describelevel,
     dropnalevel,
     index_names,
     projectlevel,

src/pandas_indexing/accessors.py

@@ -20,10 +20,10 @@
 from .core import (
     Data,
     assignlevel,
+    describelevel,
     dropnalevel,
     projectlevel,
     semijoin,
-    summarylevel,
     uniquelevel,
 )
 from .utils import Axis
@@ -38,7 +38,7 @@ def __init__(self, pandas_obj):
         self._obj = pandas_obj
 
     def __repr__(self):
-        return summarylevel(self._obj)
+        return describelevel(self._obj, as_str=True)
 
     def assign(
         self,

src/pandas_indexing/core.py

@@ -7,6 +7,7 @@
 from typing import Any, Literal, Optional, Sequence, TypeVar, Union
 
 import numpy as np
+from deprecated import deprecated
 from pandas import DataFrame, Index, MultiIndex, Series
 from pandas.core.indexes.frozen import FrozenList
 
@@ -230,7 +231,7 @@ def uniquelevel(
     return projectlevel(index, levels).unique()
 
 
-def _summarylevel(index: Index, n: int = 80) -> str:
+def _describelevel(index: Index, n: int = 80) -> str:
     def name(l):
         return "<unnamed>" if l is None else l
 
@@ -241,34 +242,48 @@ def name(l):
     )
 
 
-def summarylevel(index_or_data: Union[DataFrame, Series, Index], n: int = 80):
+def describelevel(
+    index_or_data: Union[DataFrame, Series, Index], n: int = 80, as_str: bool = False
+) -> Optional[str]:
     """
-    Summarize index levels.
+    Describe index levels.
 
     Parameters
     ----------
     index_or_data : Index|Series|DataFrame
-        Index, Series or DataFrame of which to summarize index levels
+        Index, Series or DataFrame of which to describe index levels
     n : int, default 80
         The maximum line length
+    as_str : bool, default False
+        Whether to return as string or print, instead
 
     Returns
     -------
-    summary : str
+    description : str, optional
+        if print is False
 
     See also
     --------
     pandas.DataFrame.describe
     """
     if isinstance(index_or_data, DataFrame):
-        index_desc = _summarylevel(index_or_data.index, n=n)
-        columns_desc = _summarylevel(index_or_data.columns, n=n)
-        return f"Index:\n{index_desc}\n\nColumns:\n{columns_desc}"
+        index_desc = _describelevel(index_or_data.index, n=n)
+        columns_desc = _describelevel(index_or_data.columns, n=n)
+        description = f"Index:\n{index_desc}\n\nColumns:\n{columns_desc}"
+    else:
+        if isinstance(index_or_data, Series):
+            index_or_data = index_or_data.index
+        description = f"Index:\n{_describelevel(index_or_data, n=n)}"
+
+    if as_str:
+        return description
+
+    print(description)
 
-    if isinstance(index_or_data, Series):
-        index_or_data = index_or_data.index
 
-    return f"Index:\n{_summarylevel(index_or_data, n=n)}"
+summarylevel = deprecated(
+    describelevel, reason="Use describelevel instead", version="v0.2.5"
+)
 
 
 def index_names(s, raise_on_index=False):

tests/test_core.py

@@ -10,9 +10,9 @@
 
 from pandas_indexing.core import (
     assignlevel,
+    describelevel,
     dropnalevel,
     projectlevel,
-    summarylevel,
     uniquelevel,
 )
 
@@ -139,9 +139,9 @@ def test_uniquelevel(mdf, midx):
     assert_index_equal(uniquelevel(midx, ["str", "num"]), midx)
 
 
-def test_summarylevel(mdf, midx):
+def test_describelevel(mdf, midx):
     assert (
-        summarylevel(mdf)
+        describelevel(mdf, as_str=True)
         == dedent(
             """
             Index:
@@ -155,7 +155,7 @@ def test_summarylevel(mdf, midx):
     )
 
     assert (
-        summarylevel(midx)
+        describelevel(midx, as_str=True)
         == dedent(
             """
             Index: