DOC: Update MultiIndex.names whatsnew (pandas-dev#29572)

Author: TomAugspurger

doc/source/user_guide/advanced.rst

@@ -554,6 +554,31 @@ index.
 Both ``rename`` and ``rename_axis`` support specifying a dictionary,
 ``Series`` or a mapping function to map labels/names to new values.
 
+When working with an ``Index`` object directly, rather than via a ``DataFrame``,
+:meth:`Index.set_names` can be used to change the names.
+
+.. ipython:: python
+
+   mi = pd.MultiIndex.from_product([[1, 2], ['a', 'b']], names=['x', 'y'])
+   mi.names
+
+   mi2 = mi.rename("new name", level=0)
+   mi2
+
+.. warning::
+
+   Prior to pandas 1.0.0, you could also set the names of a ``MultiIndex``
+   by updating the name of a level.
+
+   .. code-block:: none
+
+      >>> mi.levels[0].name = 'name via level'
+      >>> mi.names[0]  # only works for older panads
+      'name via level'
+
+   As of pandas 1.0, this will *silently* fail to update the names
+   of the MultiIndex. Use :meth:`Index.set_names` instead.
+
 Sorting a ``MultiIndex``
 ------------------------
 

doc/source/whatsnew/v1.0.0.rst

@@ -130,34 +130,39 @@ Backwards incompatible API changes
 
 .. _whatsnew_1000.api_breaking.MultiIndex._names:
 
-``MultiIndex.levels`` do not hold level names any longer
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Avoid using names from ``MultiIndex.levels``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- A :class:`MultiIndex` previously stored the level names as attributes of each of its
-  :attr:`MultiIndex.levels`. From Pandas 1.0, the names are only accessed through
-  :attr:`MultiIndex.names` (which was also possible previously). This is done in order to
-  make :attr:`MultiIndex.levels` more similar to :attr:`CategoricalIndex.categories` (:issue:`27242`:).
+As part of a larger refactor to :class:`MultiIndex` the level names are now
+stored separately from the levels (:issue:`27242`). We recommend using
+:attr:`MultiIndex.names` to access the names, and :meth:`Index.set_names`
+to update the names.
 
-*pandas 0.25.x*
+For backwards compatibility, you can still *access* the names via the levels.
 
-.. code-block:: ipython
+.. ipython:: python
 
-   In [1]: mi = pd.MultiIndex.from_product([[1, 2], ['a', 'b']], names=['x', 'y'])
-   Out[2]: mi
-   MultiIndex([(1, 'a'),
-               (1, 'b'),
-               (2, 'a'),
-               (2, 'b')],
-              names=['x', 'y'])
-   Out[3]: mi.levels[0].name
-   'x'
+   mi = pd.MultiIndex.from_product([[1, 2], ['a', 'b']], names=['x', 'y'])
+   mi.levels[0].name
 
-*pandas 1.0.0*
+However, it is no longer possible to *update* the names of the ``MultiIndex``
+via the name of the level. The following will **silently** fail to update the
+name of the ``MultiIndex``
 
 .. ipython:: python
 
-   mi = pd.MultiIndex.from_product([[1, 2], ['a', 'b']], names=['x', 'y'])
-   mi.levels[0].name
+   mi.levels[0].name = "new name"
+   mi.names
+
+To update, use ``MultiIndex.set_names``, which returns a new ``MultiIndex``.
+
+.. ipython:: python
+
+   mi2 = mi.set_names("new name", level=0)
+   mi2.names
+
+New repr for :class:`pandas.core.arrays.IntervalArray`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - :class:`pandas.core.arrays.IntervalArray` adopts a new ``__repr__`` in accordance with other array classes (:issue:`25022`)