Unify deprecation warning channels before v1: EvolvingAPIWarning vs LinopySemanticsWarning

[FBumann]

Note

AI-written note (Claude Code, prompted by @FBumann) — tracking item from the #737 discussion.

There are two parallel "this will change under v1" warning channels:

Channel	Introduced by	Used for
EvolvingAPIWarning (subclass of FutureWarning)	#732	implicit MultiIndex-level projections in broadcast_to_coords (both strict and non-strict modes since #737); piecewise API
LinopySemanticsWarning + warn_legacy()	#717 (unmerged)	per-site legacy-vs-v1 deprecations (NaN fills, coord mismatches, aux conflicts) with opt-in/silence hints

Before v1 ships these should be one channel — users need a single warning category to filter, and warn_legacy() already has the better infrastructure (dynamic stacklevel, opt-in hints, per-site messages).

Proposal: the migration happens as part of landing #717 (not as an independent PR) — the class must arrive together with its infrastructure (warn_legacy(), the options['semantics'] flag, the opt-in hints its docstring references). Concretely, #717's integration commit routes the MI-projection warnings in linopy/common.py (_warn_implicit_projections, marked TODO(#738)) through warn_legacy().

EvolvingAPIWarning itself stays — it serves a different purpose (API-surface evolution, e.g. piecewise) and #717 keeps both classes.

(An attempt to copy LinopySemanticsWarning into #737 ahead of #717 was considered and rejected: the class's meaning — "legacy semantics" — doesn't exist as a concept until #717's options flag lands.)

Blocked on: #732 and #717 merging. The MI projection warning site carries a TODO referencing this issue.

[FabianHofmann]

🤖 This comment was written by Claude (Claude Code), based on hands-on findings while migrating PyPSA to the v1 arithmetic semantics.

Adding a downstream data point relevant to the warning-channel decision here: the choice to base LinopySemanticsWarning on FutureWarning (so it's shown to end users by default) has a side effect on consumer CI.

PyPSA configures pytest with filterwarnings = ["error::FutureWarning", ...]. The moment a v1-capable linopy is installed, every legacy divergence becomes a hard test error — even in legacy mode, before any opt-in to v1. During the PyPSA migration this meant simply upgrading linopy broke the suite at all the merge / alignment / absent-slot sites, independent of whether we had opted into v1.

That's arguably working as intended (it surfaces exactly the code that needs migrating), but it's worth weighing in the EvolvingAPIWarning vs LinopySemanticsWarning unification: whichever category is chosen, a lot of downstreams treat FutureWarning as an error, so the transitional warnings will trip their CI on upgrade regardless of semantics selection. Options that would soften this:

• a distinct base category that's easy to filter without also silencing genuine FutureWarnings, and/or
• a documented one-line silence (a warnings.filterwarnings(...) snippet or a linopy.options toggle) prominently in the migration guide, so consumers can adopt v1-capable linopy first and migrate the sites incrementally.

Happy to link the concrete PyPSA sites if useful.

[FBumann]

@FabianHofmann I think we agree that there needs to be a way to have linopy code that works in both semantics versions (legacy/v1) without warnings or errors. Therefore having this as a loud FutureWarning is what we want. Until this is proven to be infeasible, this can be closed

The rest of the issue is also already adressed in #717

[FabianHofmann]

great, thanks @FBumann