Confusion about Artist place in matplotlib hierarchy

Question

In this period I am working with matplotlib. I studied many examples, and was able to modify it to suit several of my needs. But I would like to better understand the general structure of the library. For this reason, apart reading a lot of tutorials on the web, I also purchased the ebook "Matplotlib for Python Developers", by Tosi. While it is full of good examples, I still don't fully grasp the relationships between all the different levels.

The book clearly explains that matplotlib has 3 main "modes":

1) pylab, to work similarly to Matlab

2) pyplot, to work in a procedural way

3) the full OO system

Concerning the objects of the OO system, the book lists 3 levels:

1) FigureCanvas, the container class for the Figure instance

2) Figure, the container for Axes instances

3) Axes, the areas that hold the basic elements (lines, points, text...)

The problem is that, by reading the official documentation, I also encountered the notions of Backends and Artists. While I understand the basic logic of them, I am quite confused about their role respect to the previous classifications. In particular, are the Artists in an intermediate level between the FigureCanvas and the Figure, or is that hierarchy not suitable in this case?

I would be grateful to receive some clarifications, eventually also referring to other documentation I could have missed. Thanks.

Answer 1

I do not like those layers

• pylab : massive namespace dump that pulls in everything from pyplot and numpy. It is not a 'layer' so much as a very cluttered name space.
• pyplot : state-machine based layer (it knows what your 'current axes' and 'current figure' are and applies the functions to that axes/figure. You should use this only when you are playing around in an interactive terminal (other than plt.subplots or plt.figure for setting up the figure/axes objects). Making a distiction between this layer and pylab is dumb. This is the layer that makes it 'like MATLAB'
• the OO layer : which is what you should use in all of your scripts

Figures are the top level container objects. They can contain Axes objects and Artist objects (technically Axes are Artists, but it is useful for pedagogical reasons to distinguish between the Axes objects in a figure and the other artists (such as text objects) that are in the Figure, but not associated with an Axes) and know about the Canvas object. Each Axes can contain more Artists objects. The Artists are the useful things you want to put on your graph (lines, text, images, etc). Artists know how to draw themselves on a Canvas. When you call fig.savefig (or render the figure to the screen) the Figure object loops over all of it's children and tell them to draw them selves on to it's Canvas.

The different Backends provide implementations of the Canvas objects, hence the same figure can be rendered to a raster or vector graphic by just changing the Canvas object that is being used.

Unless you want to write a new backend, many of these details are not important and the fact that matplotlib hides them from you is why it is useful.

If the book couldn't get this correct, I would take everything it says with grain of salt.