Probably should make the documentation consistent with the code?

Not sure about this, because the default behave somewhat weirdly…
Here is the default looking arrow:

Notice that the width is really small.

If we set the width to something more sensible (in this case width=0.05):

which doesn't make sense at all.

With the original defaults stated in the documentation it looks like this:

Perhaps the linear dependance is really the problem here.

What does the default arrow now look like?

I am mostly 👎 on this change, but am open to be convinced otherwise.

The history of this seems to be, the default was changed to 20 (but the docs not updated) in 2013 in (7458091 / #1186) because the head was invisible.

The default width of 0.001 seems to go all the way back to when this code came into the code base de93f2b

I think this either needs to also change the default width, or just update the docs to match the code.

import matplotlib.patches as mpatches

fig, ax = plt.subplots()

scales = [3, 20]
widths = [0.001, .01, .05]

for k, scale in enumerate(scales):
    ax.axvline(k, color='k', ls=':')
    ax.axvline(k+.5, color='k', ls=':')
    for j, width in enumerate(widths):
        a = mpatches.FancyArrow(k, j, .5, 0, width=width, head_width=scale*width)
        ax.add_patch(a)

ax.set_ylim(-1, j+1)
ax.set_xlim(-.25, k + 1)

ax.set_xticks(np.arange(len(scales)) + .25)
ax.set_xticklabels(map(str, scales))
ax.set_yticks(range(len(widths)))
ax.set_yticklabels(map(str, widths))

ax.set_xlabel('default scale')
ax.set_ylabel('default width')

attn @dmcdougall @pelson

Part of the real problem is that Arrow and FancyArrow make sense (if at all) only if drawn with a transform that makes the x and y scales identical. Hence they are of very limited utility. I think both should be deprecated--unless I am missing some application for which they are well-suited. Nevertheless, the present default of having the head width be 20 times the tail width seems a bit extreme.

What are the units for the width? It's clearly not pixels, but maybe it's time to increase the default, since it seems to be rounded up to one pixel anyway...

After discussion with @efiring and @dopplershift we decided to merge this as-is and then deprecate this Artist.

Backported to v2.x via 848cfe5.