api: "unstable" features

[MarcoGorelli]

I'm slightly hesitant about how to merge #1298 and #1290 - rolling_mean is marked as unstable in Polars. ewm_mean isn't, but follows the api kind of API style

I do think we should merge them, I just think we need a way to signal that we won't make the same kinds of promises for them as we do for the rest of the API in stable.v1

So, I'm tempted to say:

• let's wait for some decision / further discussion on Explore dropping Pandas requirement for Plotly Express plotly/plotly.py#4834
• we can discuss the Narwhals unstable API

I'm sorry for the delay here in merging these PRs

[FBruzzesi]

I'm sorry for the delay here in merging these PRs

No need to be sorry, I think #1290 was not even discussed fully (e.g. in which way we want to implement rolling for pyarrow backend).

Regarding how to mark features as unstable, which options do we have? Adding a warning/disclaimer in the docstrings and docs is the bare minimum, aside that:

• Raising a warning might be too much and too strong for a user.
• Raising a warning only in the stable API i.e. if used in narwhals.stable.v1, but let it go silently if called from narwhals?

I would say this second option could be a compromise?

[MarcoGorelli]

thanks! the second one could work - we could define a NarwhalsUnstableWarning class, and advise users to silence warnings of that class if they're OK with using an experimental feature

[DeaMariaLeon]

Is this decided then?: "define a NarwhalsUnstableWarning class, and advise users to silence warnings of that class if they're OK with using an experimental feature"