Explain typed etc.

Author: topper-123

pandas/_testing.py

@@ -22,7 +22,7 @@
 )
 
 import pandas._libs.testing as _testing
-from pandas._typing import FrameOrSeriesT
+from pandas._typing import SameFrameOrSeries
 from pandas.compat import _get_lzma_file, _import_lzma
 
 from pandas.core.dtypes.common import (
@@ -102,8 +102,8 @@ def reset_display_options():
 
 
 def round_trip_pickle(
-    obj: FrameOrSeriesT, path: Optional[str] = None
-) -> FrameOrSeriesT:
+    obj: SameFrameOrSeries, path: Optional[str] = None
+) -> SameFrameOrSeries:
     """
     Pickle an object and then read it again.
 

pandas/_typing.py

@@ -42,8 +42,16 @@
 
 Dtype = Union[str, np.dtype, "ExtensionDtype"]
 FilePathOrBuffer = Union[str, Path, IO[AnyStr]]
+# FrameOrSeries means either a DataFrame or a Series. E.g.
+# `def func(a: FrameOrSeries) -> FrameOrSeries: ...` means that if a Series is passed
+# in, either a Series or DataFrame is returned, and if a DataFrame is passed in, either
+# a DataFrame or a Series is returned.
 FrameOrSeries = Union["DataFrame", "Series"]
-FrameOrSeriesT = TypeVar("FrameOrSeriesT", bound="NDFrame")
+# SameFrameOrSeries is stricter and ensures that the same subclass of NDFrame always is
+# used. E.g. `def func(a: SameFrameOrSeries) -> SameFrameOrSeries: ...` means that if a
+# Series is passed into a function, a Series is always returned and if a DataFrame is
+# passed in, a DataFrame is always returned.
+SameFrameOrSeries = TypeVar("SameFrameOrSeries", bound="NDFrame")
 Axis = Union[str, int]
 Ordered = Optional[bool]
 JSONSerializable = Union[PythonScalar, List, Dict]

pandas/core/generic.py

@@ -30,7 +30,7 @@
 from pandas._config import config
 
 from pandas._libs import Timestamp, iNaT, lib, properties
-from pandas._typing import Dtype, FilePathOrBuffer, FrameOrSeriesT, JSONSerializable
+from pandas._typing import Dtype, FilePathOrBuffer, JSONSerializable, SameFrameOrSeries
 from pandas.compat import set_function_name
 from pandas.compat._optional import import_optional_dependency
 from pandas.compat.numpy import function as nv
@@ -552,12 +552,12 @@ def size(self):
         return np.prod(self.shape)
 
     @property
-    def _selected_obj(self: FrameOrSeriesT) -> FrameOrSeriesT:
+    def _selected_obj(self: SameFrameOrSeries) -> SameFrameOrSeries:
         """ internal compat with SelectionMixin """
         return self
 
     @property
-    def _obj_with_exclusions(self: FrameOrSeriesT) -> FrameOrSeriesT:
+    def _obj_with_exclusions(self: SameFrameOrSeries) -> SameFrameOrSeries:
         """ internal compat with SelectionMixin """
         return self
 
@@ -4670,7 +4670,7 @@ def f(x):
         else:
             raise TypeError("Must pass either `items`, `like`, or `regex`")
 
-    def head(self: FrameOrSeriesT, n: int = 5) -> FrameOrSeriesT:
+    def head(self: SameFrameOrSeries, n: int = 5) -> SameFrameOrSeries:
         """
         Return the first `n` rows.
 
@@ -4743,7 +4743,7 @@ def head(self: FrameOrSeriesT, n: int = 5) -> FrameOrSeriesT:
 
         return self.iloc[:n]
 
-    def tail(self: FrameOrSeriesT, n: int = 5) -> FrameOrSeriesT:
+    def tail(self: SameFrameOrSeries, n: int = 5) -> SameFrameOrSeries:
         """
         Return the last `n` rows.
 
@@ -5188,8 +5188,8 @@ def pipe(self, func, *args, **kwargs):
     # Attribute access
 
     def __finalize__(
-        self: FrameOrSeriesT, other, method=None, **kwargs
-    ) -> FrameOrSeriesT:
+        self: SameFrameOrSeries, other, method=None, **kwargs
+    ) -> SameFrameOrSeries:
         """
         Propagate metadata from other to self.
 
