docs: explain translation from narwhals api to native api

[amol-]

What type of PR is this? (check all applicable)

• 💾 Refactor
• ✨ Feature
• 🐛 Bug Fix
• 🔧 Optimization
• 📝 Documentation
• ✅ Test
• 🐳 Other

If you have comments or can explain your changes, please do so below.

The current documentation is unclear about the how objects move from narwhals api to polars compatible backend to native api. This adds a section that tries to make that more clear.

[MarcoGorelli]

thanks @amol- , amazing stuff here! I've just reworded it a bit, and will try to do a bit more tomorrow, but I think this is super-important to be documented, so thanks a tonne for having started it 🙏

[amol-]

@MarcoGorelli I think that in the rewording we lost a little bit the message that the last part tried to convey.
In the last paragraph I was trying to explain and showcase how narwhals.Dataframe and PandasLikeDataframe can be used interchangeably in the narwhals api and that thus even if methods return the "Like" version the user doesn't have to care about that.

I'm referring to this part:

After a compliant object is returned, the user will keep using and perform
additional operations on the compliant object itself, as the compliant
object implements the same API as the narwhals objects and is accepted
as an argument by all narwhals functions.

For example nw.col("b")._call(nwdf.__narwhals_namespace__()) on a
pyarrow.Table will return an ArrowExpr:

  ArrowExpr(depth=0, function_name=col, root_names=['b'], output_names=['b']

but invoking narwhals.Dataframe.select on it will work and return
a new narwhals.Dataframe as if we passed a narwhals.Expr itself:

>>> nwexpr = nw.col("b")
>>> type(nwexpr)
<class 'narwhals.stable.v1.Expr'>
>>> nwr = nwdf.select(nw.col("b"))
>>> type(nwr)
<class 'narwhals.stable.v1.DataFrame'>
>>> arrowexpr = nw.col("b")._call(nwdf.__narwhals_namespace__())
>>> type(arrowexpr)
<class 'narwhals._arrow.expr.ArrowExpr'>
>>> nwr = nwdf.select(arrowexpr)
>>> type(nwr)
<class 'narwhals.stable.v1.DataFrame'>

[MarcoGorelli]

Thanks - I'll double check but I'm not sure it's intentional that that's supported

[MarcoGorelli]

In fact, I just applied the following diff, ran the test suite, and no test failed:

diff --git a/narwhals/dataframe.py b/narwhals/dataframe.py
index 644db7bc..07c567bd 100644
--- a/narwhals/dataframe.py
+++ b/narwhals/dataframe.py
@@ -123,6 +123,9 @@ class BaseFrame(Generic[FrameT]):
         *exprs: IntoExpr | Iterable[IntoExpr],
         **named_exprs: IntoExpr,
     ) -> Self:
+        from narwhals._pandas_like.expr import PandasLikeExpr
+        if any(isinstance(x, PandasLikeExpr) for x in exprs):
+            1/0

Passing a compliant Expr to nw.DataFrame.select doesn't happen internally, and it's not something users are meant to do - could you clarify why it needs mentioning please? I might be missing something though, so sorry if that's the case 🙏

[amol-]

In fact, I just applied the following diff, ran the test suite, and no test failed:

diff --git a/narwhals/dataframe.py b/narwhals/dataframe.py
index 644db7bc..07c567bd 100644
--- a/narwhals/dataframe.py
+++ b/narwhals/dataframe.py
@@ -123,6 +123,9 @@ class BaseFrame(Generic[FrameT]):
         *exprs: IntoExpr | Iterable[IntoExpr],
         **named_exprs: IntoExpr,
     ) -> Self:
+        from narwhals._pandas_like.expr import PandasLikeExpr
+        if any(isinstance(x, PandasLikeExpr) for x in exprs):
+            1/0

Passing a compliant Expr to nw.DataFrame.select doesn't happen internally, and it's not something users are meant to do - could you clarify why it needs mentioning please? I might be missing something though, so sorry if that's the case 🙏

Ah good to know, I thought that the interoperability was by design. So every API always should invoke _from_compliant_dataframe (or equivalent) to surface to users only the narwhals.* objects? It might make sense to document that.

[MarcoGorelli]

Yup! I think the type hints usually make that clear? Most methods return Self

Anyway, thanks for your PR, let's ship this

[MarcoGorelli]

thanks @amol- !