Merge branch 'main' into df-repr-html

Author: dangotbanned

.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/dataframe.md

@@ -14,6 +14,9 @@
         - estimated_size
         - explode
         - filter
+        - from_arrow
+        - from_dict
+        - from_numpy
         - gather_every
         - get_column
         - group_by

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

docs/backcompat.md

@@ -3,14 +3,15 @@
 Narwhals is primarily aimed at library maintainers rather than end users. As such,
 we need to take stability and backwards compatibility extra-seriously. Our policy is:
 
-- If you write code using `import narwhals.stable.v1 as nw`, then we promise to
+- If you write code using `narwhals.stable.v1` or `import narwhals.stable.v2`, then we promise to
   never change or remove any public function you're using.
 - If we need to make a backwards-incompatible change, it will be pushed into
-  `narwhals.stable.v2`, leaving `narwhals.stable.v1` unaffected.
-- We will maintain `narwhals.stable.v1` indefinitely, even as `narwhals.stable.v2` and other
-  stable APIs come out. For example, Narwhals version 1.0.0 will offer
-  `narwhals.stable.v1`, whereas Narwhals 2.0.0 will offer both `narwhals.stable.v1` and
-  `narwhals.stable.v2`.
+  the main `narwhals` namespace (and eventually `narwhals.stable.v3`),
+  leaving `narwhals.stable.v1` and `narwhals.stable.v2` unaffected.
+- We will maintain `narwhals.stable.v1` and `narwhals.stable.v2` indefinitely,
+  even as `narwhals.stable.v3` and other stable APIs come out. For example,
+  Narwhals version 1.0.0 offers `narwhals.stable.v1`, whereas Narwhals 2.0.0 offers
+  both `narwhals.stable.v1` and `narwhals.stable.v2`.
 
 Like this, we enable different packages to be on different Narwhals stable APIs, and for
 end-users to use all of them in the same project without conflicts nor
@@ -49,8 +50,8 @@ it. That is to say, if you write your code like this:
 
 === "from/to_native"
     ```python
-    import narwhals.stable.v1 as nw
-    from narwhals.typing import IntoFrameT
+    import narwhals.stable.v2 as nw
+    from narwhals.stable.v2.typing import IntoFrameT
 
 
     def func(df: IntoFrameT) -> IntoFrameT:
@@ -59,8 +60,8 @@ it. That is to say, if you write your code like this:
 
 === "@narwhalify"
     ```python
-    import narwhals.stable.v1 as nw
-    from narwhals.typing import FrameT
+    import narwhals.stable.v2 as nw
+    from narwhals.stable.v2.typing import FrameT
 
 
     @nw.narwhalify
@@ -73,18 +74,19 @@ after they have renamed their method.
 
 Concretely, we would do the following:
 
-- `narwhals.stable.v1`: you can keep using `Expr.cum_sum`
-- `narwhals.stable.v2`: you can only use `Expr.cumulative_sum`, `Expr.cum_sum` will have been removed
+- `narwhals.stable.v2`: you can keep using `Expr.cum_sum`
+- `narwhals.stable.v3`: you can only use `Expr.cumulative_sum`, `Expr.cum_sum` will have been removed
 - `narwhals`:  you can only use `Expr.cumulative_sum`, `Expr.cum_sum` will have been removed
 
-So, although Narwhals' main API (and `narwhals.stable.v2`) will have introduced a breaking change,
-users of `narwhals.stable.v1` will have their code unaffected.
+So, although Narwhals' main API (and `narwhals.stable.v3`) will have introduced a breaking change,
+users of `narwhals.stable.v2` will have their code unaffected.
 
 ### Exceptions
 
 Are we really promising perfect backwards compatibility in all cases, without exceptions? Not quite.
 There are some exceptions, which we'll now list. But we'll never intentionally break your code.
-Anything currently in `narwhals.stable.v1` will not be changed or removed in future Narwhals versions.
+Anything currently in `narwhals.stable.v1` or `narwhals.stable.v2` will not be changed or removed
+in future Narwhals versions.
 
 Here are exceptions to our backwards compatibility policy:
 
@@ -100,16 +102,24 @@ Here are exceptions to our backwards compatibility policy:
 In general, decision are driven by use-cases, and we conduct a search of public GitHub repositories
 before making any change.
 
-
-### `import narwhals as nw` or `import narwhals.stable.v1 as nw`?
+### `import narwhals as nw`, `import narwhals.stable.v2 as nw`, or `import narwhals.stable.v1 as nw`?
 
 Which should you use? In general we recommend:
 
 - When prototyping, use `import narwhals as nw`, so you can iterate quickly.
 - Once you're happy with what you've got and want to release something production-ready and stable,
-  then switch out your `import narwhals as nw` usage for `import narwhals.stable.v1 as nw`.
+  then switch out your `import narwhals as nw` usage for `import narwhals.stable.v2 as nw`.
+- If you're starting a new project, use either the main Narwhals namespace or `narwhals.stable.v2`.
+- If your project is already using `narwhals.stable.v1`, and you don't need any of the newer Narwhals
+  features, there's probably no need to switch to `narwhals.stable.v2`, as that would require you to
+  raise the minimum version of Narwhals you support. If you'd like to use `narwhals.stable.v2`, make
+  sure to require at least `narwhals>=2.0`.
+
+## `main` vs `stable.v2` differences
 
-## `main` vs `stable.v1`
+So far, nothing, everything non-unstable from the main namespace should be available in `narwhals.stable.v2`.
+
+## `main` vs `stable.v1` differences
 
 - Since Narwhals 1.49:
 
@@ -133,6 +143,9 @@ Which should you use? In general we recommend:
 
 - Since Narwhals 1.29.0, `LazyFrame.gather_every` has been deprecated from the main namespace.
 
+- Since Narwhals 1.25.0, `native_namespace` is generally deprecated across the API. Please
+  use `backend` instead.
+
 - Since Narwhals 1.24.1, an empty or all-null object-dtype pandas Series is inferred to
   be of dtype `String`. Previously, it would have been inferred as `Object`.
 

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",