<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">Thanks for the feedback; comments below:</div><div class="gmail_quote"><br></div><div class="gmail_quote">On Sun, Feb 9, 2014 at 4:17 PM, MinRK <span dir="ltr"><<a href="mailto:benjaminrk@gmail.com" target="_blank">benjaminrk@gmail.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><br><br><div class="gmail_quote"><div class="">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>
<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 class=""><div><br></div></div></div></div></div></blockquote><div><br></div><div>Sure, demonstrating the ? is even better.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div class=""><div></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><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></div></div></blockquote><div><br></div><div><br></div><div>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?)</div>
<div><br></div><div>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.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div></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></div></div></blockquote><div><br></div><div>Yes, of course, these aren't designed for beginners. But just pointing out that there are places where implementation details pop through.</div><div><br>
</div><div>-Doug</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div></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><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" target="_blank">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>
<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>