Broaden read csv param types

[EFord36]

• Closes usecols keyword argument of pd.read_csv says it expects list[str] but the documentation says otherwise #605, Closes names parameter of pd.read_csv restricted to list[str] even though the valid types are much broader #623
• Tests added: Please use assert_type() to assert the type of any return value

Submitted as 1 PR for the 2 issues because the relevant code is so close that I thought it might be quicker to review together, plus trying to have both as separate PRs would likely result in merge conflicts if/when one was merged before the other. The commits addressing the two issues are separate though, so it would be easy for me to split into 2 separate PR if this is preferred.

As well as read_csv, modify read_table, read_clipboard, read_excel, which all have the relevant params (I searched for other functions but let me know if I missed any).

Closes #605 in a different way than suggested in that ticket, in order to allow broader types than just lists of string or ints, since list-likes are allowed here. Naming of the type alias UsecolsArgType was inspired by ColspaceArgType, happy to change if desired.

Please let me know if coverage of more different types for names and/or usecols is needed in the tests, or if there are stylistic details you would like me to change. There is a lot of repetition between the tests for the different functions that have these params - I'm happy to work on reducing it, but I thought it might mean restructuring some of the existing tests, so I didn't want to fiddle with it too much until I knew if it (and the actual functional change) was desired.

Passes tests (poetry run poe test_all) locally when the last commit before my changes is 7730abc - the two commits after that (6819e32 and 9c301b3) result in test failures for me locally that seem unrelated to my change, and I get if I just run on main with no changes.

[Dr-Irv]

Thanks for this nice PR and for combining the changes for both issues in the same PR, and the extensive tests.

I would like to add tests that make sure that a plain string is not accepted where it is not supposed to be. Something like this:

        if TYPE_CHECKING_INVALID_USAGE:
            pd.read_excel(path, names="foo")  # type: ignore[call-overload] # pyright: ignore[reportGeneralTypeIssues]
            pd.read_csv(path, usecols="foo")  # type: ignore[arg-type] # pyright: ignore[reportGeneralTypeIssues]

I tried the above, with your PR, and it worked, but you should add tests for the names and usecols argument where str is not accepted, and I think it is just for names for read_excel().

I think that for read_excel() you use call-overload, but for the rest, arg-type should work.

[EFord36]

Added tests to make sure the plain string isn't accepted (and one for read_excel to check it is accepted where it should be).

Thanks for the guidance, it made adding the tests nice and quick for me!

Running the tests a few times, turns out it needs arg-type for usecols, but call-overload for names.

(I'm speculating maybe because usecols has a specific type alias that is shared between all the overloads, mypy is smart enough there to take into account that the argument type is the same between overloads, and raise arg-type, whereas for usecols, because the still shared type hint is now more complex, it doesn't? I may be missing something obvious, but to me it seems like the failures are for the same reason.)

[Dr-Irv]

Thanks @EFord36 . Nice work.

[Dr-Irv]

(I'm speculating maybe because usecols has a specific type alias that is shared between all the overloads, mypy is smart enough there to take into account that the argument type is the same between overloads, and raise arg-type, whereas for usecols, because the still shared type hint is now more complex, it doesn't? I may be missing something obvious, but to me it seems like the failures are for the same reason.)

TBH, I've never figured out exactly why mypy picks one error over another. So we put in the error that was reported to make sure that we get through CI. For these kinds of tests where we are using TYPE_CHECKING_INVALID_USAGE, the goal is to make sure that mypy and pyright flag them as known errors. The specific error reported is less of a concern.