An implementation of upcast

[Azureblade3808]

I use Pandas in my daily work. Sometimes I want to erase generic types provided by "pandas-stubs" (e.g., convert Series[bool] into Series), as the types there don't seem right. I used to use typing.cast to have the job done but I've written some bugs caused by some wrong casts (e.g., cast("pd.Series", df.iloc[0:]) instead of cast("pd.Series", df.iloc[0])) . Now I have implemented upcast to avoid such bugs.

from __future__ import annotations

from typing_extensions import Any, Generic, Never, TypeVar, overload

_T = TypeVar("_T")
_T0 = TypeVar("_T0")

class upcast(Generic[_T]):
    def __class_getitem__(cls, key: Any, /) -> type[Any]:
        # ! This method normally returns a generic type alias, which always adds a
        # ! `__orig_base__` member onto its call result that would normally be a
        # ! newly created instance of the original class.

        # ! We are getting rid of this behavior here, as it would cause unnecessary
        # ! overhead and raise errors with any value that is an instance of `type`.

        return cls

    # If `upcast` is used without a generic type, the call will be blocked by this 
    # overload and the return type `Never` will indicate something is wrong.
    @overload
    def __new__(cls: type[upcast[Never]], value: Any, /) -> Never:
        ...

    @overload
    def __new__(cls: type[upcast[_T0]], value: _T0, /) -> _T0:
        ...

    def __new__(cls, value: Any, /) -> Any:
        return value

It can be used with something like upcast[TYPE_OR_TYPE_STRING](value). For example ---

i = int()
reveal_type(i)  # "int".

f = upcast[float](i)
reveal_type(f)  # "float"

s = upcast["str"](f)  # Reported, as `float` is not a subtype of `str`.

and

import pandas

s0 = pandas.Series([])
reveal_type(s0)  # "TimestampSeries", which is incorrect.

s1 = upcast["pandas.Series"](s0)
reveal_type(s1)  # "Series[Unknown]".

s1[0] = 0

v0 = s1.loc[0]
reveal_type(v0)  # "Unknown".

v1 = upcast["float"](v0)
reveal_type(v1)  # "float".

Related: #1261

---

Edit:
Add a custom __class_getitem__ to prevent some unexpected errors with calls like upcast["int"](int).

[twoertwein]

I use Pandas in my daily work. Sometimes I want to erase generic types provided by "pandas-stubs" (e.g., convert Series[bool] into Series), as the types there don't seem right.

Feel free to report pandas-stubs issues here: https://github.com/pandas-dev/pandas-stubs

If you prefer the pandas annotations (compared to the pandas-stubs annotations), you can simply uninstall pandas-stubs: pyright should(?) then use the non-py.typed pandas annotations and infer any missing annotations.

[Azureblade3808]

Pandas-stubs has been a great project and is still getting better, so I have no reason to stop using it. Problem is that I don't always use pandas in recommended ways, so there may be distances between common needs and my own needs. If I see something that is qualified as an issue, I will surely report it.