enh: Start narwhals.stable.v2 and enforce deprecations (#2814)

Author: MarcoGorelli

.pre-commit-config.yaml

@@ -36,11 +36,11 @@ repos:
                 narwhals/dataframe\.py|
                 # TODO: gradually enable
                 narwhals/dependencies\.py|
-                # TODO: gradually enable
-                narwhals/stable/v1/dependencies\.py|
                 # private, so less urgent to document too well
                 narwhals/_.*|
-                ^utils/.*
+                ^utils/.*|
+                # Soft-deprecated, so less crucial to document so carefully
+                narwhals/stable/v1/.*
             )$
 - repo: local
   hooks:
@@ -69,15 +69,15 @@ repos:
             from\ narwhals\ import\ dtypes|
             from\ narwhals.dtypes\ import\ [^D_]+|
             import\ narwhals.stable.v1.dtypes|
-            from\ narwhals.stable.v1\ import\ dtypes|
-            from\ narwhals.stable.v1.dtypes\ import
+            from\ narwhals.stable\.v.\ import\ dtypes|
+            from\ narwhals.stable\.v.\.dtypes\ import
       language: pygrep
       files: ^narwhals/
       exclude: |
         (?x)
           ^(
             narwhals/_utils\.py|
-            narwhals/stable/v1/_dtypes.py|
+            narwhals/stable/v./_?dtypes.py|
             narwhals/.*__init__.py|
             narwhals/.*typing\.py
           )

docs/api-reference/expr.md

@@ -8,9 +8,6 @@
         - alias
         - all
         - any
-        - arg_max
-        - arg_min
-        - arg_true
         - cast
         - count
         - cum_count
@@ -24,8 +21,6 @@
         - exp
         - fill_null
         - filter
-        - gather_every
-        - head
         - clip
         - is_between
         - is_duplicated
@@ -57,14 +52,11 @@
         - rolling_sum
         - rolling_var
         - round
-        - sample
         - shift
-        - sort
         - skew
         - sqrt
         - std
         - sum
-        - tail
         - unique
         - var
       show_source: false

docs/api-reference/narwhals.md

@@ -19,7 +19,6 @@ Here are the top-level functions available in Narwhals.
         - from_native
         - from_numpy
         - generate_temporary_column_name
-        - get_level
         - get_native_namespace
         - is_ordered_categorical
         - len

narwhals/__init__.py

@@ -57,7 +57,6 @@
     from_arrow,
     from_dict,
     from_numpy,
-    get_level,
     len_ as len,
     lit,
     max,
@@ -141,7 +140,6 @@
     "from_native",
     "from_numpy",
     "generate_temporary_column_name",
-    "get_level",
     "get_native_namespace",
     "is_ordered_categorical",
     "len",

narwhals/_compliant/dataframe.py

@@ -22,7 +22,7 @@
     ToNarwhals,
     ToNarwhalsT_co,
 )
