From 080f926c8e33fc872ffdc4d62a3d4533339b7d6c Mon Sep 17 00:00:00 2001 From: Torsten Bittner Date: Tue, 20 Jan 2015 17:51:04 -0800 Subject: [PATCH 1/2] Add documentation for interact function. --- IPython/html/widgets/interaction.py | 61 +++++++++++++++++++++++++++-- 1 file changed, 57 insertions(+), 4 deletions(-) diff --git a/IPython/html/widgets/interaction.py b/IPython/html/widgets/interaction.py index d21f12f30..2f2366dd1 100644 --- a/IPython/html/widgets/interaction.py +++ b/IPython/html/widgets/interaction.py @@ -227,12 +227,65 @@ def interactive(__interact_f, **kwargs): return container def interact(__interact_f=None, **kwargs): - """interact(f, **kwargs) + """ + Displays interactive widgets which are tied to a function. + Expects the first argument to be a function. Parameters to this function are + passed in as keyword arguments (**kwargs). Can be used as a decorator (see + examples). + + Returns + ------- + __interact_f with interactive widget attached to it. + + Parameters + ---------- + __interact_f : function + The function to which the interactive widgets are tied. The **kwargs + should match the function signature. Passed to :func:`interactive()` + **kwargs : various, optional + An interactive widget will be created for each keyword argument. Passed + to :func:`interactive()` + + Examples + -------- + Renders an interactive text field that shows the greeting with the passed in + text. - Interact with a function using widgets.""" + 1. Invocation of interact as a function + def greeting(text="World"): + print "Hello {}".format(text) + interact(greeting, text="IPython Widgets") + + 2. Invocation of interact as a decorator + @interact + def greeting(text="World"): + print "Hello {}".format(text) + + 3. Invocation of interact as a decorator with named parameters + @interact(text="IPython Widgets") + def greeting(text="World"): + print "Hello {}".format(text) + + Renders an interactive slider widget and prints square of number. + + 1. Invocation of interact as a function + def square(num=1): + print "{} squared is {}".format(num, num*num) + interact(square, num=5) + + 2. Invocation of interact as a decorator + @interact + def square(num=2): + print "{} squared is {}".format(num, num*num) + + 3. Invocation of interact as a decorator with named parameters + @interact(num=5) + def square(num=2): + print "{} squared is {}".format(num, num*num) + """ # positional arg support in: https://gist.github.com/8851331 if __interact_f is not None: - # This branch handles the cases: + # This branch handles the cases 1 and 2 # 1. interact(f, **kwargs) # 2. @interact # def f(*args, **kwargs): @@ -249,7 +302,7 @@ def interact(__interact_f=None, **kwargs): display(w) return f else: - # This branch handles the case: + # This branch handles the case 3 # @interact(a=30, b=40) # def f(*args, **kwargs): # ... From d5a7879a262546a24458a005597bb01c75fcf032 Mon Sep 17 00:00:00 2001 From: Torsten Bittner Date: Wed, 21 Jan 2015 12:25:28 -0800 Subject: [PATCH 2/2] Add documentation for interactive function. --- IPython/html/widgets/interaction.py | 30 ++++++++++++++++++++++------- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/IPython/html/widgets/interaction.py b/IPython/html/widgets/interaction.py index 2f2366dd1..a94389479 100644 --- a/IPython/html/widgets/interaction.py +++ b/IPython/html/widgets/interaction.py @@ -160,7 +160,23 @@ def _widgets_from_abbreviations(seq): return result def interactive(__interact_f, **kwargs): - """Build a group of widgets to interact with a function.""" + """ + Builds a group of interactive widgets tied to a function and places the + group into a Box container. + + Returns + ------- + container : a Box instance containing multiple widgets + + Parameters + ---------- + __interact_f : function + The function to which the interactive widgets are tied. The **kwargs + should match the function signature. + **kwargs : various, optional + An interactive widget is created for each keyword argument that is a + valid widget abbreviation. + """ f = __interact_f co = kwargs.pop('clear_output', True) manual = kwargs.pop('__manual', False) @@ -215,7 +231,7 @@ def interactive(__interact_f, **kwargs): # Wire up the widgets # If we are doing manual running, the callback is only triggered by the button # Otherwise, it is triggered for every trait change received - # On-demand running also suppresses running the fucntion with the initial parameters + # On-demand running also suppresses running the function with the initial parameters if manual: manual_button.on_click(call_f) else: @@ -230,12 +246,12 @@ def interact(__interact_f=None, **kwargs): """ Displays interactive widgets which are tied to a function. Expects the first argument to be a function. Parameters to this function are - passed in as keyword arguments (**kwargs). Can be used as a decorator (see - examples). + widget abbreviations passed in as keyword arguments (**kwargs). Can be used + as a decorator (see examples). Returns ------- - __interact_f with interactive widget attached to it. + f : __interact_f with interactive widget attached to it. Parameters ---------- @@ -243,8 +259,8 @@ def interact(__interact_f=None, **kwargs): The function to which the interactive widgets are tied. The **kwargs should match the function signature. Passed to :func:`interactive()` **kwargs : various, optional - An interactive widget will be created for each keyword argument. Passed - to :func:`interactive()` + An interactive widget is created for each keyword argument that is a + valid widget abbreviation. Passed to :func:`interactive()` Examples --------