index in DataFrame.from_records does not accept Index, Series, etc.

[cmp0xff]

Describe the bug

DataFrame.from_records(data, index=pd.Index(...)) is not accepted

edit: the following types work at runtime, but none is accpeted:

• pd.Index[str]
• pd.Series[str]
• ExtensionArray
• ArrayLike (see example)
• np.typing.NDArray[np.str_]
• np.typing.NDArray[Any]

To Reproduce

Provide a minimal runnable pandas example that is not properly checked by the stubs.

import numpy as np
import pandas as pd

data, py_l = [[1, 2, 3], [4, 5, 6]], ["a", "b"]
pd.DataFrame.from_records(data, pd.Index(py_l))
pd.DataFrame.from_records(data, pd.Series(py_l))
pd.DataFrame.from_records(data, pd.Series(py_l).array)
pd.DataFrame.from_records(data, pd.Series(py_l).values)
pd.DataFrame.from_records(data, np.asarray(py_l))
pd.DataFrame.from_records(data, np.asarray(py_l, np.str_))

Indicate which type checker you are using (mypy or pyright).

pyright

Show the error message received from that type checker while checking your example

attempt.py
  attempt.py:5:33 - error: Argument of type "Index[str]" cannot be assigned to parameter "index" of type "str | SequenceNotStr[Hashable] | None" in function "from_records"
    Type "Index[str]" is not assignable to type "str | SequenceNotStr[Hashable] | None"
      "Index[str]" is not assignable to "str"
      "Index[str]" is incompatible with protocol "SequenceNotStr[Hashable]"
        "index" is not present
        "count" is not present
        "__reversed__" is not present
          "__getitem__" is an incompatible type
            One or more overloads of "__getitem__" is not assignable
    ... (reportArgumentType)
  attempt.py:6:33 - error: Argument of type "Series[str]" cannot be assigned to parameter "index" of type "str | SequenceNotStr[Hashable] | None" in function "from_records"
    Type "Series[str]" is not assignable to type "str | SequenceNotStr[Hashable] | None"
      "Series[str]" is not assignable to "str"
      "Series[str]" is incompatible with protocol "SequenceNotStr[Hashable]"
        "__reversed__" is not present
          "__getitem__" is an incompatible type
            One or more overloads of "__getitem__" is not assignable
          "index" is an incompatible type
            Type "property" is not assignable to type "(value: Any, start: int = ..., stop: int = ..., /) -> int"
    ... (reportArgumentType)
  attempt.py:7:33 - error: Argument of type "ExtensionArray" cannot be assigned to parameter "index" of type "str | SequenceNotStr[Hashable] | None" in function "from_records"
    Type "ExtensionArray" is not assignable to type "str | SequenceNotStr[Hashable] | None"
      "ExtensionArray" is not assignable to "str"
      "ExtensionArray" is incompatible with protocol "SequenceNotStr[Hashable]"
        "index" is not present
        "count" is not present
        "__reversed__" is not present
          "__getitem__" is an incompatible type
            One or more overloads of "__getitem__" is not assignable
    ... (reportArgumentType)
  attempt.py:8:33 - error: Argument of type "ArrayLike" cannot be assigned to parameter "index" of type "str | SequenceNotStr[Hashable] | None" in function "from_records"
    Type "ArrayLike" is not assignable to type "str | SequenceNotStr[Hashable] | None"
      Type "ExtensionArray" is not assignable to type "str | SequenceNotStr[Hashable] | None"
        "ExtensionArray" is not assignable to "str"
        "ExtensionArray" is incompatible with protocol "SequenceNotStr[Hashable]"
          "index" is not present
          "count" is not present
          "__reversed__" is not present
            "__getitem__" is an incompatible type
    ... (reportArgumentType)
  attempt.py:9:33 - error: Argument of type "NDArray[Any]" cannot be assigned to parameter "index" of type "str | SequenceNotStr[Hashable] | None" in function "from_records"
    Type "NDArray[Any]" is not assignable to type "str | SequenceNotStr[Hashable] | None"
      "ndarray[_Shape, dtype[Any]]" is not assignable to "str"
      "ndarray[_Shape, dtype[Any]]" is incompatible with protocol "SequenceNotStr[Hashable]"
        "index" is not present
        "count" is not present
        "__reversed__" is not present
          "__getitem__" is an incompatible type
            One or more overloads of "__getitem__" is not assignable
    ... (reportArgumentType)
  attempt.py:10:33 - error: Argument of type "NDArray[str_]" cannot be assigned to parameter "index" of type "str | SequenceNotStr[Hashable] | None" in function "from_records"
    Type "NDArray[str_]" is not assignable to type "str | SequenceNotStr[Hashable] | None"
      "ndarray[_Shape, dtype[str_]]" is not assignable to "str"
      "ndarray[_Shape, dtype[str_]]" is incompatible with protocol "SequenceNotStr[Hashable]"
        "index" is not present
        "count" is not present
        "__reversed__" is not present
          Could not bind method "__getitem__" because "ndarray[_Shape, dtype[str_]]" is not assignable to parameter "self"
            "ndarray[_Shape, dtype[str_]]" is not assignable to "ndarray[_Shape, dtype[void]]"
    ... (reportArgumentType)
6 errors, 0 warnings, 0 informations

Please complete the following information

• OS: Windows
• OS Version: 11
• python version: 3.13.4
• version of type checker: 1.1.404
• version of installed pandas-stubs: 2.3.2.250827

Additional context

None

[loicdiridollou]

So the docs don't mention the use of Index explicitly but in the code we usually use array-like to ArrayLike | Index | Series.
https://github.com/pandas-dev/pandas/blob/7bfef3b1cba58a6c3aa62493e0b0905bc59e6443/pandas/core/frame.py#L2137-L2139

Could you check if passing a Series would work at runtime? I am onboard to change the type of AnyArrayLike, maybe have @Dr-Irv confirm but it seems in line with how we treat array-like in other parts of the stubs.

[cmp0xff]

Could you check if passing a Series would work at runtime?

description updated

[Dr-Irv]

Seems like the docs are too restrictive. Should use Axes | None to match the DataFrame.__new__() method.

Probably worth creating an issue in pandas to indicate the docs are wrong.