disallow .str on certain series types

Author: Dr-Irv

pandas-stubs/core/frame.pyi

@@ -44,7 +44,10 @@ from pandas.core.indexing import (
     _LocIndexer,
 )
 from pandas.core.interchange.dataframe_protocol import DataFrame as DataFrameXchg
-from pandas.core.series import Series
+from pandas.core.series import (
+    Series,
+    UnknownSeries,
+)
 from pandas.core.window import (
     Expanding,
     ExponentialMovingWindow,
@@ -244,24 +247,24 @@ class _LocIndexerFrame(_LocIndexer, Generic[_T]):
 if sys.version_info >= (3, 12):
     class _GetItemHack:
         @overload
-        def __getitem__(self, key: Scalar | tuple[Hashable, ...]) -> Series: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
+        def __getitem__(self, key: Scalar | tuple[Hashable, ...]) -> UnknownSeries: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
         @overload
         def __getitem__(  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
             self, key: Iterable[Hashable] | slice
         ) -> Self: ...
         @overload
-        def __getitem__(self, key: Hashable) -> Series: ...
+        def __getitem__(self, key: Hashable) -> UnknownSeries: ...
 
 else:
     class _GetItemHack:
         @overload
-        def __getitem__(self, key: Scalar | tuple[Hashable, ...]) -> Series: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
+        def __getitem__(self, key: Scalar | tuple[Hashable, ...]) -> UnknownSeries: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
         @overload
         def __getitem__(  # pyright: ignore[reportOverlappingOverload]
             self, key: Iterable[Hashable] | slice
         ) -> Self: ...
         @overload
-        def __getitem__(self, key: Hashable) -> Series: ...
+        def __getitem__(self, key: Hashable) -> UnknownSeries: ...
 
 class DataFrame(NDFrame, OpsMixin, _GetItemHack):
 

pandas-stubs/core/series.pyi

@@ -231,6 +231,54 @@ class _LocIndexerSeries(_LocIndexer, Generic[S1]):
         value: S1 | ArrayLike | Series[S1] | None,
     ) -> None: ...
 
+class _StrMethods:
+    @overload
+    def __get__(self, instance: Series[str], owner: Any) -> StringMethods[
+        Series[str],
+        DataFrame,
+        Series[bool],
+        Series[list[str]],
+        Series[int],
+        Series[bytes],
+        Series[str],
+        Series[type[object]],
+    ]: ...
+    @overload
+    def __get__(self, instance: Series[bytes], owner: Any) -> StringMethods[
+        Series[bytes],
+        DataFrame,
+        Series[bool],
+        Series[list[str]],
+        Series[int],
+        Series[bytes],
+        Series[str],
+        Series[type[object]],
+    ]: ...
+    @overload
+    def __get__(self, instance: Series[list[str]], owner: Any) -> StringMethods[
+        Series[list[str]],
+        DataFrame,
+        Series[bool],
+        Series[list[str]],
+        Series[int],
+        Series[bytes],
+        Series[str],
+        Series[type[object]],
+    ]: ...
+    @overload
+    def __get__(self, instance: Series[S1], owner: Any) -> NoReturn: ...
+    @overload
+    def __get__(self, instance: UnknownSeries, owner: Any) -> StringMethods[
+        Series,
+        DataFrame,
+        Series[bool],
+        Series[list[str]],
+        Series[int],
+        Series[bytes],
+        Series[str],
+        Series[type[object]],
+    ]: ...
+
 _ListLike: TypeAlias = (
     ArrayLike | dict[_str, np.ndarray] | Sequence[S1] | IndexOpsMixin[S1]
 )
@@ -1153,19 +1201,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
         copy: _bool = ...,
     ) -> Series[S1]: ...
     def to_period(self, freq: _str | None = ..., copy: _bool = ...) -> DataFrame: ...
-    @property
-    def str(
-        self,
-    ) -> StringMethods[
-        Self,
-        DataFrame,
-        Series[bool],
-        Series[list[str]],
-        Series[int],
-        Series[bytes],
-        Series[str],
-        Series[type[object]],
-    ]: ...
+    str: _StrMethods
     @property
     def dt(self) -> CombinedDatetimelikeProperties: ...
     @property

tests/test_string_accessors.py

@@ -6,7 +6,10 @@
 import pandas as pd
 from typing_extensions import assert_type
 
-from tests import check
+from tests import (
+    TYPE_CHECKING_INVALID_USAGE,
+    check,
+)
 
 # Separately define here so pytest works
 np_ndarray_bool = npt.NDArray[np.bool_]
@@ -139,7 +142,7 @@ def test_string_accessors_string_series():
     _check(assert_type(s.str.zfill(10), "pd.Series[str]"))
     s_bytes = pd.Series([b"a1", b"b2", b"c3"])
     _check(assert_type(s_bytes.str.decode("utf-8"), "pd.Series[str]"))
-    s_list = pd.Series([["apple", "banana"], ["cherry", "date"], [1, "eggplant"]])
+    s_list = pd.Series([["apple", "banana"], ["cherry", "date"], ["foo", "eggplant"]])
     _check(assert_type(s_list.str.join("-"), "pd.Series[str]"))
 
 
@@ -415,3 +418,10 @@ def test_index_overloads_extract():
         pd.Index,
         object,
     )
+
+
+def test_series_unknown():
+    if TYPE_CHECKING_INVALID_USAGE:
+        s = pd.Series([1, 2, 3])
+        s.str.startswith("a")  # type:ignore[attr-defined]
+        s.str.slice(2, 4)  # type:ignore[attr-defined]