MNT: Add provisional get_backend(resolve=False) flag #29039
Conversation
25482d5 to
9640a95
Compare
lib/matplotlib/__init__.py
Outdated
|
|
||
|
|
||
| def get_backend(): | ||
| def get_backend(*, resolve=True): |
There was a problem hiding this comment.
To bikeshed the name a bit, auto_resolve or force_resolution? "resolve" is not fully obvious to me that this means "should I try to guess the best available back end or not".
There was a problem hiding this comment.
I've been thinking on the name a bit. How do we complete the sentence "If no backend has been selected yet, ..."?
- "trigger backend resolution" / "resolve the backend": this is the "resolve" namespace. I feel "auto" and "force" do not add information here - "automatically resolve the backend", "force backend resolution" both basically state "do the resolution", there's nothing "automatic" about it other than it selects what's available, but that's already the resolution, there's also no "force" it's just the operation to be done.
Maybe the "resolution" terminology is a bit heavy? - "auto-select a suitable backend":
get_backend(auto_select=True)? - "activate a suitable backend":
get_backend(activate=True)?
There was a problem hiding this comment.
I like auto_select the best as it also implies that "one was not set, we did not pick, therefor you get back None"
There was a problem hiding this comment.
I think "resolve" makes sense here? get_backend means "tell me what backend I'm using". "resolve" means choose one so it is not unresolved. That this is the default behaviour of get_backend is the design decision we are trying to reverse?
There was a problem hiding this comment.
That this is the default behaviour of
get_backendis the design decision we are trying to reverse?
This is not a complete sentence (or rather 1.5 sentences 😄). Not sure I understand what you're asking, but I'll try to answer anyway. The first goal is to provide a high-level API for "get the current backend, but don't resolve if there is no current backend". One currently has to rely on the semi-public rcParams._get('backend'), but #26406 (comment) plans to get away from handling backend logic in rcParams. Therefore, get_backend(resolve=False) will be the replacement for rcParams._get('backend').
Whether or not the default should eventually change or not is a separate discussion that can be had later. It does not interfere with this PR.
There was a problem hiding this comment.
My point was just that "resolve" makes sense as the kwarg.
There was a problem hiding this comment.
Still collecting opinions on the parameter name. Prime candidates are resolve and auto_select.
There was a problem hiding this comment.
I think the argument against resolve is that unless you know the jargon we use about the auto-select backend, it is not clear what "get the backend, but do not resolve" means, where as "get the backend, but do not run the auto-select logic" is relatively clear.
There was a problem hiding this comment.
Thanks @tacaswell that convinces me. While resolve is slightly more concise, auto_select is easier to understand for people without prior knowledge. -> Changed to auto_select.
fcdf522 to
d29e8b5
Compare
The default is `resolve=True` for now, so that this introduction is completely backward-compatible. The provisional introduction anticipates planned changes for the backend resolution (matplotlib#26406 (comment)). If all plays out as intended, this prolongs the range of releases for the migration: If we start deprecating `rcParams._get("backend")` say in 3.11, people can immediately switch to `get_backend(resolve=False)` and their code still runs on 3.10 without version gating. The worst that can happen is that the introduced flag was not helpful and we remove it again, which is easy because it's provisional.
|
Note: I've intentionally not added a what's new note. People can start using this, but it's not my ambition to already push them this way by advertising the new API. As written above, this is mainly in 3.10 so that there are less version-gating issues when the API gets formally introduced in 3.11. |
since 3.10 we have the official API `matplotlib.get_backend (auto_select=False)`. No problems have been reported and matplotlib-inline is using it https://github .com/ipython/matplotlib-inline/pull/38. Therefore, I remove the provisional status from the auto-select flag. Additionally, I deprecate the API rcParams._get('backend'), which the above is replacing. It seems that `rcParams._get("backend")` is not used anywhere publically, but let's still be defensive and deprecate. https://github.com/search?q=%2F%5C._get%5C%28%5B%22%27%5Dbackend%5B%22%27%5D%5C%29%2F+language%3APython+NOT+is%3Afork+NOT+path%3A**%2Fmatplotlib%2F**+NOT+path%3A**%2Fsite-packages**+NOT+path%3A**%2Fpyplot.py&type=code This is working towards matplotlib#26406. Follow-up to matplotlib#29039.
since 3.10 we have the official API `matplotlib.get_backend (auto_select=False)`. No problems have been reported and matplotlib-inline is using it https://github .com/ipython/matplotlib-inline/pull/38. Therefore, I remove the provisional status from the auto-select flag. Additionally, I deprecate the API rcParams._get('backend'), which the above is replacing. It seems that `rcParams._get("backend")` is not used anywhere publically, but let's still be defensive and deprecate. https://github.com/search?q=%2F%5C._get%5C%28%5B%22%27%5Dbackend%5B%22%27%5D%5C%29%2F+language%3APython+NOT+is%3Afork+NOT+path%3A**%2Fmatplotlib%2F**+NOT+path%3A**%2Fsite-packages**+NOT+path%3A**%2Fpyplot.py&type=code This is working towards matplotlib#26406. Follow-up to matplotlib#29039.
since 3.10 we have the official API `matplotlib.get_backend (auto_select=False)`. No problems have been reported and matplotlib-inline is using it https://github .com/ipython/matplotlib-inline/pull/38. Therefore, I remove the provisional status from the auto-select flag. Additionally, I deprecate the API rcParams._get('backend'), which the above is replacing. It seems that `rcParams._get("backend")` is not used anywhere publically, but let's still be defensive and deprecate. https://github.com/search?q=%2F%5C._get%5C%28%5B%22%27%5Dbackend%5B%22%27%5D%5C%29%2F+language%3APython+NOT+is%3Afork+NOT+path%3A**%2Fmatplotlib%2F**+NOT+path%3A**%2Fsite-packages**+NOT+path%3A**%2Fpyplot.py&type=code This is working towards matplotlib#26406. Follow-up to matplotlib#29039.
The default is
resolve=Truefor now, so that it is completely backward-compatible.The provisional introduction anticipates planned changes for the backend resolution (#26406 (comment)).
If all plays out as intended, this prolongs the range of releases for the migration: If we start deprecating
rcParams._get("backend")say in 3.11, people can immediately switch toget_backend(resolve=False)and their code still runs on 3.10 without version gating.The worst that can happen is that the introduced flag was not helpful and we remove it again, which is easy because it's provisional.
On a side-note: This also helps with a possible future default change from
resolve=Truetoresolve=False. By making the flag available, users can choose the behavior explicitly, again without (or with lesser version gating) if they don't want to be affected by a default change.