chore: Support @requires.backend_version in namespaces

narwhals/_arrow/series_cat.py

@@ -5,13 +5,14 @@
 import pyarrow as pa
 
 from narwhals._arrow.utils import ArrowSeriesNamespace
+from narwhals._compliant.any_namespace import CatNamespace
 
 if TYPE_CHECKING:
     from narwhals._arrow.series import ArrowSeries
     from narwhals._arrow.typing import Incomplete
 
 
-class ArrowSeriesCatNamespace(ArrowSeriesNamespace):
+class ArrowSeriesCatNamespace(ArrowSeriesNamespace, CatNamespace["ArrowSeries"]):
     def get_categories(self) -> ArrowSeries:
         # NOTE: Should be `list[pa.DictionaryArray]`, but `DictionaryArray` has no attributes
         chunks: Incomplete = self.native.chunks

narwhals/_arrow/series_dt.py

@@ -6,6 +6,7 @@
 import pyarrow.compute as pc
 
 from narwhals._arrow.utils import UNITS_DICT, ArrowSeriesNamespace, floordiv_compat, lit
+from narwhals._compliant.any_namespace import DateTimeNamespace
 from narwhals._constants import (
     MS_PER_MINUTE,
     MS_PER_SECOND,
@@ -36,7 +37,9 @@
     IntoRhs: TypeAlias = int
 
 
-class ArrowSeriesDateTimeNamespace(ArrowSeriesNamespace):
+class ArrowSeriesDateTimeNamespace(
+    ArrowSeriesNamespace, DateTimeNamespace["ArrowSeries"]
+):
     _TIMESTAMP_DATE_FACTOR: ClassVar[Mapping[TimeUnit, int]] = {
         "ns": NS_PER_SECOND,
         "us": US_PER_SECOND,

narwhals/_arrow/series_list.py

@@ -6,19 +6,19 @@
 import pyarrow.compute as pc
 
 from narwhals._arrow.utils import ArrowSeriesNamespace
+from narwhals._compliant.any_namespace import ListNamespace
 from narwhals._utils import not_implemented
 
 if TYPE_CHECKING:
     from narwhals._arrow.series import ArrowSeries
 
 
-class ArrowSeriesListNamespace(ArrowSeriesNamespace):
+class ArrowSeriesListNamespace(ArrowSeriesNamespace, ListNamespace["ArrowSeries"]):
     def len(self) -> ArrowSeries:
         return self.with_native(pc.list_value_length(self.native).cast(pa.uint32()))
 
-    unique = not_implemented()
-
-    contains = not_implemented()
-
     def get(self, index: int) -> ArrowSeries:
         return self.with_native(pc.list_element(self.native, index))
+
+    unique = not_implemented()
+    contains = not_implemented()

narwhals/_arrow/series_str.py

@@ -7,13 +7,14 @@
 import pyarrow.compute as pc
 
 from narwhals._arrow.utils import ArrowSeriesNamespace, lit, parse_datetime_format
+from narwhals._compliant.any_namespace import StringNamespace
 
 if TYPE_CHECKING:
     from narwhals._arrow.series import ArrowSeries
     from narwhals._arrow.typing import Incomplete
 
 
-class ArrowSeriesStringNamespace(ArrowSeriesNamespace):
+class ArrowSeriesStringNamespace(ArrowSeriesNamespace, StringNamespace["ArrowSeries"]):
     def len_chars(self) -> ArrowSeries:
         return self.with_native(pc.utf8_length(self.native))
 

narwhals/_arrow/series_struct.py

@@ -5,11 +5,12 @@
 import pyarrow.compute as pc
 
 from narwhals._arrow.utils import ArrowSeriesNamespace
+from narwhals._compliant.any_namespace import StructNamespace
 
 if TYPE_CHECKING:
     from narwhals._arrow.series import ArrowSeries
 
 
-class ArrowSeriesStructNamespace(ArrowSeriesNamespace):
+class ArrowSeriesStructNamespace(ArrowSeriesNamespace, StructNamespace["ArrowSeries"]):
     def field(self, name: str) -> ArrowSeries:
         return self.with_native(pc.struct_field(self.native, name)).alias(name)

narwhals/_compliant/any_namespace.py

@@ -2,30 +2,40 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING, ClassVar, Protocol
 
 from narwhals._utils import CompliantT_co, _StoresCompliant
 
 if TYPE_CHECKING:
     from typing import Callable
 
+    from narwhals._compliant.typing import Accessor
     from narwhals.typing import NonNestedLiteral, TimeUnit
 
 __all__ = [
     "CatNamespace",
     "DateTimeNamespace",
     "ListNamespace",
     "NameNamespace",
+    "NamespaceAccessor",
     "StringNamespace",
     "StructNamespace",
 ]
 
 
-class CatNamespace(_StoresCompliant[CompliantT_co], Protocol[CompliantT_co]):
+class NamespaceAccessor(_StoresCompliant[CompliantT_co], Protocol[CompliantT_co]):
+    _accessor: ClassVar[Accessor]
+
+
+class CatNamespace(NamespaceAccessor[CompliantT_co], Protocol[CompliantT_co]):
+    _accessor: ClassVar[Accessor] = "cat"
+
     def get_categories(self) -> CompliantT_co: ...
 
 
 class DateTimeNamespace(_StoresCompliant[CompliantT_co], Protocol[CompliantT_co]):
+    _accessor: ClassVar[Accessor] = "dt"
+
     def to_string(self, format: str) -> CompliantT_co: ...
     def replace_time_zone(self, time_zone: str | None) -> CompliantT_co: ...
     def convert_time_zone(self, time_zone: str) -> CompliantT_co: ...
@@ -52,15 +62,17 @@ def offset_by(self, by: str) -> CompliantT_co: ...
 
 
 class ListNamespace(_StoresCompliant[CompliantT_co], Protocol[CompliantT_co]):
-    def get(self, index: int) -> CompliantT_co: ...
+    _accessor: ClassVar[Accessor] = "list"
 
+    def get(self, index: int) -> CompliantT_co: ...
     def len(self) -> CompliantT_co: ...
-
     def unique(self) -> CompliantT_co: ...
     def contains(self, item: NonNestedLiteral) -> CompliantT_co: ...
 
 
 class NameNamespace(_StoresCompliant[CompliantT_co], Protocol[CompliantT_co]):
+    _accessor: ClassVar[Accessor] = "name"
+
     def keep(self) -> CompliantT_co: ...
     def map(self, function: Callable[[str], str]) -> CompliantT_co: ...
     def prefix(self, prefix: str) -> CompliantT_co: ...
@@ -70,6 +82,8 @@ def to_uppercase(self) -> CompliantT_co: ...
 
 
 class StringNamespace(_StoresCompliant[CompliantT_co], Protocol[CompliantT_co]):
+    _accessor: ClassVar[Accessor] = "str"
+
     def len_chars(self) -> CompliantT_co: ...
     def replace(
         self, pattern: str, value: str, *, literal: bool, n: int
@@ -91,4 +105,6 @@ def zfill(self, width: int) -> CompliantT_co: ...
 
 
 class StructNamespace(_StoresCompliant[CompliantT_co], Protocol[CompliantT_co]):
+    _accessor: ClassVar[Accessor] = "struct"
+
     def field(self, name: str) -> CompliantT_co: ...

narwhals/_compliant/typing.py

@@ -204,3 +204,8 @@ class ScalarKwargs(TypedDict, total=False):
 - https://github.com/narwhals-dev/narwhals/issues/2526
 - https://github.com/narwhals-dev/narwhals/issues/2660
 """
+
+Accessor: TypeAlias = Literal[
+    "arr", "cat", "dt", "list", "meta", "name", "str", "bin", "struct"
+]
+"""`{Expr,Series}` method namespace accessor name."""

narwhals/_polars/expr.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any, Callable, Literal
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Literal
 
 import polars as pl
 
@@ -22,6 +22,7 @@
 
     from typing_extensions import Self
 
+    from narwhals._compliant.typing import Accessor
     from narwhals._expression_parsing import ExprKind, ExprMetadata
     from narwhals._polars.dataframe import Method
     from narwhals._polars.namespace import PolarsNamespace
@@ -400,17 +401,11 @@ class PolarsExprDateTimeNamespace(
 class PolarsExprStringNamespace(
     PolarsExprNamespace, PolarsStringNamespace[PolarsExpr, pl.Expr]
 ):
+    @requires.backend_version((0, 20, 5))
     def zfill(self, width: int) -> PolarsExpr:
         backend_version = self.compliant._backend_version
         native_result = self.native.str.zfill(width)
 
-        if backend_version < (0, 20, 5):  # pragma: no cover
-            # Reason:
-            # `TypeError: argument 'length': 'Expr' object cannot be interpreted as an integer`
-            # in `native_expr.str.slice(1, length)`
-            msg = "`zfill` is only available in 'polars>=0.20.5', found version '0.20.4'."
-            raise NotImplementedError(msg)
-
         if backend_version <= (1, 30, 0):
             length = self.native.str.len_chars()
             less_than_width = length < width
@@ -435,7 +430,7 @@ class PolarsExprCatNamespace(
 
 
 class PolarsExprNameNamespace(PolarsExprNamespace):
-    _accessor = "name"
+    _accessor: ClassVar[Accessor] = "name"
     keep: Method[PolarsExpr]
     map: Method[PolarsExpr]
     prefix: Method[PolarsExpr]

narwhals/_polars/typing.py

@@ -1,25 +1,10 @@
 from __future__ import annotations  # pragma: no cover
 
-from typing import (
-    TYPE_CHECKING,  # pragma: no cover
-    Union,  # pragma: no cover
-)
+from typing import TYPE_CHECKING  # pragma: no cover
 
 if TYPE_CHECKING:
-    import sys
-    from typing import Literal, TypeVar
-
-    if sys.version_info >= (3, 10):
-        from typing import TypeAlias
-    else:
-        from typing_extensions import TypeAlias
+    from typing import TypeVar
 
     from narwhals._polars.dataframe import PolarsDataFrame, PolarsLazyFrame
-    from narwhals._polars.expr import PolarsExpr
-    from narwhals._polars.series import PolarsSeries
 
-    IntoPolarsExpr: TypeAlias = Union[PolarsExpr, PolarsSeries]
     FrameT = TypeVar("FrameT", PolarsDataFrame, PolarsLazyFrame)
-    NativeAccessor: TypeAlias = Literal[
-        "arr", "cat", "dt", "list", "meta", "name", "str", "bin", "struct"
-    ]

narwhals/_polars/utils.py

@@ -30,10 +30,10 @@
 
     from typing_extensions import TypeIs
 
+    from narwhals._compliant.typing import Accessor
     from narwhals._polars.dataframe import Method
     from narwhals._polars.expr import PolarsExpr
     from narwhals._polars.series import PolarsSeries
-    from narwhals._polars.typing import NativeAccessor
     from narwhals.dtypes import DType
     from narwhals.typing import IntoDType
 
@@ -261,7 +261,7 @@ class PolarsAnyNamespace(
     _StoresNative[NativeT_co],
     Protocol[CompliantT_co, NativeT_co],
 ):
-    _accessor: ClassVar[NativeAccessor]
+    _accessor: ClassVar[Accessor]
 
     def __getattr__(self, attr: str) -> Callable[..., CompliantT_co]:
         def func(*args: Any, **kwargs: Any) -> CompliantT_co:
@@ -273,7 +273,7 @@ def func(*args: Any, **kwargs: Any) -> CompliantT_co:
 
 
 class PolarsDateTimeNamespace(PolarsAnyNamespace[CompliantT, NativeT_co]):
-    _accessor: ClassVar[NativeAccessor] = "dt"
+    _accessor: ClassVar[Accessor] = "dt"
 
     def truncate(self, every: str) -> CompliantT:
         # Ensure consistent error message is raised.
@@ -309,7 +309,7 @@ def offset_by(self, by: str) -> CompliantT:
 
 
 class PolarsStringNamespace(PolarsAnyNamespace[CompliantT, NativeT_co]):
-    _accessor: ClassVar[NativeAccessor] = "str"
+    _accessor: ClassVar[Accessor] = "str"
 
     # NOTE: Use `abstractmethod` if we have defs to implement, but also `Method` usage
     @abc.abstractmethod
@@ -331,12 +331,12 @@ def zfill(self, width: int) -> CompliantT: ...
 
 
 class PolarsCatNamespace(PolarsAnyNamespace[CompliantT, NativeT_co]):
-    _accessor: ClassVar[NativeAccessor] = "cat"
+    _accessor: ClassVar[Accessor] = "cat"
     get_categories: Method[CompliantT]
 
 
 class PolarsListNamespace(PolarsAnyNamespace[CompliantT, NativeT_co]):
-    _accessor: ClassVar[NativeAccessor] = "list"
+    _accessor: ClassVar[Accessor] = "list"
 
     @abc.abstractmethod
     def len(self) -> CompliantT: ...
@@ -347,5 +347,5 @@ def len(self) -> CompliantT: ...
 
 
 class PolarsStructNamespace(PolarsAnyNamespace[CompliantT, NativeT_co]):
-    _accessor: ClassVar[NativeAccessor] = "struct"
+    _accessor: ClassVar[Accessor] = "struct"
     field: Method[CompliantT]