What kind of properties can I assume from seaborn version?

[chmduquesne]

Hi,

I wrote a module which depends on seaborn (it basically maps all arguments to widgets, for easier user interaction). I plan to give it a facelift (I have not touched it in 3 years) and adapt it so it can follow future seaborn evolutions.

I noticed that seaborn does not follow semantic versioning, since it makes non backward compatible changes between minor versions (e.g. v0.10.0 removed seaborn.linearmodel: in semantic versioning, this would mandate a new major version, so moving to v1.x.x).

Is there any programmatic way for me to know which functions/arguments are still valid between versions? Or do I have to read all release notes?

Cheers,
Christophe-Marie

[mwaskom]

Like other scientific Python libraries seaborn does not strictly follow semantic versioning (i.e. "increment leftmost number any time any downstream code would break with or without warning").

That said, to quote from your link, current practice is textually consistent with semver:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

But also like other scientific libraries in a 0.x stage (e.g. scikit-learn, pandas until recently), this isn't actually taken as a license to change anything at any time. The practice for (most) backwards incompatible changes aims to

• issue a warning at least one 0.x.0 version ahead of time about the change (ideally these would always be FutureWarnings but i'm not sure that's 100% reliable)
• accept deprecated usage patterns where possible after the formal API changes, issuing a warnings about how to update (e.g.)
• Mention in release notes with an "API" tag (🔴)

With that said, I do expect that the vast majority of usage of seaborn is directly by end users in an interactive context, not by third-party library developers. As such, if faced with a decision between API stability and consistency/expressiveness, seaborn tends to lean more towards the latter than other libraries might. So you should bear that in mind.

There's a lot of work going on to make things more consistent internally and externally such that hopefully a release around 0.15 or so could be a 1.0, which would come with stronger assumptions about API stability. (Though, like numpy and basically all peer packages, that doesn't mean shifting into a very strict implementation of semver).

BTW regarding this specifically:

e.g. v0.10.0 removed seaborn.linearmodel: in semantic versioning, this would mandate a new major version, so moving to v1.x.x

I'd recommend using everything through the top-level namespace. That change did not remove any functions/classes from the public API (and it did have a couple versions where importing seaborn.linearmodels directly would issue a warning), but as the documented usage in every case uses the top-level namespace, I'm less averse to making such internal organizational changes.

[mwaskom]

BTW I think this post makes some good, related points.

[chmduquesne]

All right, thanks for the info.

In my situation, semantic versioning would be interesting, since I am exactly remapping all arguments of each plot to UI widgets. So any MINOR change (in the sense of semver) means that I do not need to worry about backwards compatibility of the data structure, and any MAJOR change means I need to rewrite some code. I am not affected by the other problems that the article mention, in the sense if one changes what the plot shows, it does not break my code: I only care about mapping the arguments correctly. It is the job of seaborn to do whatever it wants with those arguments. However, you are right that it won't solve all problems. The people who are going to see the difference are ultimately the end users.

[mwaskom]

IMO the best thing for your application is probably to pin on a specific Y version (in an X.Y.Z scheme).

Even if semver were strictly followed and nothing was removed unless incrementing X, features can be added on Y releases and so only updating your interface for "major bumps" would mean it would still be out of sync with the underlying library (even if it doesn't break). And deprecated features would start raising warnings, which you'd want to do something about to keep the application from gradually getting more annoying to use.