DataFrame.index not reliably typed using Index[Any]

[adamjstewart]

Describe the bug

DataFrame.index is currently typed as Index[Any]. As a result, certain statically typed valid code is flagged as invalid by mypy. I would argue that Any would be better until the index can be reliably typed.

To Reproduce

For the following code:

import pandas as pd

data = {'col1': [1, 2], 'col2': [3, 4]}
index = pd.interval_range(start=0, end=2)
df = pd.DataFrame(data, index)
print(df.index.left)
print(df.index.right)

mypy complains with:

test.py:6: error: "Index[Any]" has no attribute "left"  [attr-defined]
test.py:7: error: "Index[Any]" has no attribute "right"  [attr-defined]
Found 2 errors in 1 file (checked 1 source file)

This is because I am using an IntervalIndex, not a generic Index.

Please complete the following information:

• OS: macOS
• OS Version: 26.1
• python version: 3.13.8
• version of type checker: 1.19.0
• version of installed pandas-stubs: 2.3.2.250926

Additional context

The issue of DataFrame.index type hints was also raised in pandas-dev/pandas#36708. This issue also impacts geopandas: python/typeshed#15111.

[cmp0xff]

Thank you for the report. DataFrame is currently not typed as generic (#295), so that special indexes and columns cannot be represented.

One can imagine adding index and columns as TypeVars to the DataFrame class in the stubs. We are open to PRs.

Please note that the current behaviours, specified by the tests, need to be kept. My personal experience is that adding TypeVars is challenging.

[adamjstewart]

Completely agree with making DataFrame a generic. I'm just wondering if index should be Any while we wait for it to become a generic.

[cmp0xff]

I'm just wondering if index should be Any while we wait for it to become a generic.

What would you suggest as an alternative?

[cmp0xff]

In the example you provided, we can do as follows:

from typing import cast, reveal_type

import pandas as pd

data = {'col1': [1, 2], 'col2': [3, 4]}
df = pd.DataFrame(data, pd.interval_range(start=0, end=2))

index = cast("pd.IntervalIndex[pd.Interval[int]]", df.index)
reveal_type(index.left)  # pyright gives Index[Any]
reveal_type(index.right)  # pyright gives Index[Any]

Neither mypy nor pyright complain any more. However, obtaining Index[Any] is not ideal, which is another topic.

[adamjstewart]

I would suggest Any as an alternative to Index[Any]. This disables the type checker on dynamic types since we can't know the correct type at the moment. Correct statically typed code should not be changed to fit type hints, type hints should be changed to match code.

[Dr-Irv]

I would suggest Any as an alternative to Index[Any]. This disables the type checker on dynamic types since we can't know the correct type at the moment. Correct statically typed code should not be changed to fit type hints, type hints should be changed to match code.

The pandas source is not fully typed. The goal of pandas-stubs is to provide type hints that assist users based on the most common usage of pandas.

DataFrame.index returns an Index, but we don't know which subclass (RangeIndex, DatetimeIndex, IntervalIndex, MultiIndex, etc.). So using Index[Any] is covering all the subclasses. If DataFrame.index were to return Any, you lose the benefit of having type checking occur for the methods that are in the Index base class.

[adamjstewart]

We could also modify Index[Any] such that all unknown attributes (e.g., left, right) are Any.

[Dr-Irv]

We could also modify Index[Any] such that all unknown attributes (e.g., left, right) are Any.

The downside of that is that we have to pick up all the attributes of the subclasses of Index that are not attributes of Index.

The benefit of the current approach, suggested above when using cast, is that you are telling the type checker "I know that I have an IntervalIndex here, so please treat it as such."

Same goes for DatetimeIndex, TimedeltaIndex, etc.