ENH: Change `MultiIndex.get_level_values()` to `MultiIndex.get_level()`

[mcp292]

Feature Type

• Adding new functionality to pandas

• Changing existing functionality in pandas

• Removing existing functionality in pandas

Problem Description

The Index.values attribute is already associated with an array type, but MultiIndex.get_level_values() returns an Index object - which is confusing.

Feature Description

Changing the method name to MultiIndex.get_level() should correct this inconsistency.

In English:
MultiIndex.get_level() intuitively returns an Index object of that level. MultiIndex.get_level_values() intuitively returns an array object of that level. But, the reality is MultiIndex.get_level_values() returns an Index object of that level.

In code:

# intuitively
level_index = df.index.get_level("Level")
level_values = df.index.get_level_values("Level")

# reality
level_index = df.index.get_level_values("Level")
level_values = df.index.get_level_values("Level").values

Alternative Solutions

Alias and deprecate.

Additional Context

No response

[phofl]

Hi, thanks for your request.

Imo get_level_values is the appropriate name. We keep track of the level internally, but this is a different object than what is returned here, it does not contain duplicate elements, it is basically midx.get_level_values().drop_duplicates(). Since .levels is public, calling this get_level would be more confusing imo.

[mcp292]

Thank you for your input. I'm interested to hear from more of the team so I won't take action immediately.

As you mentioned though, .levels returns something different, whereas .get_level() would get a single level, in its entirety, with duplicates. I would agree with your statement if I were proposing a .get_levels() that returned something different than .levels.

[phofl]

get_level implies to me that you get one element of levels while get_levels would imply to me that you get all of them. So this is more confusing to me than get_level_values

[mcp292]

This understanding is correct. get_level() should give you one column of the MultiIndex levels which should be of type Index.

[jreback]

this is exactly what .levels[n] already does

-1 on any api change

[mcp292]

That doesn't allow named access.

[mcp292]

And that doesn't address the main issue: values implies array.

[mroeschke]

Thanks for the request but it appears there hasn't been much interest in this issue from the core team and community over the years so closing.