DOC: DataFrame.reset_index names param can't be a tuple as docs state

[alexandermorgan]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.reset_index.html

Documentation problem

In the description of the names parameter, the declared type in bold is correct: "int, str or 1-dimensional list, default None"

But the expanded description that immediately follows incorrectly states that names can be a tuple: "If the DataFrame has a MultiIndex, this has to be a list or tuple with length equal to the number of levels."

This is incorrect because passing a tuple as the names parameter raises this error: 'raise ValueError("Index names must be str or 1-dimensional list")'

Suggested fix for documentation

Remove " or tuple" from the expanded documentation description. This will cause it to match the bold-face type description, and more importantly accurately reflect the behavior. I can submit a PR for this if that's preferred.

[Aloqeely]

The method that raised the ValueError is Index._get_default_index_names and it states that it only raises "if names not str or list-like", and a tuple is definitely list-like, I think it makes more sense to fix the behavior of _get_default_index_names to accept tuples, rather than change the documentation

[rhshadrach]

But the expanded description that immediately follows incorrectly states that names can be a tuple: "If the DataFrame has a MultiIndex, this has to be a list or tuple with length equal to the number of levels."

@alexandermorgan - can you supply a reproducible example.

[asishm]

pd.DataFrame({'a': [1]}, index=pd.MultiIndex.from_tuples([(1,2)])).reset_index(names=('a', 'b'))

raises with ValueError: Index names must be str or 1-dimensional list

File ~/asishm/pandas/core/frame.py:6144, in DataFrame.reset_index(self, level, drop, inplace, col_level, col_fill, allow_duplicates, names)
   6141 to_insert: Iterable[tuple[Any, Any | None]]
   6143 default = "index" if "index" not in self else "level_0"
-> 6144 names = self.index._get_default_index_names(names, default)
   6146 if isinstance(self.index, MultiIndex):
   6147     to_insert = zip(self.index.levels, self.index.codes)

File ~/asishm/pandas/core/indexes/base.py:1727, in Index._get_default_index_names(self, names, default)
   1724         names = [names]
   1726 if not isinstance(names, list) and names is not None:
-> 1727     raise ValueError("Index names must be str or 1-dimensional list")
   1729 if not names:
   1730     if isinstance(self, MultiIndex):

ValueError: Index names must be str or 1-dimensional list

[alexandermorgan]

If we go with @Aloqeely's suggestion of changing Index._get_default_index_names, then instead of raising an error if names is not a list, we could change the condition of the error block to be if not is_list_like(names). Here is where is_list_like seems to be defined. It's a little surprising that the 7 examples given in the docstring of is_list_like's behavior, neither tuples nor dictionaries are included, though the function returns True for both types.

[rhshadrach]

Thanks @asishm and @alexandermorgan. From the original issue:

For multi-index, you should provide a list.

and the corresponding PR, it seems clear to me the original intention was to require a list. I think we should update the docs here.

cc @jorisvandenbossche

[gboeker]

take