Fix/from native update version by camriddell · Pull Request #3515 · narwhals-dev/narwhals

camriddell · 2026-03-18T18:48:07Z

Description

Calling from_native(nw.DataFrame(…), version=…) would always return the passed DataFrame/Series object.
This ignores the version that is specified in the version argument.

Instead, for a given narwhals DataFrame/Series from_native now returns the same object if the versions match and creates a new object if the versions do not match.

Note, 2 clean up items are also added in this PR.

Before:

import narwhals as nw, narwhals.stable.v1 as nw_v1
import polars as pl

native = pl.DataFrame({"a": [1, 2, 3]})

unstable = nw.from_native(native)
stablified = nw_v1.from_native(unstable)

print(
    isinstance(stablified, nw_v1.DataFrame), # False
    isinstance(stablified, nw.DataFrame),    # True
    sep='\n'
)

stable = nw_v1.from_native(native)
unstablified = nw.from_native(unstable)

print(
    isinstance(unstablified, nw_v1.DataFrame), # False
    isinstance(unstablified, nw.DataFrame),    # True
    sep='\n'
)

After:

import narwhals as nw, narwhals.stable.v1 as nw_v1
import polars as pl

native = pl.DataFrame({"a": [1, 2, 3]})

unstable = nw.from_native(native)
stablified = nw_v1.from_native(unstable)

print(
    isinstance(stablified, nw_v1.DataFrame), # True
    isinstance(stablified, nw.DataFrame),    # True (since nw.v1.DataFrame is subclass of nw.DataFrame)
    sep='\n'
)

stable = nw_v1.from_native(native)
unstablified = nw.from_native(unstable)

print(
    isinstance(unstablified, nw_v1.DataFrame), # False
    isinstance(unstablified, nw.DataFrame),    # True
    sep='\n'
)

reported by hoxbro (Holoviews) on Discord #help channel

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

Related issues

Related issue #<issue number>
Closes #<issue number>

Checklist

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

in tests/translate/from_native_test.py test_init_already_narwhals and test_init_already_narwhals_unstable have the exact same source code, when the former should verify behavior in a stable version. This function used to test this, but seemed to have been mistakenly edited.

from_native on a narwhals.{DataFrame,Series} would always return the same object even if the DataFrame._version and the version passed into from_native disagreed. Now, if the versions mismatch we create a new narwhals object with the appropriate version. If the versions match, we short cut and return the same object.

camriddell · 2026-03-18T19:07:10Z

