Repository navigation
Expand the explanation of the Object-Oriented interface #18249
Description
Problem
Most of the content of https://matplotlib.org/tutorials/introductory/lifecycle.html#a-note-on-the-object-oriented-api-vs-pyplot will not make sense to a user new matplotlib ( and likely new to python). The text makes several assumptions about the reader:
- They know what object oriented means
- They know what a state-based interface is
- They know what the Matlab interface is like
- They understand "we utilize an instance of axes.Axes in order to render visualizations on an instance of figure.Figure."
- Doesn't pyplot also do this under the hood?
As a piece of anecdata I was fairly confused by all of this both years ago when I started using matplotlib and more recently when I started to make more complex and interactive matplotlib plots.
Suggested Improvement
Add deeper explanations/definitions for all the above bullet points. As well it would be great to expand on the note that simply says:
In general, try to use the object-oriented interface over the pyplot interface.
with a justification of that claim.
A related example is https://matplotlib.org/gallery/api/agg_oo_sgskip.html which could also use some more explanation or perhaps removal.
Activity
ianhi commented on Aug 14, 2020
Annoyingly this issue was not automatically labelled with the Documentation tag like it should have been following #18161
I'm trying to look into that but if anyone has any ideas 🤷♂️
edit labelling issue should be fixed by #18250
mwaskom commented on Aug 14, 2020
See also: https://matplotlib.org/tutorials/introductory/usage.html#the-object-oriented-interface-and-the-pyplot-interface
pspiagicw commented on Nov 8, 2021
Has this issue been resolved ?
timhoffm commented on Feb 7, 2022
AFAICS partially addressed by #21877.
jklymak commented on Feb 18, 2022
@ianhi can we close this, or do you have feedback on #21877 which is now in the devdocs: https://matplotlib.org/devdocs/users/explain/api_interfaces.html#matplotlib-application-interfaces-apis That is just a start and we should continue to refine it.
ianhi commented on Mar 5, 2022
@jklymak that looks good!
I do think that that should be linked to from various place in the docs. e.g. the pyplot tutorial: https://matplotlib.org/devdocs/tutorials/introductory/pyplot.html#sphx-glr-tutorials-introductory-pyplot-py which still uses the object-oriented terminology
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used
DOC: Add links to explicit vs implicit API everywhere "OO" is used