Repository: narwhals-dev/narwhals
Pull request #1310 (2024-11-03 09:54:17)

fix: consistent naming of positional arguments in from_native
technically breaking, but in practice, from:
- https://github.com/search?q=%22nw.from_native%28native_dataframe%3D%22&type=code
- https://github.com/search?q=%22nw.from_native(%22&type=code

it looks like this affects _zero_ public repositories. People just pass this argument in positionally. We might as well just make the change now then, so as to limit the stable.v1 vs main namespace differences

<!--
# Thanks for contributing a pull request! 
## Please make sure you see our contribution guidelines: https://github.com/narwhals-dev/narwhals/blob/main/CONTRIBUTING.md
-->

## What type of PR is this? (check all applicable)

- [ ] 💾 Refactor
- [ ] ✨ Feature
- [ ] 🐛 Bug Fix
- [ ] 🔧 Optimization
- [ ] 📝 Documentation
- [ ] ✅ Test
- [ ] 🐳 Other

## Related issues 

- Related issue # 
- Closes #

## Checklist

- [ ] Code follows style guide (ruff)
- [ ] Tests added 
- [ ] Documented the changes

## If you have comments or can explain your changes, please do so below.




Patch:
diff --git a/docs/backcompat.md b/docs/backcompat.md
index 13c3cda8..2090eae7 100644
--- a/docs/backcompat.md
+++ b/docs/backcompat.md
@@ -92,6 +92,9 @@ Here are exceptions to our backwards compatibility policy:
   need to rethink Narwhals. However, we expect such radical changes to be exceedingly unlikely.
 - we may consider making some type hints more precise.
 
+In general, decision are driven by use-cases, and we conduct a search of public GitHub repositories
+before making any change.
+
 ## Breaking changes carried out so far
 
 ### After `stable.v1`
@@ -120,19 +123,3 @@ Here are exceptions to our backwards compatibility policy:
     assert nw.Datetime("us") == nw.Datetime
     assert nw_v1.Datetime("us") == nw_v1.Datetime
     ```
-
-- The first argument to `from_native` has been renamed from `native_dataframe` to `native_object`:
-
-    ```python
-    # v1 syntax:
-    nw.from_native(native_dataframe=df)  # people tend to write this
-    # main namespace syntax:
-    nw.from_native(native_object=df)
-    ```
-
-    In practice, we recommend passing this argument positionally, and that will work consistently
-    across namespaces:
-    ```python
-    # Recommended
-    nw.from_native(df)
-    ```
diff --git a/narwhals/stable/v1/__init__.py b/narwhals/stable/v1/__init__.py
index 68aca770..5bc762dd 100644
--- a/narwhals/stable/v1/__init__.py
+++ b/narwhals/stable/v1/__init__.py
@@ -577,7 +577,7 @@ def _stableify(
 
 @overload
 def from_native(
-    native_dataframe: IntoDataFrameT | IntoSeriesT,
+    native_object: IntoDataFrameT | IntoSeriesT,
     *,
     strict: Literal[False],
     eager_only: None = ...,
@@ -589,7 +589,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoDataFrameT | IntoSeriesT,
+    native_object: IntoDataFrameT | IntoSeriesT,
     *,
     strict: Literal[False],
     eager_only: Literal[True],
@@ -601,7 +601,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoDataFrameT,
+    native_object: IntoDataFrameT,
     *,
     strict: Literal[False],
     eager_only: None = ...,
@@ -613,7 +613,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: T,
+    native_object: T,
     *,
     strict: Literal[False],
     eager_only: None = ...,
@@ -625,7 +625,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoDataFrameT,
+    native_object: IntoDataFrameT,
     *,
     strict: Literal[False],
     eager_only: Literal[True],
@@ -637,7 +637,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: T,
+    native_object: T,
     *,
     strict: Literal[False],
     eager_only: Literal[True],
@@ -649,7 +649,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoFrameT | IntoSeriesT,
+    native_object: IntoFrameT | IntoSeriesT,
     *,
     strict: Literal[False],
     eager_only: None = ...,
@@ -661,7 +661,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoSeriesT,
+    native_object: IntoSeriesT,
     *,
     strict: Literal[False],
     eager_only: None = ...,
@@ -673,7 +673,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoFrameT,
+    native_object: IntoFrameT,
     *,
     strict: Literal[False],
     eager_only: None = ...,
@@ -685,7 +685,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: T,
+    native_object: T,
     *,
     strict: Literal[False],
     eager_only: None = ...,
@@ -697,7 +697,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoDataFrameT,
+    native_object: IntoDataFrameT,
     *,
     strict: Literal[True] = ...,
     eager_only: None = ...,
@@ -713,7 +713,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoDataFrameT,
+    native_object: IntoDataFrameT,
     *,
     strict: Literal[True] = ...,
     eager_only: Literal[True],
@@ -729,7 +729,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoFrameT | IntoSeriesT,
+    native_object: IntoFrameT | IntoSeriesT,
     *,
     strict: Literal[True] = ...,
     eager_only: None = ...,
@@ -745,7 +745,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoSeriesT | Any,  # remain `Any` for downstream compatibility
+    native_object: IntoSeriesT | Any,  # remain `Any` for downstream compatibility
     *,
     strict: Literal[True] = ...,
     eager_only: None = ...,
@@ -761,7 +761,7 @@ def from_native(
 
 @overload
 def from_native(
-    native_dataframe: IntoFrameT,
+    native_object: IntoFrameT,
     *,
     strict: Literal[True] = ...,
     eager_only: None = ...,
@@ -778,7 +778,7 @@ def from_native(
 # All params passed in as variables
 @overload
 def from_native(
-    native_dataframe: Any,
+    native_object: Any,
     *,
     strict: bool,
     eager_only: bool | None,
@@ -789,7 +789,7 @@ def from_native(
 
 
 def from_native(
-    native_dataframe: Any,
+    native_object: Any,
     *,
     strict: bool = True,
     eager_only: bool | None = None,
@@ -801,7 +801,7 @@ def from_native(
     Convert dataframe/series to Narwhals DataFrame, LazyFrame, or Series.
 
     Arguments:
-        native_dataframe: Raw object from user.
+        native_object: Raw object from user.
             Depending on the other arguments, input object can be:
 
             - pandas.DataFrame
@@ -825,12 +825,12 @@ def from_native(
     from narwhals.stable.v1 import dtypes
 
     # Early returns
-    if isinstance(native_dataframe, (DataFrame, LazyFrame)) and not series_only:
-        return native_dataframe
-    if isinstance(native_dataframe, Series) and (series_only or allow_series):
-        return native_dataframe
+    if isinstance(native_object, (DataFrame, LazyFrame)) and not series_only:
+        return native_object
+    if isinstance(native_object, Series) and (series_only or allow_series):
+        return native_object
     result = _from_native_impl(
-        native_dataframe,
+        native_object,
         strict=strict,
         eager_only=eager_only,
         eager_or_interchange_only=eager_or_interchange_only,


Test patch:
diff --git a/tests/stable_api_test.py b/tests/stable_api_test.py
index 414b20ad..7fa0ffda 100644
--- a/tests/stable_api_test.py
+++ b/tests/stable_api_test.py
@@ -85,8 +85,6 @@ def test_stable_api_docstrings() -> None:
             continue
         v1_doc = getattr(nw_v1, item).__doc__
         nw_doc = getattr(nw, item).__doc__
-        if item == "from_native":
-            v1_doc = v1_doc.replace("native_dataframe", "native_object")
         assert v1_doc == nw_doc