Skip to content

[Doc]: Revisit interface terminology: Axes interface / pyplot interface #26388

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
timhoffm opened this issue Jul 25, 2023 · 9 comments
Open

[Doc]: Revisit interface terminology: Axes interface / pyplot interface #26388

timhoffm opened this issue Jul 25, 2023 · 9 comments
Labels
Documentation

Comments

@timhoffm
Copy link
Member

timhoffm commented Jul 25, 2023 •
edited
Loading

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(...)
@story645
Copy link
Member

story645 commented Jul 25, 2023 •
edited
Loading

  1. the Axes interface / the pyplot interface

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
Copy link
Member

jklymak commented Jul 25, 2023

Agreed - implicit and explicit is hard to keep track of. OTOH, it could still be mentioned.

@story645
Copy link
Member

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
Copy link
Member

jklymak commented Jul 26, 2023

You can rephrase it if you like, but it is in contrast to "third-party" interfaces in the next section.

@story645
Copy link
Member

story645 commented Jul 26, 2023 •
edited
Loading

but it is in contrast to "third-party" interfaces in the next sectio

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
Copy link
Member

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
Copy link
Member

jklymak commented 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.

timhoffm added a commit to timhoffm/matplotlib that referenced this issue Jul 27, 2023
@timhoffm
Restructure interface section API Reference index page
e4204d8 
- switch to Axes interface / pyplot interface terminology (matplotlib#26388)
- Reduce the interface description to very compact
  two-sentence descriptions and refer to the interface
  page for everything else.

  The focus here is to point the users to relevant API resources
  for the respective interfaces, not to discuss these interfaces
  in detail. The latter is the task of
  https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html
  and I will add some missing pieces there in a follow-up PR.
timhoffm added a commit to timhoffm/matplotlib that referenced this issue Jul 27, 2023
@timhoffm
Restructure interface section API Reference index page
8003178 
- switch to Axes interface / pyplot interface terminology (matplotlib#26388)
- Reduce the interface description to very compact
  two-sentence descriptions and refer to the interface
  page for everything else.

  The focus here is to point the users to relevant API resources
  for the respective interfaces, not to discuss these interfaces
  in detail. The latter is the task of
  https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html
  and I will add some missing pieces there in a follow-up PR.
timhoffm added a commit to timhoffm/matplotlib that referenced this issue Jul 27, 2023
@timhoffm
Restructure interface section of API Reference index page
f7dcf3f 
- switch to Axes interface / pyplot interface terminology (matplotlib#26388)
- Reduce the interface description to very compact
  two-sentence descriptions and refer to the interface
  page for everything else.

  The focus here is to point the users to relevant API resources
  for the respective interfaces, not to discuss these interfaces
  in detail. The latter is the task of
  https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html
  and I will add some missing pieces there in a follow-up PR.
@timhoffm timhoffm mentioned this issue Jul 27, 2023
Merged
timhoffm added a commit to timhoffm/matplotlib that referenced this issue Jul 28, 2023
@timhoffm
Restructure interface section of API Reference index page
e272b5c 
- switch to Axes interface / pyplot interface terminology (matplotlib#26388)
- Reduce the interface description to very compact
  two-sentence descriptions and refer to the interface
  page for everything else.

  The focus here is to point the users to relevant API resources
  for the respective interfaces, not to discuss these interfaces
  in detail. The latter is the task of
  https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html
  and I will add some missing pieces there in a follow-up PR.

  Co-authored-by: hannah <story645@gmail.com>
timhoffm added a commit to timhoffm/matplotlib that referenced this issue Jul 28, 2023
@timhoffm
Restructure interface section of API Reference index page
bab0b5b 
- switch to Axes interface / pyplot interface terminology (matplotlib#26388)
- Reduce the interface description to very compact
  two-sentence descriptions and refer to the interface
  page for everything else.

  The focus here is to point the users to relevant API resources
  for the respective interfaces, not to discuss these interfaces
  in detail. The latter is the task of
  https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html
  and I will add some missing pieces there in a follow-up PR.

  Co-authored-by: hannah <story645@gmail.com>
timhoffm added a commit to timhoffm/matplotlib that referenced this issue Jul 29, 2023
@timhoffm
Restructure interface section of API Reference index page
49b2728 
- switch to Axes interface / pyplot interface terminology (matplotlib#26388)
- Reduce the interface description to very compact
  two-sentence descriptions and refer to the interface
  page for everything else.

  The focus here is to point the users to relevant API resources
  for the respective interfaces, not to discuss these interfaces
  in detail. The latter is the task of
  https://matplotlib.org/devdocs/users/explain/figure/api_interfaces.html
  and I will add some missing pieces there in a follow-up PR.

  Co-authored-by: hannah <story645@gmail.com>
@paniterka paniterka mentioned this issue Aug 29, 2023
Closed
@zeehio
Copy link

zeehio commented 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
Copy link
Member

jklymak commented Sep 3, 2023

Yes we have that, but it's not merged yet. Should be in my opinion. https://github.com/matplotlib/mpl-gui

@mofojed mofojed mentioned this issue Oct 16, 2023
Open
@timhoffm timhoffm mentioned this issue Nov 18, 2023
Closed
1 task
timhoffm added a commit to timhoffm/matplotlib that referenced this issue Apr 4, 2024
@timhoffm
DOC: Clarify interface terminology
15a88db 
as proposed in https://github
.com/matplotlib/issues/21817#issuecomment-983705359
and matplotlib#26388

and already used in 26402.

Closes matplotlib#21817.
@timhoffm timhoffm mentioned this issue Apr 4, 2024
Merged
timhoffm added a commit to timhoffm/matplotlib that referenced this issue Apr 7, 2024
@timhoffm
DOC: Clarify interface terminology
da1551f 
as proposed in https://github
.com/matplotlib/issues/21817#issuecomment-983705359
and matplotlib#26388

and already used in 26402.

Closes matplotlib#21817.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@zeehio @tacaswell @story645 @jklymak @timhoffm