Read-only (covariant) list parameter annotations

[hamdanal]

• Closes BUG: set_index rejects List[str] #153 (already closed but similar issues still exist)
• Tests added (Please use assert_type() to assert the type of any return value)
• No AI used

Some pandas functions expect a list as argument but not any sequence. Because list is invariant, parameters annotated with list[float] will not accept list[int], for examlpe, even though we know that the list is read-only and will not be modified. To fix this, I propose the following trick using the CovariantList protocol. This protocol can replace list annotations in parameter positions (never use as a return type, instead keep using list there).

Note that this problem has manifested before and one trick you use today is to parametrize the list with a type variable that has an appropriate upper bound (for example you use list[HashableT] where you want a list of hashable objects). This is cumbersome because for every type of list element, you'll need to define a corresponding type variable. Also, there are some places where a list of a very wide type like a union is still used (for example list[AggFuncTypeBase] in DataFrame.aggregate). All of these can be replaced with the CovariantList protocol.

In this PR I only introduce the protocol and change one method to use it to demonstrate its value. I think it would be better to incrementally use this protocol in follow up PR(s) for easier work and review. For example a PR could replace all list[HashableT] and list[Hashable] in parameter positions by CovariantList[Hashable] then other uses could be audited and changed in separate follow-up PRs.

[Dr-Irv]

thanks. This looks like an interesting idea!

[Dr-Irv]

thanks @hamdanal