fix: include all names in MultiIndex repr (#564)

docs: include Index in table-of-contents (#564)

Author: tswast

bigframes/core/blocks.py

@@ -1314,8 +1314,8 @@ def retrieve_repr_request_results(
             head_block = self
         computed_df, query_job = head_block.to_pandas()
         formatted_df = computed_df.set_axis(self.column_labels, axis=1)
-        # we reset the axis and substitute the bf index name for the default
-        formatted_df.index.name = self.index.name
+        # we reset the axis and substitute the bf index name(s) for the default
+        formatted_df.index.names = self.index.names  # type: ignore
         return formatted_df, count, query_job
 
     def promote_offsets(self, label: Label = None) -> typing.Tuple[Block, str]:

bigframes/core/indexes/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from bigframes.core.indexes.index import Index
+from bigframes.core.indexes.base import Index
 
 __all__ = [
     "Index",

bigframes/core/indexes/index.py renamed to bigframes/core/indexes/base.py

@@ -88,7 +88,12 @@ def from_frame(
 
     @property
     def name(self) -> blocks.Label:
-        return self.names[0]
+        names = self.names
+        if len(names) == 1:
+            return self.names[0]
+        else:
+            # pandas returns None for MultiIndex.name.
+            return None
 
     @name.setter
     def name(self, value: blocks.Label):
@@ -460,14 +465,6 @@ def __init__(
         super().__init__(series_or_dataframe._block)
         self._whole_frame = series_or_dataframe
 
-    @property
-    def name(self) -> blocks.Label:
-        return self.names[0]
-
-    @name.setter
-    def name(self, value: blocks.Label):
-        self.names = [value]
-
     @property
     def names(self) -> typing.Sequence[blocks.Label]:
         """Returns the names of the Index."""

docs/reference/bigframes.pandas/indexing.rst

@@ -3,7 +3,7 @@
 Index objects
 =============
 
-.. autoclass:: bigframes.core.indexes.index.Index
+.. autoclass:: bigframes.core.indexes.base.Index
     :members:
     :inherited-members:
     :undoc-members:

docs/templates/toc.yml

@@ -40,6 +40,8 @@
       - name: SeriesGroupBy
         uid: bigframes.core.groupby.SeriesGroupBy
       name: Groupby
+    - name: Index
+      uid: bigframes.core.indexes.base.Index
     - items:
       - name: AtDataFrameIndexer
         uid: bigframes.core.indexers.AtDataFrameIndexer

scripts/publish_api_coverage.py

@@ -44,6 +44,9 @@
     "dataframegroupby": (
         "https://cloud.google.com/python/docs/reference/bigframes/latest/bigframes.core.groupby.DataFrameGroupBy#bigframes_core_groupby_DataFrameGroupBy_"
     ),
+    "index": (
+        "https://cloud.google.com/python/docs/reference/bigframes/latest/bigframes.core.indexes.base.Index#bigframes_core_indexes_base_Index_"
+    ),
     "series": (
         "https://cloud.google.com/python/docs/reference/bigframes/latest/bigframes.series.Series#bigframes_series_Series_"
     ),
@@ -59,7 +62,6 @@
     "window": (
         "https://cloud.google.com/python/docs/reference/bigframes/latest/bigframes.core.window.Window#bigframes_core_window_Window_"
     ),
-    # TODO: Index not documented.
 }
 
 

tests/system/small/test_index.py

@@ -370,3 +370,42 @@ def test_index_isin(scalars_df_index, scalars_pandas_df_index):
         bf_series,
         check_names=False,
     )
+
+
+def test_multiindex_name_is_none(session):
+    df = pd.DataFrame(
+        {
+            "A": [0, 0, 0, 1, 1, 1],
+            "B": ["x", "y", "z", "x", "y", "z"],
+            "C": [123, 345, 789, -123, -345, -789],
+            "D": ["a", "b", "c", "d", "e", "f"],
+        },
+    )
+    index = session.read_pandas(df).set_index(["A", "B"]).index
+    assert index.name is None
+
+
+def test_multiindex_names_not_none(session):
+    df = pd.DataFrame(
+        {
+            "A": [0, 0, 0, 1, 1, 1],
+            "B": ["x", "y", "z", "x", "y", "z"],
+            "C": [123, 345, 789, -123, -345, -789],
+            "D": ["a", "b", "c", "d", "e", "f"],
+        },
+    )
+    index = session.read_pandas(df).set_index(["A", "B"]).index
+    assert tuple(index.names) == ("A", "B")
+
+
+def test_multiindex_repr_includes_all_names(session):
+    df = pd.DataFrame(
+        {
+            "A": [0, 0, 0, 1, 1, 1],
+            "B": ["x", "y", "z", "x", "y", "z"],
+            "C": [123, 345, 789, -123, -345, -789],
+            "D": ["a", "b", "c", "d", "e", "f"],
+        },
+    )
+    index = session.read_pandas(df).set_index(["A", "B"]).index
+    assert "names=['A', 'B']" in repr(index)

tests/system/small/test_session.py

@@ -27,7 +27,7 @@
 import pytest
 
 import bigframes
-import bigframes.core.indexes.index
+import bigframes.core.indexes.base
 import bigframes.dataframe
 import bigframes.dtypes
 import bigframes.ml.linear_model

third_party/bigframes_vendored/pandas/core/frame.py

@@ -4879,7 +4879,7 @@ def index(self):
             MultiIndex([( 'Alice',  'Seattle'),
                 (   'Bob', 'New York'),
                 ('Aritra',     'Kona')],
-               name='Name')
+               names=['Name', 'Location'])
             >>> df1.index.values
             array([('Alice', 'Seattle'), ('Bob', 'New York'), ('Aritra', 'Kona')],
                 dtype=object)

third_party/bigframes_vendored/pandas/core/indexes/base.py

@@ -8,6 +8,18 @@ class Index:
     """Immutable sequence used for indexing and alignment.
 
     The basic object storing axis labels for all objects.
+
+    Args:
+        data (pandas.Series | pandas.Index | bigframes.series.Series | bigframes.core.indexes.base.Index):
+            Labels (1-dimensional).
+        dtype:
+            Data type for the output Index. If not specified, this will be
+            inferred from `data`.
+        name:
+            Name to be stored in the index.
+        session (Optional[bigframes.session.Session]):
+            BigQuery DataFrames session where queries are run. If not set,
+            a default session is used.
     """
 
     @property

third_party/bigframes_vendored/pandas/core/series.py

@@ -87,7 +87,7 @@ def index(self):
             MultiIndex([( 'Alice',  'Seattle'),
                 (   'Bob', 'New York'),
                 ('Aritra',     'Kona')],
-               name='Name')
+               names=['Name', 'Location'])
             >>> s1.index.values
             array([('Alice', 'Seattle'), ('Bob', 'New York'), ('Aritra', 'Kona')],
                 dtype=object)