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

[Damon M. <dam...@gm...>]

On Mon, Dec 10, 2012 at 6:27 PM, Joe Kington <jof...@gm...> wrote:
> On Mon, Dec 10, 2012 at 2:45 AM, Phil Elson <pel...@gm...> wrote:
>>
>> Hi Joe,
>>
>> Thanks for bringing this up, it is certainly valuable to highlight this on
>> the mailinglist. As you say, the change is hard to spot and, I agree, makes
>> library code supporting v1.1.1 and v1.2 harder than one would like.
>> Typically, anything which is going to break core APIs (even slightly) should
>> be documented under the "API Changes" page here
>> http://matplotlib.org/api/api_changes.html#changes-in-1-2-x .
>
>
> Thanks! I wasn't aware of that page! (and it does a very nice job of
> documenting the changes!)
>
>>
>> You will find there were quite a few changes made relating to transforms
>> which I think is entirely my doing, so at least we know who the guilty party
>> is :-)
>>
>> Thanks for spotting the example failure - I split these changes over many
>> separate pull requests and did scan the gallery for any noticeable changes,
>> but this one must have slipped the net.
>>
>> If you're still having problems with using the newer transform API, please
>> shout and I'd be happy to have a look for you.
>
>
> Will do, thanks for the offer!
>
>>
>>
>> All the best,
>>
>> Phil
>>
>>
>> On 9 December 2012 22:10, Joe Kington <jof...@gm...> wrote:
>>>
>>> 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 transform
>>> method when subclassing transforms.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_affine
>>> and the transform_path methods for compatibility with newer and older
>>> versions of matplotlib.
>>>
>>> Arguably, it should have always been done this way, but  based on
>>> examples/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
>>>
>>>
>>>
>>> ------------------------------------------------------------------------------
>>> LogMeIn Rescue: Anywhere, Anytime Remote support for IT. Free Trial
>>> Remotely access PCs and mobile devices and provide instant support
>>> Improve your efficiency, and focus on delivering more value-add services
>>> Discover what IT Professionals Know. Rescue delivers
>>> http://p.sf.net/sfu/logmein_12329d2d
>>> _______________________________________________
>>> Matplotlib-users mailing list
>>> Mat...@li...
>>> https://lists.sourceforge.net/lists/listinfo/matplotlib-users
>>>
>>
>

Is there anything we could do to give this important information a
little more visibility on the webpage? The webpage still indicates
that 1.2.0 is a development version. Perhaps we could update it to
say:

"1.2.0 The most current stable release. Click here to see what's new
since 1.1.1"

And have "Click here" link to the page Phil mentioned. Thoughts?

-- 
Damon McDougall
http://www.damon-is-a-geek.com
Institute for Computational Engineering Sciences
201 E. 24th St.
Stop C0200
The University of Texas at Austin
Austin, TX 78712-1229