various changes

doc/source/whatsnew/v0.24.0.rst

@@ -1010,6 +1010,14 @@ Other API Changes
 Deprecations
 ~~~~~~~~~~~~
 
+- :attr:`MultiIndex.labels` has been deprecated and replaced by :attr:`MultiIndex.codes`.
+  The functionality is unchanged. This new name better reflects the natures of
+  these codes and makes the API more similar to the API for
+  :class:`CategoricalIndex`(:issue:`13443`).
+  As a concequence, other uses of the name ``labels`` have also been deprecated in ``MultiIndex`` and replaced with ``codes``:
+  - You should initialize a MultiIndex instance using a parameter named ``codes`` rather than ``labels``.
+  - :meth:`MultiIndex.set_labels` has been deprecated in favor of :meth:`MultiIndex.set_codes`
+  - for method :meth:`MultiIndex.copy`, the ``labels`` parameter has been deprecated and replaced by a ``codes`` parameter.
 - :meth:`DataFrame.to_stata`, :meth:`read_stata`, :class:`StataReader` and :class:`StataWriter` have deprecated the ``encoding`` argument. The encoding of a Stata dta file is determined by the file type and cannot be changed (:issue:`21244`)
 - :meth:`MultiIndex.to_hierarchical` is deprecated and will be removed in a future version (:issue:`21613`)
 - :meth:`Series.ptp` is deprecated. Use ``numpy.ptp`` instead (:issue:`21614`)

pandas/core/indexes/base.py

@@ -3990,14 +3990,14 @@ def _join_multi(self, other, how, return_indexers=True):
             # common levels, ldrop_names, rdrop_names
             dropped_names = ldrop_names + rdrop_names
 
-            levels, labels, names = (
+            levels, codes, names = (
                 _restore_dropped_levels_multijoin(self, other,
                                                   dropped_names,
                                                   join_idx,
                                                   lidx, ridx))
 
             # Re-create the multi-index
-            multi_join_idx = MultiIndex(levels=levels, labels=labels,
+            multi_join_idx = MultiIndex(levels=levels, codes=codes,
                                         names=names, verify_integrity=False)
 
             multi_join_idx = multi_join_idx.remove_unused_levels()
@@ -4114,34 +4114,34 @@ def _get_leaf_sorter(labels):
             rev_indexer = lib.get_reverse_indexer(left_lev_indexer,
                                                   len(old_level))
 
-            new_lev_labels = algos.take_nd(rev_indexer, left.codes[level],
-                                           allow_fill=False)
+            new_level_codes = algos.take_nd(rev_indexer, left.codes[level],
+                                            allow_fill=False)
 
             new_codes = list(left.codes)
-            new_codes[level] = new_lev_labels
+            new_codes[level] = new_level_codes
 
             new_levels = list(left.levels)
             new_levels[level] = new_level
 
             if keep_order:  # just drop missing values. o.w. keep order
                 left_indexer = np.arange(len(left), dtype=np.intp)
-                mask = new_lev_labels != -1
+                mask = new_level_codes != -1
                 if not mask.all():
                     new_codes = [lab[mask] for lab in new_codes]
                     left_indexer = left_indexer[mask]
 
             else:  # tie out the order with other
                 if level == 0:  # outer most level, take the fast route
-                    ngroups = 1 + new_lev_labels.max()
+                    ngroups = 1 + new_level_codes.max()
                     left_indexer, counts = libalgos.groupsort_indexer(
-                        new_lev_labels, ngroups)
+                        new_level_codes, ngroups)
 
                     # missing values are placed first; drop them!
                     left_indexer = left_indexer[counts[0]:]
                     new_codes = [lab[left_indexer] for lab in new_codes]
 
                 else:  # sort the leaves
-                    mask = new_lev_labels != -1
+                    mask = new_level_codes != -1
                     mask_all = mask.all()
                     if not mask_all:
                         new_codes = [lab[mask] for lab in new_codes]