Repository navigation
[Doc]: Revisit interface terminology: Axes interface / pyplot interface #26388
Description
Documentation Link
https://matplotlib.org/devdocs/api/index.html
Problem
We currently use the terms the explicit API and implicit API. Even though they were the result of lengthy discussions, I still have a hard time using them. I bet that most of our users do not know these terms. And also when given these terms, I suppose most would not know what they mean. In my experience, I always have to follow up on these terms with an explanation.
I think the problem is that they are very technical and not something a user can relate to intuitively: Explicit/implicit is the mode of operation; i.e. how the written code references the Figure and Axes. This is not a primary concern of users.
Suggested improvement
Use interface instead of API.
API is too much on the technical side (which objects/functions/methods are there and what are their signatures). To me interface has more emphasis on the conceptual aspect (how do I work with this). Also, interface can have a good-enough intuitive meaning for non-software developers who do not know "API" at all.
Distinguishing characteristics
Use the the things the user interacts with as the distinguishing characteristic:
- Variant 1) conceptual distinction: the object interface / the function interface
- Variant 2) practical distinction: the Axes interface / the pyplot interface
I propose to go with variant 2). While object/function is more concrete than explicit/implicit, it's still somewhat generic (what objects/functions?). Also, the OOP aspect is dilluted because you usually do not instantiate objects yourself and the interactions is mostly limited to Figure and Axes objects.
In variant 2) one could have gone with "the Figure-and-Axes interface", but that seems too verbose, and given that operations on the Figure are much less frequent compared to operations on the Axes, I think we can afford that simplification. The nice thing about this description is that it directly relates to the prefixes that are used for plotting: Axes -> ax; pyplot --> plt.
# The Axes interface fig, ax = plt.subplots() ax.plot(x, y) ax.set_xlabel(...) ax.set_ylabel(...) ax.set_title(...) # The pyplot interface plt.plot(x, y) plt.xlabel(...) plt.ylabel(...) plt.title(...)
Activity
story645 commented on Jul 25, 2023
truthfully I think this is mostly what I already use as @matplotlib because I think it's got the least cognitive overload/overhead. I forgot about the explicit/implicit thing, but I totally agree w/ you that it explains the difference between the two but not what they are.
jklymak commented on Jul 25, 2023
Agreed - implicit and explicit is hard to keep track of. OTOH, it could still be mentioned.
story645 commented on Jul 26, 2023
because I don't want to open up a PR for a one word change, while someone is changing those docs they should also remove the word Native from the interfaces heading as it doesn't add anything
jklymak commented on Jul 26, 2023
You can rephrase it if you like, but it is in contrast to "third-party" interfaces in the next section.
story645 commented on Jul 26, 2023
Then maybe rename the next section to "External (third party) Interfaces"? I think "Matplotib Interfaces" and the content of that section make it clear that these are the ones we ship?
ETA: It's kinda I think another variant of what this issue is about, internal/external, native/third-party describe the contrast/where to find but now what it is.
tacaswell commented on Jul 27, 2023
A disadvantage of "axes interface" vs "pyplot interface" is that it does not actually convey any information about what they are or why you would want to pick one over the other or why both exist. For someone new to the library it might as well be "flibber interface" and "jibberish interface".
With explicit / implicit there is at least some additional information in there about how they the two APIs differ and (maybe) an implication that they have equivalent capabilities. If people have read the zen of Python it also helps nudge them to using the explicit interface.
jklymak commented on Jul 27, 2023
In https://matplotlib.org/stable/users/explain/api_interfaces.html#api-interfaces we say "The explicit "Axes" interface" and "The implicit "pyplot" interface". Maybe just move that into this location as well.
Restructure interface section API Reference index page
Restructure interface section API Reference index page
Restructure interface section of API Reference index page
Restructure interface section of API Reference index page
Restructure interface section of API Reference index page
Restructure interface section of API Reference index page
zeehio commented on Sep 3, 2023
Coming from https://twitter.com/matplotlib/status/1698143656077599077?s=20
The most effective way to avoid confusion between interfaces for users is to say "import X is discouraged, please use import Y instead".
So if there was an import matplotlib.axes as plt interface that provided figure(), subplots(), etc and left plot() out, it would be easier for users to tell "this is what matplotlib devs want me to use" vs "this is what I have always used" and then adapt and ask questions about it.
Autocomplete would tell us users what best practice is.
Thanks for all your work!
jklymak commented on Sep 3, 2023
Yes we have that, but it's not merged yet. Should be in my opinion. https://github.com/matplotlib/mpl-gui
DOC: Clarify interface terminology
DOC: Clarify interface terminology