<div dir="ltr"><div class="gmail_extra"><br><br><div class="gmail_quote">On Sun, Feb 9, 2014 at 4:59 AM, Doug Blank <span dir="ltr"><<a href="mailto:doug.blank@gmail.com" target="_blank">doug.blank@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div>Devs,</div><div><br></div><div>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:</div>
<div><br></div><div><a href="http://nbviewer.ipython.org/github/ipython/ipython/blob/master/examples/widgets/Part%202%20-%20Events.ipynb" target="_blank">http://nbviewer.ipython.org/github/ipython/ipython/blob/master/examples/widgets/Part%202%20-%20Events.ipynb</a><br>
</div><div><br></div><div>it would be easy to change:</div><br>print(widgets.Widget.on_trait_change.__doc__)<br><br>to:<div><br></div><div>help(widgets.Widget.on_trait_change)<br></div></div></blockquote><div><br></div><div>
Or the IPython way: `widgets.Widget.on_trait_change?`</div><div>It's been many years since I called `help` on something.</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><div></div><div><br></div><div>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:</div>
<div><br></div>"""<br>def on_value_change(name, value):<br> print(value)<br>int_range.on_trait_change(on_value_change, 'value')<div>"""</div><div><br></div><div>might be easier to understand if it were:</div>
<div><br></div>"""<br>def callback(name, new_value):<br> print(name, "changed to", new_value)<br>int_range.on_value_change(callback, 'value')<div>"""</div><div><br></div>
<div>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.</div>
<div><br></div><div>What do you think?</div></div></blockquote><div><br></div><div>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.</div>
<div><br></div><div>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.</div>
<div><br></div><div>-MinRK</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><span class=""><font color="#888888"><div><br></div><div>-Doug</div></font></span></div>
<br>_______________________________________________<br>
IPython-dev mailing list<br>
<a href="mailto:IPython-dev@scipy.org">IPython-dev@scipy.org</a><br>
<a href="http://mail.scipy.org/mailman/listinfo/ipython-dev" target="_blank">http://mail.scipy.org/mailman/listinfo/ipython-dev</a><br>
<br></blockquote></div><br></div></div>