chore: `IntoImplementation` type alias

[FBruzzesi]

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

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

Related issues

• See comment

Checklist

• [x] 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]

FYI, if we wanna expose it in the future - we now have IntoBackend

https://github.com/narwhals-dev/narwhals/blob/62ba1579012584228d85d965887035ae03f5225a/narwhals/_namespace.py#L83

Currently not a runtime object, but it is this idea + auto-completion

https://github.com/narwhals-dev/narwhals/blob/62ba1579012584228d85d965887035ae03f5225a/narwhals/_namespace.py#L56-L83

[!NOTE] That doesn't supersede this PR though, which is the exposing + documenting part 🙂

[FBruzzesi]

Closing in favor of #2971