-from narwhals._typing_compat import assert_never, deprecated
+from narwhals._typing_compat import assert_never
 from narwhals._utils import (
     ValidateBackendVersion,
     Version,
@@ -312,10 +312,6 @@ def drop(self, columns: Sequence[str], *, strict: bool) -> Self: ...
     def drop_nulls(self, subset: Sequence[str] | None) -> Self: ...
     def explode(self, columns: Sequence[str]) -> Self: ...
     def filter(self, predicate: CompliantExprT_contra | Incomplete) -> Self: ...
-    @deprecated(
-        "`LazyFrame.gather_every` is deprecated and will be removed in a future version."
-    )
-    def gather_every(self, n: int, offset: int) -> Self: ...
     def group_by(
         self,
         keys: Sequence[str] | Sequence[CompliantExprT_contra],
@@ -349,8 +345,6 @@ def sink_parquet(self, file: str | Path | BytesIO) -> None: ...
     def sort(
         self, *by: str, descending: bool | Sequence[bool], nulls_last: bool
     ) -> Self: ...
-    @deprecated("`LazyFrame.tail` is deprecated and will be removed in a future version.")
-    def tail(self, n: int) -> Self: ...
     def unique(
         self, subset: Sequence[str] | None, *, keep: LazyUniqueKeepStrategy
     ) -> Self: ...

narwhals/_compliant/expr.py

@@ -27,7 +27,6 @@
     LazyExprT,
     NativeExprT,
 )
-from narwhals._typing_compat import deprecated
 from narwhals._utils import _StoresCompliant
 from narwhals.dependencies import get_numpy, is_numpy_array
 
@@ -107,9 +106,6 @@ def cast(self, dtype: IntoDType) -> Self: ...
     def count(self) -> Self: ...
     def min(self) -> Self: ...
     def max(self) -> Self: ...
-    def arg_min(self) -> Self: ...
-    def arg_max(self) -> Self: ...
-    def arg_true(self) -> Self: ...
     def mean(self) -> Self: ...
     def sum(self) -> Self: ...
     def median(self) -> Self: ...
@@ -134,8 +130,6 @@ def len(self) -> Self: ...
     def log(self, base: float) -> Self: ...
     def round(self, decimals: int) -> Self: ...
     def mode(self) -> Self: ...
-    def head(self, n: int) -> Self: ...
-    def tail(self, n: int) -> Self: ...
     def shift(self, n: int) -> Self: ...
     def is_finite(self) -> Self: ...
     def is_nan(self) -> Self: ...
@@ -148,7 +142,6 @@ def cum_min(self, *, reverse: bool) -> Self: ...
     def cum_max(self, *, reverse: bool) -> Self: ...
     def cum_prod(self, *, reverse: bool) -> Self: ...
     def is_in(self, other: Any) -> Self: ...
-    def sort(self, *, descending: bool, nulls_last: bool) -> Self: ...
     def rank(self, method: RankMethod, *, descending: bool) -> Self: ...
     def replace_strict(
         self,
@@ -158,14 +151,6 @@ def replace_strict(
         return_dtype: IntoDType | None,
     ) -> Self: ...
     def over(self, partition_by: Sequence[str], order_by: Sequence[str]) -> Self: ...
-    def sample(
-        self,
-        n: int | None,
-        *,
-        fraction: float | None,
-        with_replacement: bool,
-        seed: int | None,
-    ) -> Self: ...
     def quantile(
         self, quantile: float, interpolation: RollingInterpolationMethod
     ) -> Self: ...
@@ -209,8 +194,6 @@ def rolling_std(
         self, window_size: int, *, min_samples: int, center: bool, ddof: int
     ) -> Self: ...
 
-    @deprecated("Since `1.22.0`")
-    def gather_every(self, n: int, offset: int) -> Self: ...
     def __and__(self, other: Any) -> Self: ...
     def __or__(self, other: Any) -> Self: ...
     def __add__(self, other: Any) -> Self: ...

narwhals/_utils.py

@@ -217,6 +217,7 @@ def _validate_backend_version(self) -> None:
 
 class Version(Enum):
     V1 = auto()
+    V2 = auto()
     MAIN = auto()
 
     @property
@@ -225,6 +226,10 @@ def namespace(self) -> type[Namespace[Any]]:
             from narwhals.stable.v1._namespace import Namespace as NamespaceV1
 
             return NamespaceV1
+        if self is Version.V2:
+            from narwhals.stable.v2._namespace import Namespace as NamespaceV2
+
+            return NamespaceV2
         from narwhals._namespace import Namespace
 
         return Namespace
@@ -235,6 +240,10 @@ def dtypes(self) -> DTypes:
             from narwhals.stable.v1 import dtypes as dtypes_v1
 
             return dtypes_v1
+        if self is Version.V2:
+            from narwhals.stable.v2 import dtypes as dtypes_v2
+
+            return dtypes_v2
         from narwhals import dtypes
 
         return dtypes
@@ -245,6 +254,10 @@ def dataframe(self) -> type[DataFrame[Any]]:
             from narwhals.stable.v1 import DataFrame as DataFrameV1
 
             return DataFrameV1
+        if self is Version.V2:
+            from narwhals.stable.v2 import DataFrame as DataFrameV2
+
+            return DataFrameV2
         from narwhals.dataframe import DataFrame
 
         return DataFrame
@@ -255,6 +268,10 @@ def lazyframe(self) -> type[LazyFrame[Any]]:
             from narwhals.stable.v1 import LazyFrame as LazyFrameV1
 
             return LazyFrameV1
+        if self is Version.V2:
+            from narwhals.stable.v2 import LazyFrame as LazyFrameV2
+
+            return LazyFrameV2
         from narwhals.dataframe import LazyFrame
 
         return LazyFrame
@@ -265,6 +282,10 @@ def series(self) -> type[Series[Any]]:
             from narwhals.stable.v1 import Series as SeriesV1
 
             return SeriesV1
+        if self is Version.V2:
+            from narwhals.stable.v2 import Series as SeriesV2
+
+            return SeriesV2
         from narwhals.series import Series
 
         return Series
@@ -1452,7 +1473,7 @@ def find_stacklevel() -> int:
     return n
 
 
-def issue_deprecation_warning(message: str, _version: str) -> None:
+def issue_deprecation_warning(message: str, _version: str) -> None:  # pragma: no cover
     """Issue a deprecation warning.
 
     Arguments:
@@ -1477,18 +1498,10 @@ def validate_strict_and_pass_though(
     pass_through: bool | None,  # noqa: FBT001
     *,
     pass_through_default: bool,
-    emit_deprecation_warning: bool,
 ) -> bool:
     if strict is None and pass_through is None:
         pass_through = pass_through_default
     elif strict is not None and pass_through is None:
-        if emit_deprecation_warning:
-            msg = (
-                "`strict` in `from_native` is deprecated, please use `pass_through` instead.\n\n"
-                "Note: `strict` will remain available in `narwhals.stable.v1`.\n"
-                "See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.\n"
-            )
-            issue_deprecation_warning(msg, _version="1.13.0")
         pass_through = not strict
     elif strict is None and pass_through is not None:
         pass

narwhals/dataframe.py

@@ -34,7 +34,6 @@
     is_list_of,
     is_sequence_like,
     is_slice_none,
-    issue_deprecation_warning,
     issue_performance_warning,
     supports_arrow_c_stream,
 )
@@ -2867,22 +2866,6 @@ def head(self, n: int = 5) -> Self:
         """
         return super().head(n)
 
-    def tail(self, n: int = 5) -> Self:  # pragma: no cover
-        r"""Get the last `n` rows.
-
-        Warning:
-            `LazyFrame.tail` is deprecated and will be removed in a future version.
-            Note: this will remain available in `narwhals.stable.v1`.
-            See [stable api](../backcompat.md/) for more information.
-
-        Arguments:
-            n: Number of rows to return.
-
-        Returns:
-            A subset of the LazyFrame of shape (n, n_columns).
-        """
-        return super().tail(n)
-
     def drop(self, *columns: str | Iterable[str], strict: bool = True) -> Self:
         r"""Remove columns from the LazyFrame.
 
@@ -3359,30 +3342,6 @@ def lazy(self) -> Self:
         """
         return self
 
-    def gather_every(self, n: int, offset: int = 0) -> Self:
-        r"""Take every nth row in the DataFrame and return as a new DataFrame.
-
-        Warning:
-            `LazyFrame.gather_every` is deprecated and will be removed in a future version.
-            Note: this will remain available in `narwhals.stable.v1`.
-            See [stable api](../backcompat.md/) for more information.
-
-        Arguments:
-            n: Gather every *n*-th row.
-            offset: Starting index.
-
-        Returns:
-            The LazyFrame containing only the selected rows.
-        """
-        msg = (
-            "`LazyFrame.gather_every` is deprecated and will be removed in a future version.\n\n"
-            "Note: this will remain available in `narwhals.stable.v1`.\n"
-            "See https://narwhals-dev.github.io/narwhals/backcompat/ for more information.\n"
-        )
-        issue_deprecation_warning(msg, _version="1.29.0")
-
-        return super().gather_every(n=n, offset=offset)
-
     def unpivot(
         self,
         on: str | list[str] | None = None,