@@ -5658,7 +5658,7 @@ def astype(
         result.columns = self.columns
         return result
 
-    def copy(self: FrameOrSeriesT, deep: bool_t = True) -> FrameOrSeriesT:
+    def copy(self: SameFrameOrSeries, deep: bool_t = True) -> SameFrameOrSeries:
         """
         Make a copy of this object's indices and data.
 
@@ -5766,10 +5766,10 @@ def copy(self: FrameOrSeriesT, deep: bool_t = True) -> FrameOrSeriesT:
         data = self._data.copy(deep=deep)
         return self._constructor(data).__finalize__(self)
 
-    def __copy__(self: FrameOrSeriesT, deep: bool_t = True) -> FrameOrSeriesT:
+    def __copy__(self: SameFrameOrSeries, deep: bool_t = True) -> SameFrameOrSeries:
         return self.copy(deep=deep)
 
-    def __deepcopy__(self: FrameOrSeriesT, memo=None) -> FrameOrSeriesT:
+    def __deepcopy__(self: SameFrameOrSeries, memo=None) -> SameFrameOrSeries:
         """
         Parameters
         ----------
@@ -5779,13 +5779,13 @@ def __deepcopy__(self: FrameOrSeriesT, memo=None) -> FrameOrSeriesT:
         return self.copy(deep=True)
 
     def _convert(
-        self: FrameOrSeriesT,
+        self: SameFrameOrSeries,
         datetime: bool_t = False,
         numeric: bool_t = False,
         timedelta: bool_t = False,
         coerce: bool_t = False,
         copy: bool_t = True,
-    ) -> FrameOrSeriesT:
+    ) -> SameFrameOrSeries:
         """
         Attempt to infer better dtype for object columns
 
@@ -5877,14 +5877,14 @@ def infer_objects(self: FrameOrSeries) -> FrameOrSeries:
     # Filling NA's
 
     def fillna(
-        self: FrameOrSeriesT,
+        self: SameFrameOrSeries,
         value=None,
         method=None,
         axis=None,
         inplace: bool_t = False,
         limit=None,
         downcast=None,
-    ) -> Optional[FrameOrSeriesT]:
+    ) -> Optional[SameFrameOrSeries]:
         """
         Fill NA/NaN values using the specified method.
 
@@ -6066,12 +6066,12 @@ def fillna(
             return self._constructor(new_data).__finalize__(self)
 
     def ffill(
-        self: FrameOrSeriesT,
+        self: SameFrameOrSeries,
         axis=None,
         inplace: bool_t = False,
         limit=None,
         downcast=None,
-    ) -> Optional[FrameOrSeriesT]:
+    ) -> Optional[SameFrameOrSeries]:
         """
         Synonym for :meth:`DataFrame.fillna` with ``method='ffill'``.
 
@@ -6085,12 +6085,12 @@ def ffill(
         )
 
     def bfill(
-        self: FrameOrSeriesT,
+        self: SameFrameOrSeries,
         axis=None,
         inplace: bool_t = False,
         limit=None,
         downcast=None,
-    ) -> Optional[FrameOrSeriesT]:
+    ) -> Optional[SameFrameOrSeries]:
         """
         Synonym for :meth:`DataFrame.fillna` with ``method='bfill'``.
 
@@ -8055,14 +8055,14 @@ def last(self: FrameOrSeries, offset) -> FrameOrSeries:
         return self.iloc[start:]
 
     def rank(
-        self: FrameOrSeriesT,
+        self: SameFrameOrSeries,
         axis=0,
         method: str = "average",
         numeric_only: Optional[bool_t] = None,
         na_option: str = "keep",
         ascending: bool_t = True,
         pct: bool_t = False,
-    ) -> FrameOrSeriesT:
+    ) -> SameFrameOrSeries:
         """
         Compute numerical data ranks (1 through n) along axis.
 
@@ -8870,7 +8870,9 @@ def shift(
 
         return self._constructor(new_data).__finalize__(self)
 
-    def slice_shift(self: FrameOrSeriesT, periods: int = 1, axis=0) -> FrameOrSeriesT:
+    def slice_shift(
+        self: SameFrameOrSeries, periods: int = 1, axis=0
+    ) -> SameFrameOrSeries:
         """
         Equivalent to `shift` without copying data.
 
@@ -8970,8 +8972,8 @@ def tshift(
         return self._constructor(new_data).__finalize__(self)
 
     def truncate(
-        self: FrameOrSeriesT, before=None, after=None, axis=None, copy: bool_t = True
-    ) -> FrameOrSeriesT:
+        self: SameFrameOrSeries, before=None, after=None, axis=None, copy: bool_t = True
+    ) -> SameFrameOrSeries:
         """
         Truncate a Series or DataFrame before and after some index value.
 
@@ -9124,8 +9126,8 @@ def truncate(
         return result
 
     def tz_convert(
-        self: FrameOrSeriesT, tz, axis=0, level=None, copy: bool_t = True
-    ) -> FrameOrSeriesT:
+        self: SameFrameOrSeries, tz, axis=0, level=None, copy: bool_t = True
+    ) -> SameFrameOrSeries:
         """
         Convert tz-aware axis to target time zone.
 
