[Matplotlib-users] Undocumented transform API change between 1.1 and 1.2?

[Joe K. <jof...@gm...>]

Hi folks,

At some point transforms.Transform was slightly refactored. (Particularly,
this commit:
https://github.com/matplotlib/matplotlib/commit/8bbe2e55f29b28ba558504b27596b8e36a087c1c)
 This changed what methods need to be overridden when subclassing
Transform.

All in all, it seems like a very sensible change, but it led to some very
hard-to-find bugs in some of my code that subclasses transforms.Transform.
I thought I would mention it on the mailing list for anyone else that uses
custom projections. Forgive me if it was mentioned earlier and I just
didn't notice.

With versions 1.1.x and older, one had to directly implement a
transformmethod when subclassingtransforms.Transform,
otherwise a NotImplemented error would be raised.

With versions 1.2.x and newer, the preferred way appears to be to implement
things in a separate transform_affine or transform_non_affine method and
not explicitly implement a transform method.

If you implement the non-affine portion directly in the transform method
without overriding transform_non_affine, it leads to strange drawing bugs
with v1.2 that did not occur with older versions.  (For example, this broke
one of the examples in the gallery between 1.1. and 1.2:
http://matplotlib.org/1.1.1/examples/api/custom_projection_example.html
http://matplotlib.org/1.2.0/examples/api/custom_projection_example.html . I
just submitted a pull request to update the example, by the way.)

On the other hand, for compatibility with versions 1.1 and older, you have
to explicitly implement the transform method as well, otherwise you'll get
the NotImplemented error.

Therefore, now one needs to explicitly implement *_both_* the
transform_non_affine and transform methods of a custom non-affine transform
for compatibility with 1.1 and older as well as 1.2 and newer.

Similarly, one needs to implement* _both_ *the transform_path_non_affineand the
transform_path methods for compatibility with newer and older versions of
matplotlib.

Arguably, it should have always been done this way, but  based
onexamples/api/custom_projection_example.py,
I (and I suspect many other people as well)  implemented the transform
directly as the transform method when subclassing Transform, instead of
separately in a transform_affine or transform_non_affine method.

Is this a large enough change to warrant a mention in the changelog? (On
the other hand, the mailing list probably gets a lot more eyes on it than
the changelog...)

Thanks!
-Joe