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?

[dangotbanned]

I think adding Compliant*.native could be a pretty nice improvement internally - where each protocol exposes .native and not the much longer current (private) names.

Shortens paths like this, where lots of places use inconsistent aliasing:

narwhals/narwhals/_arrow/series.py

Line 319 in b03f716

ca = self._native_series

narwhals/narwhals/_arrow/series.py

Line 771 in b03f716

series = self._native_series

narwhals/narwhals/_arrow/series.py

Line 741 in b03f716

ser = self._native_series

narwhals/narwhals/_arrow/series.py

Line 896 in b03f716

native_series = cast("Any", self._native_series)

narwhals/narwhals/_arrow/series.py

Line 832 in b03f716

arr = self._native_series

Being a @property is also a good signal that we shouldn't be using in-place/mutating operations.

Also for things like #2044 (comment), there's an obvious place to hint the TypeVar and not expose internal attributes

[FBruzzesi]

Thanks for reviewing @dangotbanned!

The original PR was not for introducing native at the complaint level, rather at Narwhals one.

I think having Compliant*.native can be a quick win and using properties we can have more control via its setter if we need to

[dangotbanned]

@FBruzzesi I've tested this out for some parts of _arrow over on main...stores-native-compliant

Really think it's a nice improvement to readabilty and DRYs things up well 🙂

With a lot of the repetition out of the way, I was able to spot a few more things that could be written more concisely.

Not sure if this is worth opening an issue for - but if we went ahead with it - then it'd probably make sense to try and do it in one or more big chunks to avoid conflicts

[FBruzzesi]

@FBruzzesi I've tested this out for some parts of _arrow over on main...stores-native-compliant

Really think it's a nice improvement to readabilty and DRYs things up well 🙂

With a lot of the repetition out of the way, I was able to spot a few more things that could be written more concisely.

Not sure if this is worth opening an issue for - but if we went ahead with it - then it'd probably make sense to try and do it in one or more big chunks to avoid conflicts

Hey @dangotbanned sorry I had the chance to look at the code only now. It definitly looks a bit different from what this PR was trying to do.
I think adding native at the compliant level will have no opposition as it's internal only anyway.

Regarding native property at the Narwhals level, I am still not fully sure. I personally like to_native() method, yet we should specify in the docs that this is a no-op as users might expect that some particular computation happens.

[dangotbanned]

#1301 (comment)

Yeah I agree @FBruzzesi wrt the public to_native() - I think it also leaves some wiggle-room in the future for adding parameters (if a use-case arises)

Apologies for hijacking the PR w/ (#1301 (comment)) - I'll continue that as it's own thing 👍

[FBruzzesi]

Closing this for now