feat: add native property and deprecate .to_native() method

[FBruzzesi]

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

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

Related issues

• Related issue #
• Closes add DataFrame.native / LazyFrame.native / Series.native properties #1295

Checklist

• Code follows style guide (ruff)
• Tests added
• Documented the changes

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

[MarcoGorelli]

nice!

• should we use this in all the public docs places where to_native currently appears?
• I think we should have it such that in the main namespace, DataFrame.to_native / LazyFrame.to_native / Series.to_native issue deprecation warnings, but not in stable.v1 (could be a follow-up)
• i think the same docstring as the current to_native functions would be good?

[FBruzzesi]

I updated accordingly, let me leave a couple of comments:

• should we use this in all the public docs places where to_native currently appears?

I replaced only the cases for .to_native() method (one instance), not nw.to_native(...)

• I think we should have it such that in the main namespace, DataFrame.to_native / LazyFrame.to_native / Series.to_native issue deprecation warnings, but not in stable.v1 (could be a follow-up)

I added this, and tested as well. Yet, since it is a free operation, I don't think it is a big drawback keeping it. I personally like the to_native() api better (not sure why).

• i think the same docstring as the current to_native functions would be good?

👍🏼

[FBruzzesi]

My understanding is that CI is failing because all the imports in stable v1 docstrings changed

+ import narwhals as nw
- import narwhals.stable.v1 as nw

how's that the case?

[MarcoGorelli]

thanks!

I added this, and tested as well. Yet, since it is a free operation, I don't think it is a big drawback keeping it. I personally like the to_native() api better (not sure why).

🤔 maybe we can bikeshed on this longer then 😄 longterm I think it'd be better to stabilise on a single api...on the one hand, I like the symmetry of to/from, but on the other hand, I do like that .native makes it look more like it is (a pratically free operation)

[MarcoGorelli]

My understanding is that CI is failing because all the imports in stable v1 docstrings changed

+ import narwhals as nw
- import narwhals.stable.v1 as nw

how's that the case?

sorry yeah this was in #1278

[FBruzzesi]

sorry yeah this was in #1278

Just to be sure, was this intended?

[MarcoGorelli]

CI looks like it's green now, I think the only failure is because of deprecation warnings having changed in py13, looking into it

[FBruzzesi]

CI looks like it's green now, I think the only failure is because of deprecation warnings having changed in py13, looking into it

Found the doctest that was raising, I changed it to call .native instead, and I am skipping the .to_native() tests in stable api v1. Those would fail unless we change it back to the import import narwhals.stable.v1 as nw

[MarcoGorelli]

thanks!

I personally like the to_native() api better (not sure why).

shall we sleep on this one a bit longer then? i don't feel super-strongly about this one tbh, happy to keep to_native() if you prefer it

[FBruzzesi]

I personally like the to_native() api better (not sure why).

Would it be bad to introduce .native without deprecating .to_native()? I understand it may be confusing for a user. Maybe changing the description of .to_native() to explicitly mention that's just an alias for .native and that's a free operation.

[EdAbati]

I also don't have a strong preference.
I see why .native hints that it is a 'free' operation but I kind of like how to_native reads 😅 (maybe just because I got used to it)

We could keep it as alias for now, and move the discussion to an issue. In the meantime, we can suggest .native in every docs to signal it is the 'preferred way'.

[MarcoGorelli]

maybe this can be a good topic for discussion for tomorrow's community call?