Add type guard for what `from_native` supports

[OutSquareCapital]

We would like to learn about your use case. For example, if this feature is needed to adopt Narwhals in an open source project, could you please enter the link to it below?

It would be nice if typing.runtime_checkable decorator could be added to NativeFrame.

Please describe the purpose of the new feature or describe the problem to solve.

This would allow me to avoid maintaining a copy of the Protocol in my own project for instances checking.
Also, I haven't looked at how NativeFrame is used in narwhals internals, but if there's any getattr access to check at runtime the Protocol compliance, this can be a nicer alternative.

My test suite show that it works :)

Suggest a solution if possible.

No response

If you have tried alternatives, please describe them below.

No response

Additional information that may help us understand your needs.

No response

[dangotbanned]

Thanks for raising this @OutSquareCapital

I wanted to say I'm happy to see (duckdb/duckdb-python#352) landed!
Really appreciate the work you've put into it as the duckdb stubs had caused me a few headaches 😅 (#3188)

[dangotbanned]

How it works?

Also, I haven't looked at how NativeFrame is used in narwhals internals,

I'd recommend reading through narwhals/_native.py - but note the _ prefix.
The types we currently export are all listed in narwhals/typing.py

but if there's any getattr access to check at runtime the Protocol compliance, this can be a nicer alternative.

Generally speaking, we use the same underlying function as @runtime_checkable, which is inspect.getattr_static.

narwhals/narwhals/_utils.py

Lines 1572 to 1573 in 7e3fcca

	def _hasattr_static(obj: Any, attr: str) -> bool:
	return getattr_static(obj, attr, _SENTINEL) is not _SENTINEL

Where we differ, is that we (usually) check for a single attribute - rather than a full interface.
This can make a pretty big difference to the cost of the check - and is accurate enough because the rest is enforced with a (static) type checker:

narwhals/narwhals/_utils.py

Lines 1587 to 1590 in 7e3fcca

	def is_compliant_lazyframe(
	obj: CompliantLazyFrame[CompliantExprT, NativeLazyFrameT, ToNarwhalsT_co] | Any,
	) -> TypeIs[CompliantLazyFrame[CompliantExprT, NativeLazyFrameT, ToNarwhalsT_co]]:
	return _hasattr_static(obj, "__narwhals_lazyframe__")

NativeFrame

This protocol does not define what is sufficient at runtime to be used with narwhals.

It defines the common denominator - that we can use in our typing - to match the concrete types we can't depend on.
I know that's a mouthful 😂

With that being said, would having this runtime check still be of use to you?

typing.runtime_checkable

The other problem is I wouldn't feel comfortable supporting that decorator until our minimum python is 3.12 - which is when it switched to inspect.getattr_static.
I know at least pandas, ibis and duckdb all define a __getattr__ - which would get invoked by the old version

Ideally we could use typing_extensions - but have had issues with being 0-dependencies in the past (#2391)

[OutSquareCapital]

Thanks for raising this @OutSquareCapital

I wanted to say I'm happy to see (duckdb/duckdb-python#352) landed! Really appreciate the work you've put into it as the duckdb stubs had caused me a few headaches 😅 (#3188)

Happy to see others happy haha!
Same for me about headaches. Will continue working on this once my proposal is accepted

[OutSquareCapital]

Thanks for the detailled answer!
I see, the runtime consideration is something I haven't much tought of.

"With that being said, would having this runtime check still be of use to you?"

I currently use a copy-pasted version of the Protocol here.

If there's a better solution to check if something is usable by narwhals I'm all hears :). It's not a big deal, it would just be nice.

However the 3.12 change is indeed a very fair point. typing_extensions is nice to use when it's type checking only, so it can be a "soft" dependency.
But here it's runtime, hmm.
All things considered I would perfectly understand why this would not be supported until minimum version = 3.12

[dangotbanned]

Thanks for the detailled answer!

No worries!
I just wanted to be clear that what you're asking for is reasonable.
But we have some complexity that is getting in the way 😄

If there's a better solution to check if something is usable by narwhals

So I haven't dived too deep into pql to see exactly the shape of your problem, but can see narwhals as required dependency.

Rough idea

This would probably solve the runtime part:

from typing import Any

import narwhals as nw


def into_narwhals_lazyframe(obj: Any) -> nw.LazyFrame[Any] | TypeError:
    narwhals_obj = nw.from_native(obj, pass_through=True)
    if isinstance(narwhals_obj, (nw.DataFrame, nw.LazyFrame)):
        return narwhals_obj.lazy()
    msg = f"<some message if you're bailing here on: {obj!r}>"
    return TypeError(msg)


def into_pql(obj: Any) -> nw.LazyFrame[Any]:
    # <some ceremony you do before trying narwhals>
    # maybe handle `duckdb` and `polars` directly?
    # ...

    narwhals_lazyframe = into_narwhals_lazyframe(obj)
    if isinstance(narwhals_lazyframe, TypeError):
        # <bailing>
        raise narwhals_lazyframe
    # <some ceremony you do with a `nw.LazyFrame`>
    # maybe wrapping in a container you own?
    # ...

    # for now, just returning as-is
    return narwhals_lazyframe

By solved, I'm seeing the issue being that you'd like control over:

• whether to raise or not
• if so, what the user sees

>>> into_pql(["definitely not a native frame"])
TypeError: <some message if you're bailing here on: ['definitely not a native frame']>

I'm assuming you have the typing part solved already of course 😄

If not, replace the Any(s) with:

1. Something from narwhals.typing
2. Something else you hand-roll
3. A combination of the two

Why not a type guard?

You could use some combination of the guards in narwhals.dependencies.

The main issue they have is that you'd reject support from plugins - which would otherwise be accepted by nw.from_native