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(...)