chore: IntoImplementation type alias

[FBruzzesi]

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

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

Related issues

• See comment

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]

thanks for doing this

not totally sure about this one, some thoughts:

• the docs now show IntoImplementation, rather than a more explicit union
• the argument is backend but the type hint is IntoImplementation
• currently, we convert everything to nw.Implementation, but in theory I think we should be able to accept native namespaces which are from extensions

[FBruzzesi]

thanks for doing this

not totally sure about this one, some thoughts:

• the docs now show IntoImplementation, rather than a more explicit union
• the argument is backend but the type hint is IntoImplementation

Makes sense! I am ok with leaving the signature as it is with the union

• currently, we convert everything to nw.Implementation, but in theory I think we should be able to accept native namespaces which are from extensions

This would require to rethink the codebase, not just the signature 🙈

[dangotbanned]

https://narwhals-dev.github.io/narwhals/api-reference/dataframe/#narwhals.dataframe.DataFrame.lazy

not totally sure about this one, some thoughts:

* the docs now show `IntoImplementation`, rather than a more explicit union

@MarcoGorelli I imagined the docs for DataFrame.lazy would work in the same way as from_native

• on the API reference, you'd have a link to expand the alias
• in an editor, you'd expand the union (and docstring) on hover

Is that not a positive?

[MarcoGorelli]

I thought it would, but when I built this locally then it didn't show up. Though for some reason Implementation already doesn't show up https://narwhals-dev.github.io/narwhals/api-reference/dataframe/#narwhals.dataframe.DataFrame.lazy 🤔

[dangotbanned]

I thought it would, but when I built this locally then it didn't show up. Though for some reason Implementation already doesn't show up narwhals-dev.github.io/narwhals/api-reference/dataframe#narwhals.dataframe.DataFrame.lazy 🤔

Oh, is that because there isn't a page for Implementation?
https://narwhals-dev.github.io/narwhals/api-reference/

I went looking for one when I wrote this but settled on linking to source:
https://github.com/vega/altair/blob/94220be0115e8b13d2ebc686552edf68fd841a54/altair/datasets/_reader.py#L137-L143

[MarcoGorelli]

Oh, is that because there isn't a page for Implementation?

right, thanks 🤦

maybe we should make a type alias for Backend, rather than IntoImplementation?

[dangotbanned]

#1917 (comment)

Oh, is that because there isn't a page for Implementation?

right, thanks 🤦

maybe we should make a type alias for Backend, rather than IntoImplementation?

@MarcoGorelli responding here as it has the context.

I did originally propose either IntoBackend or IntoImplementation in (#1914 (comment))

Although (IntoImplementation) is a mouthful, I do think its the best description of what is acceptable.

IntoBackend would make more sense if the enum were renamed.

I think having Implementation and Backend could be a point of confusion - since they're semantically similar but mean very different things to narwhals

Note

I'd personally leave the description as:
Anything which can be converted to a Narwhals Implementation.