feat: make Series generic

[EdAbati]

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

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

Related issues

Checklist

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

If you have comments or can explain your changes, please do so below

Last week, I was playing with the idea of having Series generic as DataFrames for better typing.

It may be useful since it is related to the current issues/PRs around documentation/typing.

[MarcoGorelli]

thanks for doing this!

i think in stable/v1 you may need to do something like

from narwhals.typing import Series as NwSeries
Series = NwSeries[Any]

to keep it stable for shiny?

[EdAbati]

Thanks @MarcoGorelli for the review ✌️

shiny is happy now but stable.v1.Series doesn't have the generic typing 😕 If you know any smart way to renable some parts of it let me know.

(the CI error seems unrelated)

[MarcoGorelli]

Thanks, nice one! just got a question

Looking over https://narwhals-dev.github.io/narwhals/backcompat/#exceptions, we did write

we may consider making some type hints more precise.

I feel like we should loop @schloerke into the conversation - would you be OK with us making this type hint more precise? It would only affect Shiny's internal typing and so wouldn't be user-facing, and we would also make the PR to Shiny to get your CI green again

If not, no worries, the stable.v1 mechanism does allow us to only make this change in the main namespace

[schloerke]

@MarcoGorelli Correct. https://github.com/narwhals-dev/narwhals/actions/runs/11932852152/job/33258672137?pr=1412 does break py-shiny. But as you said, it's only seems to be internal and will hopefully be a quick fix.

When testing locally, I changed the pyproject.yaml narwhals dep to

    # "narwhals>=1.10.0",
    "narwhals@git+https://github.com/EdAbati/narwhals@series-generic",

Maybe we could wrap around https://github.com/posit-dev/py-shiny/blob/f6b92d8cf49a90f3b3dbb636cd6d7fdeee244cfd/shiny/render/_data_frame_utils/_types.py#L69 and check the narwhals version and return the appropriate Series or Series[Any](?) value. Hopefully this should fix most of the issues. (2x possible remaining locations: col type and return type for helper method.)

These can probably be done within Shiny before the PR is merged? Please tag me in the py-shiny PR when it is ready 😃

I currently do not have a date as to when shiny would be released after the merge. 😞

[schloerke]

Yay for stronger typing!!

[MarcoGorelli]

i just tried this at it looks like it would break Altair's typing too, so I reverted the extra commit

maybe it's OK to just introduce this in the main namespace and leave stable.v1 as it is for now

[EdAbati]

Thanks both!
I agree that if it start breaking more than 1 downstream library test, we shouldn't change stable.v1 for now. :)