[IPython-dev] Suggestions for easier understanding

[Doug Blank]

Thanks for the feedback; comments below:

On Sun, Feb 9, 2014 at 4:17 PM, MinRK <benjaminrk at gmail.com> wrote:

>
>
> On Sun, Feb 9, 2014 at 4:59 AM, Doug Blank <doug.blank at gmail.com> wrote:
>
>> Devs,
>>
>> In looking over the new example notebooks (which are great to learn the
>> new features), I see a couple of places that could use a little polish to
>> make them easier to understand, especially for those that aren't expert
>> programmers. For example, taking a look at:
>>
>>
>> http://nbviewer.ipython.org/github/ipython/ipython/blob/master/examples/widgets/Part%202%20-%20Events.ipynb
>>
>> it would be easy to change:
>>
>> print(widgets.Widget.on_trait_change.__doc__)
>>
>> to:
>>
>> help(widgets.Widget.on_trait_change)
>>
>
> Or the IPython way: `widgets.Widget.on_trait_change?`
> It's been many years since I called `help` on something.
>
>
Sure, demonstrating the ? is even better.


>
>
>>
>> which actually looks better, is more informative (even for experts), and
>> hides unnecessary implementation details. Another suggestion is to consider
>> hiding the implementational "trait" details. One could use the interface by
>> just thinking in terms of standard Python terms, such as "attribute" or
>> "value".  For example, the code:
>>
>> """
>> def on_value_change(name, value):
>>     print(value)
>> int_range.on_trait_change(on_value_change, 'value')
>> """
>>
>> might be easier to understand if it were:
>>
>> """
>> def callback(name, new_value):
>>     print(name, "changed to", new_value)
>> int_range.on_value_change(callback, 'value')
>> """
>>
>> Another reason to consider using the method name "on_value_change" rather
>> than "on_trait_change" is that I'm replicating this API for a different
>> kernel, and the implementation doesn't use "traitlets". Doesn't seem
>> necessary to have this implementational detail show in the UI.
>>
>> What do you think?
>>
>
> The events themselves are an implementation detail, and traitlets are the
> most logical way to implement them in IPython, so we use the traitlets API.
> I don't think there is a good reason to hide that. The part that is generic
> about widgets is some mechanism for synchronizing state (the messages), and
> we do not intend to enforce any kind of uniformity in APIs on kernels.
>
>

My point is that it would be nice to have uniformity across kernels by
using the same method names to attach the callbacks. But having "trait" in
the API is unnecessary, and requires further explanation to the students.
(And what happens in the future if you re-implement the mechanism with a
different paradigm?)

I'm not suggesting to hide the the fact that you use traitlets; just
suggesting that it doesn't need to be in the API.


> I think there is a doc missing that's at the right level - what is the
> part of widgets that's actually generic and language agnostic, and what is
> just part of the IPython kernel implementation.
>
>
Yes, of course, these aren't designed for beginners. But just pointing out
that there are places where implementation details pop through.

-Doug


> -MinRK
>
>
>
>>
>> -Doug
>>
>> _______________________________________________
>> IPython-dev mailing list
>> IPython-dev at scipy.org
>> http://mail.scipy.org/mailman/listinfo/ipython-dev
>>
>>
>
> _______________________________________________
> IPython-dev mailing list
> IPython-dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20140209/bca12672/attachment.html>