[IPython-dev] Suggestions for easier understanding

[MinRK]

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.



>
> 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.

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.

-MinRK



>
> -Doug
>
> _______________________________________________
> 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/e36a89ff/attachment.html>