narwhals/dataframe.py

        ```
    """

+    _version: ClassVar[Version] = Version.MAIN


Hoping this has been an oversight and wasn't excluded for a strong reason. This change makes the DataFrame/LazyFrame api a bit more consistent internally.

Yeah nice one, thanks @camriddell!

If you dig through the blame (I think) I added these on Series & DataFrame at the same time as the from_* constructors.

LazyFrame didn't get any new methods, so it slipped through 😅

camriddell · 2026-03-18T20:04:05Z

@MarcoGorelli I believe the nightly failure isn't due to this change but perhaps something that needs to be accounted for in pandas. Shall I open up an Issue with this? Or do you believe it is relevant to this PR?

dangotbanned · 2026-03-18T20:25:51Z

tests/v1_test.py

    pl_frame = pl.DataFrame({"a": [1, 2, 3]}).lazy()
    nw_frame = nw_v1.from_native(pl_frame)
-    with pytest.raises(AttributeError):
+    with pytest.raises(AssertionError):


IIRC, there may be a comment somewhere mentioning the error?

(Ignore me if this is too vague 😂)

I found this comment in the comparable tests for DataFrames

# NOTE: (#2629) combined with passing in `nw_v1.DataFrame` (w/ a `_version`) into itself changes the error with pytest.raises(AssertionError): nw_v1.DataFrame(nw_frame, level="full")

The LazyFrame had an AttributeError because the LazyFrame.__init__ would try to check the ._version attribute which didn't exist. This change more closely aligns this LazyFrame with its DataFrame and Series counterparts since they all successfully fail with the same error now.

successfully fail

😂

dangotbanned · 2026-03-18T20:35:25Z

@camriddell I should probably check what was mentioned on discord - but from reading the PR I'm a bit confused on the problem that's being solved.

(#3515 (comment)) is all good - but something seems strange to me that calling from_native changes the version 🤔

FWIW, I don't think from_native should accept narwhals-level objects, but we are where we are 😅

MarcoGorelli · 2026-03-21T14:16:43Z

thanks @camriddell !

on board with the suggestions, i think this just needs addressing

tests/translate/from_native_test.py:242: error: Need type annotation for
"stablified_s"  [var-annotated]
        stablified_s = nw_v1.from_native(unstable_s, allow_series=True)
                       ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
tests/translate/from_native_test.py:257: error: Need type annotation for
"stable_s"  [var-annotated]
        stable_s = nw_v1.from_native(s, allow_series=True)
                   ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
tests/translate/from_native_test.py:258: error: Need type annotation for
"unstablified_s"  [var-annotated]
        unstablified_s = nw.from_native(stable_s, allow_series=True)
                         ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Found 3 errors in 1 file (checked 469 source files)
make: *** [Makefile:26: typing] Error 1

the nightly failure is just due to pandas-dev/pandas#64749 and is unrelated to your pr

camriddell · 2026-03-23T01:51:05Z

@camriddell I should probably check what was mentioned on discord - but from reading the PR I'm a bit confused on the problem that's being solved.
(#3515 (comment)) is all good - but something seems strange to me that calling from_native changes the version 🤔

The primary concern here is surprise that the v1.from_native can give you a non-v1 object back. The current fast path implementation means that if you call: v2.from_native(v1.DataFrame) you get back the same v1.DataFrame, which is odd because every other input type will give you back a v2.DataFrame. Meaning the signature of v2.from_native return type is "usually a v2 object, but sometimes whatever you passed into it".

FWIW, I don't think from_native should accept narwhals-level objects, but we are where we are 😅

I agree with this from a structurally-correct perspective. However, conveniences are nice for DX especially since our primary audience is dataframe-agnostic libraries. This code let's them treat any incoming frame the same way without having to manually check if it is already a narwhals DataFrame. Likely their end users won't be passing in narwhals DataFrames, but they could have multiple entry points may need to translate to a narwhals object and our "recursive" type support means they don't have to write explicit isinstance checks before every from_native call.

…stable,unstable}

dangotbanned · 2026-03-23T12:57:16Z

(#3515 (comment))

Thanks for the context @camriddell!

I have a couple more questions, are you okay if we sit on this until later today?

camriddell · 2026-03-23T13:23:04Z

(#3515 (comment))

Thanks for the context @camriddell!

I have a couple more questions, are you okay if we sit on this until later today?

Absolutely! I'm not in a rush to merge.

dangotbanned · 2026-03-23T22:46:33Z

@camriddell thanks for your patience 😄

1. Similar issue

Did you know about this one?

from_native(nw.LazyFrame, eager_only=True) returns nw.LazyFrame #3226

2. What's the worst that could happen?

I'm curious if we can reveal cases downstream that are (unknowingly?) relying on this behavior.

As an example, if I change tests/v1_test.py::test_with_row_index like this on main - it passes through no problemo.
But wouldn't that be a v1 break following this PR?

Show diff

diff --git a/tests/v1_test.py b/tests/v1_test.py
index 330211162..59ccdae61 100644
--- a/tests/v1_test.py
+++ b/tests/v1_test.py
@@ -447,7 +447,7 @@ def test_with_row_index(constructor: Constructor) -> None:
         pytest.skip()
     data = {"abc": ["foo", "bars"], "xyz": [100, 200], "const": [42, 42]}
 
-    frame = nw_v1.from_native(constructor(data))
+    frame = nw.from_native(nw_v1.from_native(constructor(data)))

What happens if you try running the CI but change the let's see who this really is to raising an exception?

3. Is this discoverable?

Part of what I was getting at in (#3515 (comment)) is that this looks like 2 user errors to me:

# (1) Mixed versions
# (2) Asking for something you already have
nw.from_native(nw_v1.DataFrame(...))

If you think the feature to switch versions is something we need, wouldn't this be a better fit?:

nw_v1.DataFrame(...).to_version("main")
nw_v1.DataFrame(...).to_version("v1")
nw_v1.DataFrame(...).to_version("v2")

There's less ambiguity with something along those lines IMO - and it avoids defining new behavior for from_native

camriddell added 4 commits March 18, 2026 11:02

add v2 to stable/__init__:__all__

29873aa

fix nw.LazyFrame missing _version ClassVar

f1cf356

camriddell force-pushed the fix/from_native-update-version branch from 761f14c to f1cf356 Compare March 18, 2026 19:01

camriddell commented Mar 18, 2026

View reviewed changes

add Series objects in to_stable/to_unstable tests

1db171c

camriddell requested review from MarcoGorelli and dangotbanned March 18, 2026 20:04

dangotbanned reviewed Mar 18, 2026

View reviewed changes

ignore var-annotated in tests/translate/from_native init_already to {…

835c683

…stable,unstable}

camriddell force-pushed the fix/from_native-update-version branch from b596ed5 to 835c683 Compare March 23, 2026 01:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix/from native update version#3515

Fix/from native update version#3515
camriddell wants to merge 6 commits intonarwhals-dev:mainfrom
camriddell:fix/from_native-update-version

camriddell commented Mar 18, 2026

Uh oh!

camriddell Mar 18, 2026

Uh oh!

dangotbanned Mar 18, 2026

Uh oh!

camriddell commented Mar 18, 2026

Uh oh!

dangotbanned Mar 18, 2026 •

edited

Loading

Uh oh!

camriddell Mar 23, 2026

Uh oh!

dangotbanned Mar 23, 2026

Uh oh!

dangotbanned commented Mar 18, 2026

Uh oh!

MarcoGorelli commented Mar 21, 2026 •

edited

Loading

Uh oh!

camriddell commented Mar 23, 2026

Uh oh!

dangotbanned commented Mar 23, 2026

Uh oh!

camriddell commented Mar 23, 2026

Uh oh!

dangotbanned commented Mar 23, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

camriddell commented Mar 18, 2026

Description

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

Related issues

Checklist

Uh oh!

camriddell Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

dangotbanned Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

camriddell commented Mar 18, 2026

Uh oh!

dangotbanned Mar 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camriddell Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

dangotbanned Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

dangotbanned commented Mar 18, 2026

Uh oh!

MarcoGorelli commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

camriddell commented Mar 23, 2026

Uh oh!

dangotbanned commented Mar 23, 2026

Uh oh!

camriddell commented Mar 23, 2026

Uh oh!

dangotbanned commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

1. Similar issue

2. What's the worst that could happen?

3. Is this discoverable?

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dangotbanned Mar 18, 2026 •

edited

Loading

MarcoGorelli commented Mar 21, 2026 •

edited

Loading

dangotbanned commented Mar 23, 2026 •

edited

Loading