Please do not change kwarg name, it is a (subtle) api break for anyone who is using**dd to pass in kwargs.

The point is that if anybody passestrans= as a kwarg, it is already broken:

$ grep -re 'def draw_image' lib/matplotliblib/matplotlib/backends/backend_pgf.py:    def draw_image(self, gc, x, y, im, transform=None):lib/matplotlib/backends/backend_template.py:    def draw_image(self, gc, x, y, im):lib/matplotlib/backends/backend_ps.py:    def draw_image(self, gc, x, y, im, transform=None):lib/matplotlib/backends/backend_svg.py:    def draw_image(self, gc, x, y, im, transform=None):lib/matplotlib/backends/backend_gdk.py:    def draw_image(self, gc, x, y, im):lib/matplotlib/backends/backend_pdf.py:    def draw_image(self, gc, x, y, im, transform=None):lib/matplotlib/backends/backend_wx.py:    def draw_image(self, gc, x, y, im):lib/matplotlib/backends/backend_cairo.py:    def draw_image(self, gc, x, y, im):lib/matplotlib/backend_bases.py:    def draw_image(self, gc, x, y, im, trans=None):

The base class isthe only one calling ittrans, which leaves a trap for anybody using**dd to pass in the keyword arguments.

That is fun.

attn@mdboom I am inclined to accept this change and an API change entry for it.

Agreed. Let's fix this to be consistent (transform everywhere) and add a note inapi_changes.rst.

and add a note inapi_changes.rst.

If I see correctly, it's already covered byhttps://github.com/matplotlib/matplotlib/blob/master/doc/api/api_changes/2015-12-30_draw_image.rst -- if I added another note, there would be two API changes fordraw_image() listed for matplotlib 2.0. So shall we just leave it at that?

eh, yeah there is an entry for it, but just amend it to note this particular issue, as it isn't obvious from the current item that there is this change as well.

Well, from the current item it isn't obvious at all what has changed:

The draw_image method implemented by backends has changed its interface.

This change is only relevant if the backend declares that it is able to transform images by returning True from option_scale_image. See the draw_image docstring for more information.

Both sentences apply to my PR as well, which just changes the changed interface. Sorry, I'm not trying to be a nuisance, but I cannot come up with a way that explicitly mentions my change without sounding silly (and confusing).

Also note that the interface change in that note belongs to#5718, which added thetrans keyword in the first place, in an attempt to document the interface already present in the subclasses:
https://github.com/matplotlib/matplotlib/pull/5718/files#diff-504c288d675954e4e24de83a19242f4dR518

I'm just changing this to correctly call ittransform, which has been used in subclasses even before#5718 was proposed:https://github.com/matplotlib/matplotlib/pull/5718/files#diff-2623790aa8493ba82ef737fe0e63274dL1601

So this is not actually an API change. Nobody can have usedtrans= as a keyword argument, because it wouldn't have worked.

Is this convincing?

Ah, I see your point abouttrans. So, you are merely correcting a mistake before it reaches a release. Point taken.

Explanation: It's not an "image instance", and the renderer does not have any notion of axes (as far as I can see).draw_image() is used both for axes and figure images.