[IPython-dev] Suggestions for easier understanding

Doug Blank doug.blank at gmail.com
Sun Feb 9 07:59:48 EST 2014


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)

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?

-Doug
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/ipython-dev/attachments/20140209/d9fa1804/attachment.html>


More information about the IPython-dev mailing list