How does unpacking in fig, ax = plt.subplots() work for more than one subplot?

Question

I'm using python 2.7.

I've used the following code and applied it to my script: http://matplotlib.org/examples/event_handling/data_browser.html

Now, I'm trying to figure some of the specific around how it works. Eg:

fig, (ax, ax2) = plt.subplots(2, 1)

From what I know about using commas in python, it's used for unpacking. But in the code above, I can't relly understand what is being unpacked and why in that manner. Is:

fig, (ax, ax2) = plt.subplots(2, 1)

the same as:

fig, ax, ax2 = plt.subplots(2, 1)

as in this code from matplotlib faq?:

fig, ax_lst = plt.subplots(2, 2)  # a figure with a 2x2 grid of Axes

does fig automatically equal to fig = plt.figure()?

Answer 1

Looking at the plt.subplots() documentation, you find that it returns

fig : matplotlib.figure.Figure object
ax : Axes object or array of Axes objects. ax can be either a single matplotlib.axes.Axes object or an array of Axes objects if more than one subplot was created. The dimensions of the resulting array can be controlled with the squeeze keyword, see above.

Examples of usage cases are given below the function definition in the documentation.

So from this we learn that the return of plt.subplots is always a tuple. Tuples can be unpacked using the comma,

fig, ax = plt.subplots()

The first element is a matplotlib.figure.Figure, which you you could indeed also get by calling plt.figure().

The second element of the tuple ax can be a tuple as well, depending on the arguments used. If n rows or columns are created, ax is an n-tuple. This tuple can be unpacked again,

fig, (ax1, ax2) = plt.subplots(nrows=2)

If more than one row and column are created, ax will be a tuple of tuples, which again can be unpacked with a comma

fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(nrows=2, ncols=2)

---

Finally, as in python

a,b,c   = (5, 6, 7)  # works
a,b,c   = (5,(6,7))  # does not work
a,(b,c) = (5,(6,7))  # works

you cannot do fig, ax, ax2 = plt.subplots(2, 1), it will raise an error.