Description
See comment #2 in microsoft/pyright#5178 (comment)
Some of the overloads for pd.Series.new return types other than pd.Series (e.g. TimestampSeries, PeriodSeries). These other types appear nowhere within the pandas library. I presume they were added to the stubs as sort of a hack to expose certain methods that apply only for certain specializations of Series. There are better ways of handling this that more closely model the library's runtime behavior. One of the big problems with introducing these "made-up" subclasses is that Series cannot be properly subclassed. For example, if you create a subclass of Series (let's call it MySeries) but then pass arguments to the constructor that invoke an overload that returns a TimestampSeries, you will now have a TimestampSeries rather than a MySeries. If I were maintaining these stubs, I'd look at eliminating these made-up classes and folding the functionality into the main Series class. You can use a specialized type annotation for self to limit the behavior to a specific specialization of Series. For example, def add(self: Series[Timedelta], ....
NOTE: Those extra types were intrroduced in March, 2022, to make it so that mypy would work, because using something like def __add__(self: Series[Timedelta]) ... did not work with the version of mypy at that time. But mypy has evolved, so we should see if they can be removed.