stability of series.hist

[Light2Dark]

Hi! I'm from marimo and we've been using narwhals a ton as I'm sure you are aware.

We have an upcoming feature to do binning on the backend to unlock performant table charts in marimo. Related PR: marimo-team/marimo#6892

The only caveat is series.hist is marked as an unstable API. We're just gauging how unstable it is and whether we should implement fallbacks to prevent future breaks. Totally understand either way.

Thank you so much for narwhals!

[MarcoGorelli]

hey @Light2Dark !

it's marked as unstable in Polars https://docs.pola.rs/api/python/stable/reference/series/api/polars.Series.hist.html, so i'm a little hesitant about marking it stable here

having said that, we're not planning on making changes to it in the near-term - perhaps @camriddell has more to say on it?

😄 thank you for your work on Marimo, huge fan, and I always recommend it!

[camriddell]

Agreed that no planned changes are coming to narwhals.Series.hist so provided you are using the stable version API then you won't see any changes from us, just subject to any changes from the upstream dataframe libraries.

For a bit more context to help you make your decision: we currently provide support for .hist as an eager-only backend method (pandas, Arrow, Polars) where the implementation for both pandas and Arrow should be relatively stable (meaning I do not expect any changes to those libraries that will effect our histogram output). However as @MarcoGorelli mentioned Polars may change the underlying .cut function signature or its outputs which may end up then changing Polars .hist expression and Series method as well.

@MarcoGorelli a good question may be: if Polars does change things would we retrofit the stable.v{1,2} to preserve previous behavior? Perhaps this is a good reminder that we should discuss how to position ourselves against large Polars API changes predominantly in anything they have marked as unstable.

[MarcoGorelli]

hist is intentionally kept out of stable.v2 for this reason 😄 unfortunately i think it is in v1, so some retrofitting may end up being warranted unfortunately 😩

[Light2Dark]

Thanks both of you for the quick response. This gives us strong context to make a decision. And thanks for thinking about 'stabilizing' the unstable API, but understandable whichever direction you take.