Marking WIP as I'd like to add a couple of examples.... Done

Re milestoning as a bug fix. The behaviour here is much better than in 3.0.0

Thanks for the careful review @timhoffm

I only had a quick look through the code, too quick to give a green checkmark here already, but in principle this looks good and it's definitely correct to not let the two cases of contrained layout=True or False differ substantially.

Now this PR introduces a new "Placing colorbars" example, which is a great idea. If that is the place to look for how to place colorbars in matplotlib, it's not yet complete, since there are lots of other ways, mostly via the cax argument.

• use axes created from fig.add_axes
• use axes created via gridspec with unequal width_ratios
• show use of fraction, anchor arguments
• use axes created via inset_axes (not tested yet, but should be a nice way to get axes outside the plot without taking space from the original axes); similar to demo_colorbar_with_inset_locator., but with the new core function.
• use Axes Divider; or at least link to existing demo_colorbar_with_axes_divider
• (at least one of the examples should show how to create a colorbar which is of the same height as a fixed-aspect plot)

Seeing how long that list has become, it might as well be suitable as tutorial?
Also, this list is sure too long to be handled within this PR.

My proposal would be for this PR to go in, and then if someone wants to add a couple more examples to the new example file, that would be great. I'd love to see how anchor and panchor work - I've never played with those or seen them in the wild. They could sure be better documented than they are now.

Great - any of those cases you think would be useful as tests we can add. Certainly I could break it in the future!

The test added here seems to have broken on Travis master somehow.

Actually, it was already broken when it was merged, but it's been 9 days since the PR build, so I'm not certain what might have affected it.

The test passes locally on master...

@QuLogic 3.1 tests are passing on Master. Was it 3.0.x tests that have trouble?

Well, I'm not sure what happened; it seems to have magically fixed itself. It was definitely failing right after merging this PR and also after merging the fix from #12366 that otherwise broke things.

@jklymak Since you asked for special cases for potential tests:

The following produces a rather strange figure

import numpy as np
import matplotlib.pyplot as plt
from matplotlib.gridspec import GridSpec

for CL in (True, False):
    mappable = []
    fig = plt.figure(constrained_layout=CL, figsize=(4.5, 4))
    gs = GridSpec(2,2, figure=fig)
    ax1 = fig.add_subplot(gs[0,0])
    ax2 = fig.add_subplot(gs[1,0])
    ax3 = fig.add_subplot(gs[1,1])
    for nn, ax in enumerate([ax1,ax2,ax3]):
        data = np.random.randn(10, 10)
        mappable += [ax.pcolormesh(data)]
    fig.colorbar(mappable[0], ax=[ax1,ax3])
    fig.suptitle('constrainedlayout %s'%CL)
    plt.show()

But constrainedlayout is perfectly capable of handling it:

In contrast, when you add another axes later on, it'll overlap, both with and without constrained layout.

import numpy as np
import matplotlib.pyplot as plt
from matplotlib.gridspec import GridSpec

for CL in (True, False):
    mappable = []
    fig = plt.figure(constrained_layout=CL, figsize=(4.5, 4))
    gs = GridSpec(2,2, figure=fig)
    ax1 = fig.add_subplot(gs[0,0])
    ax2 = fig.add_subplot(gs[1,0])
    ax3 = fig.add_subplot(gs[1,1])
    for nn, ax in enumerate([ax1,ax2,ax3]):
        data = np.random.randn(10, 10)
        mappable += [ax.pcolormesh(data)]
    fig.colorbar(mappable[0], ax=[ax1,ax3])
    ax3.remove()
    ax4 = fig.add_subplot(gs[0,1])
    fig.suptitle('constrainedlayout %s'%CL)
    plt.show()

Not sure if any of those should be considered valid or useful though.

Those were brain teasers. I'm OK w/ the first case inconsistency. Colorbar steals space from the axes you list, and there is no way for the third axes to know space was stolen from the other two without a draw-time hook like ConstrainedLayout.

The second case is a bit more concerning; I'd have thought ideally CL would forget about the lost axes, and move the colorbar over to the left. But... that's a pretty hard pathological case, so I'm not going to worry about it, unless there is a good use case for it, in which case it may be worth the effort.

Thanks a lot for sending these! Great examples...