@@ -9181,14 +9183,14 @@ def _tz_convert(ax, tz):
         return result.__finalize__(self)
 
     def tz_localize(
-        self: FrameOrSeriesT,
+        self: SameFrameOrSeries,
         tz,
         axis=0,
         level=None,
         copy: bool_t = True,
         ambiguous="raise",
         nonexistent: str = "raise",
-    ) -> FrameOrSeriesT:
+    ) -> SameFrameOrSeries:
         """
         Localize tz-naive index of a Series or DataFrame to target time zone.
 

pandas/core/groupby/generic.py

@@ -30,7 +30,7 @@
 import numpy as np
 
 from pandas._libs import Timestamp, lib
-from pandas._typing import FrameOrSeriesT
+from pandas._typing import SameFrameOrSeries
 from pandas.util._decorators import Appender, Substitution
 
 from pandas.core.dtypes.cast import (
@@ -86,7 +86,7 @@
 ScalarResult = typing.TypeVar("ScalarResult")
 
 
-def generate_property(name: str, klass: Type[FrameOrSeriesT]):
+def generate_property(name: str, klass: Type[SameFrameOrSeries]):
     """
     Create a property for a GroupBy subclass to dispatch to DataFrame/Series.
 
@@ -109,7 +109,9 @@ def prop(self):
     return property(prop)
 
 
-def pin_whitelisted_properties(klass: Type[FrameOrSeriesT], whitelist: FrozenSet[str]):
+def pin_whitelisted_properties(
+    klass: Type[SameFrameOrSeries], whitelist: FrozenSet[str]
+):
     """
     Create GroupBy member defs for DataFrame/Series names in a whitelist.
 

pandas/core/groupby/groupby.py

@@ -33,7 +33,7 @@ class providing the base-class of operations.
 
 from pandas._libs import Timestamp
 import pandas._libs.groupby as libgroupby
-from pandas._typing import FrameOrSeriesT, Scalar
+from pandas._typing import SameFrameOrSeries, Scalar
 from pandas.compat import set_function_name
 from pandas.compat.numpy import function as nv
 from pandas.errors import AbstractMethodError
@@ -2439,8 +2439,8 @@ def tail(self, n=5):
         return self._selected_obj[mask]
 
     def _reindex_output(
-        self, output: FrameOrSeriesT, fill_value: Scalar = np.NaN
-    ) -> FrameOrSeriesT:
+        self, output: SameFrameOrSeries, fill_value: Scalar = np.NaN
+    ) -> SameFrameOrSeries:
         """
         If we have categorical groupers, then we might want to make sure that
         we have a fully re-indexed output to the levels. This means expanding

pandas/core/groupby/grouper.py

@@ -7,7 +7,7 @@
 
 import numpy as np
 
-from pandas._typing import FrameOrSeriesT
+from pandas._typing import SameFrameOrSeries
 from pandas.util._decorators import cache_readonly
 
 from pandas.core.dtypes.common import (
@@ -141,7 +141,7 @@ def _get_grouper(self, obj, validate: bool = True):
         )
         return self.binner, self.grouper, self.obj
 
-    def _set_grouper(self, obj: FrameOrSeriesT, sort: bool = False):
+    def _set_grouper(self, obj: SameFrameOrSeries, sort: bool = False):
         """
         given an object and the specifications, setup the internal grouper
         for this particular specification
@@ -244,7 +244,7 @@ def __init__(
         self,
         index: Index,
         grouper=None,
-        obj: Optional[FrameOrSeriesT] = None,
+        obj: Optional[SameFrameOrSeries] = None,
         name=None,
         level=None,
         sort: bool = True,
@@ -424,15 +424,15 @@ def groups(self) -> Dict[Hashable, np.ndarray]:
 
 
 def get_grouper(
-    obj: FrameOrSeriesT,
+    obj: SameFrameOrSeries,
     key=None,
     axis: int = 0,
     level=None,
     sort: bool = True,
     observed: bool = False,
     mutated: bool = False,
     validate: bool = True,
-) -> "Tuple[ops.BaseGrouper, List[Hashable], FrameOrSeriesT]":
+) -> "Tuple[ops.BaseGrouper, List[Hashable], SameFrameOrSeries]":
     """
     Create and return a BaseGrouper, which is an internal
     mapping of how to create the grouper indexers.