Show More
@@ -1,256 +1,256 b'' | |||||
1 | """Interact with functions using widgets.""" |
|
1 | """Interact with functions using widgets.""" | |
2 |
|
2 | |||
3 | #----------------------------------------------------------------------------- |
|
3 | #----------------------------------------------------------------------------- | |
4 | # Copyright (c) 2013, the IPython Development Team. |
|
4 | # Copyright (c) 2013, the IPython Development Team. | |
5 | # |
|
5 | # | |
6 | # Distributed under the terms of the Modified BSD License. |
|
6 | # Distributed under the terms of the Modified BSD License. | |
7 | # |
|
7 | # | |
8 | # The full license is in the file COPYING.txt, distributed with this software. |
|
8 | # The full license is in the file COPYING.txt, distributed with this software. | |
9 | #----------------------------------------------------------------------------- |
|
9 | #----------------------------------------------------------------------------- | |
10 |
|
10 | |||
11 | #----------------------------------------------------------------------------- |
|
11 | #----------------------------------------------------------------------------- | |
12 | # Imports |
|
12 | # Imports | |
13 | #----------------------------------------------------------------------------- |
|
13 | #----------------------------------------------------------------------------- | |
14 |
|
14 | |||
15 | from __future__ import print_function |
|
15 | from __future__ import print_function | |
16 |
|
16 | |||
17 | try: # Python >= 3.3 |
|
17 | try: # Python >= 3.3 | |
18 | from inspect import signature, Parameter |
|
18 | from inspect import signature, Parameter | |
19 | except ImportError: |
|
19 | except ImportError: | |
20 | from IPython.utils.signatures import signature, Parameter |
|
20 | from IPython.utils.signatures import signature, Parameter | |
21 | from inspect import getcallargs |
|
21 | from inspect import getcallargs | |
22 |
|
22 | |||
23 | from IPython.core.getipython import get_ipython |
|
23 | from IPython.core.getipython import get_ipython | |
24 | from IPython.html.widgets import (Widget, TextWidget, |
|
24 | from IPython.html.widgets import (Widget, TextWidget, | |
25 | FloatSliderWidget, IntSliderWidget, CheckboxWidget, DropdownWidget, |
|
25 | FloatSliderWidget, IntSliderWidget, CheckboxWidget, DropdownWidget, | |
26 | ContainerWidget, DOMWidget) |
|
26 | ContainerWidget, DOMWidget) | |
27 | from IPython.display import display, clear_output |
|
27 | from IPython.display import display, clear_output | |
28 | from IPython.utils.py3compat import string_types, unicode_type |
|
28 | from IPython.utils.py3compat import string_types, unicode_type | |
29 |
from IPython.utils.traitlets import HasTraits, |
|
29 | from IPython.utils.traitlets import HasTraits, Any, Unicode | |
30 |
|
30 | |||
31 | empty = Parameter.empty |
|
31 | empty = Parameter.empty | |
32 |
|
32 | |||
33 | #----------------------------------------------------------------------------- |
|
33 | #----------------------------------------------------------------------------- | |
34 | # Classes and Functions |
|
34 | # Classes and Functions | |
35 | #----------------------------------------------------------------------------- |
|
35 | #----------------------------------------------------------------------------- | |
36 |
|
36 | |||
37 |
|
37 | |||
38 | def _matches(o, pattern): |
|
38 | def _matches(o, pattern): | |
39 | """Match a pattern of types in a sequence.""" |
|
39 | """Match a pattern of types in a sequence.""" | |
40 | if not len(o) == len(pattern): |
|
40 | if not len(o) == len(pattern): | |
41 | return False |
|
41 | return False | |
42 | comps = zip(o,pattern) |
|
42 | comps = zip(o,pattern) | |
43 | return all(isinstance(obj,kind) for obj,kind in comps) |
|
43 | return all(isinstance(obj,kind) for obj,kind in comps) | |
44 |
|
44 | |||
45 |
|
45 | |||
46 | def _get_min_max_value(min, max, value=None, step=None): |
|
46 | def _get_min_max_value(min, max, value=None, step=None): | |
47 | """Return min, max, value given input values with possible None.""" |
|
47 | """Return min, max, value given input values with possible None.""" | |
48 | if value is None: |
|
48 | if value is None: | |
49 | if not max > min: |
|
49 | if not max > min: | |
50 | raise ValueError('max must be greater than min: (min={0}, max={1})'.format(min, max)) |
|
50 | raise ValueError('max must be greater than min: (min={0}, max={1})'.format(min, max)) | |
51 | value = min + abs(min-max)/2 |
|
51 | value = min + abs(min-max)/2 | |
52 | value = type(min)(value) |
|
52 | value = type(min)(value) | |
53 | elif min is None and max is None: |
|
53 | elif min is None and max is None: | |
54 | if value == 0.0: |
|
54 | if value == 0.0: | |
55 | min, max, value = 0.0, 1.0, 0.5 |
|
55 | min, max, value = 0.0, 1.0, 0.5 | |
56 | elif value == 0: |
|
56 | elif value == 0: | |
57 | min, max, value = 0, 1, 0 |
|
57 | min, max, value = 0, 1, 0 | |
58 | elif isinstance(value, (int, float)): |
|
58 | elif isinstance(value, (int, float)): | |
59 | min, max = (-value, 3*value) if value > 0 else (3*value, -value) |
|
59 | min, max = (-value, 3*value) if value > 0 else (3*value, -value) | |
60 | else: |
|
60 | else: | |
61 | raise TypeError('expected a number, got: %r' % value) |
|
61 | raise TypeError('expected a number, got: %r' % value) | |
62 | else: |
|
62 | else: | |
63 | raise ValueError('unable to infer range, value from: ({0}, {1}, {2})'.format(min, max, value)) |
|
63 | raise ValueError('unable to infer range, value from: ({0}, {1}, {2})'.format(min, max, value)) | |
64 | if step is not None: |
|
64 | if step is not None: | |
65 | # ensure value is on a step |
|
65 | # ensure value is on a step | |
66 | r = (value - min) % step |
|
66 | r = (value - min) % step | |
67 | value = value - r |
|
67 | value = value - r | |
68 | return min, max, value |
|
68 | return min, max, value | |
69 |
|
69 | |||
70 | def _widget_abbrev_single_value(o): |
|
70 | def _widget_abbrev_single_value(o): | |
71 | """Make widgets from single values, which can be used as parameter defaults.""" |
|
71 | """Make widgets from single values, which can be used as parameter defaults.""" | |
72 | if isinstance(o, string_types): |
|
72 | if isinstance(o, string_types): | |
73 | return TextWidget(value=unicode_type(o)) |
|
73 | return TextWidget(value=unicode_type(o)) | |
74 | elif isinstance(o, dict): |
|
74 | elif isinstance(o, dict): | |
75 | return DropdownWidget(values=o) |
|
75 | return DropdownWidget(values=o) | |
76 | elif isinstance(o, bool): |
|
76 | elif isinstance(o, bool): | |
77 | return CheckboxWidget(value=o) |
|
77 | return CheckboxWidget(value=o) | |
78 | elif isinstance(o, float): |
|
78 | elif isinstance(o, float): | |
79 | min, max, value = _get_min_max_value(None, None, o) |
|
79 | min, max, value = _get_min_max_value(None, None, o) | |
80 | return FloatSliderWidget(value=o, min=min, max=max) |
|
80 | return FloatSliderWidget(value=o, min=min, max=max) | |
81 | elif isinstance(o, int): |
|
81 | elif isinstance(o, int): | |
82 | min, max, value = _get_min_max_value(None, None, o) |
|
82 | min, max, value = _get_min_max_value(None, None, o) | |
83 | return IntSliderWidget(value=o, min=min, max=max) |
|
83 | return IntSliderWidget(value=o, min=min, max=max) | |
84 | else: |
|
84 | else: | |
85 | return None |
|
85 | return None | |
86 |
|
86 | |||
87 | def _widget_abbrev(o): |
|
87 | def _widget_abbrev(o): | |
88 | """Make widgets from abbreviations: single values, lists or tuples.""" |
|
88 | """Make widgets from abbreviations: single values, lists or tuples.""" | |
89 | float_or_int = (float, int) |
|
89 | float_or_int = (float, int) | |
90 | if isinstance(o, (list, tuple)): |
|
90 | if isinstance(o, (list, tuple)): | |
91 | if o and all(isinstance(x, string_types) for x in o): |
|
91 | if o and all(isinstance(x, string_types) for x in o): | |
92 | return DropdownWidget(values=[unicode_type(k) for k in o]) |
|
92 | return DropdownWidget(values=[unicode_type(k) for k in o]) | |
93 | elif _matches(o, (float_or_int, float_or_int)): |
|
93 | elif _matches(o, (float_or_int, float_or_int)): | |
94 | min, max, value = _get_min_max_value(o[0], o[1]) |
|
94 | min, max, value = _get_min_max_value(o[0], o[1]) | |
95 | if all(isinstance(_, int) for _ in o): |
|
95 | if all(isinstance(_, int) for _ in o): | |
96 | cls = IntSliderWidget |
|
96 | cls = IntSliderWidget | |
97 | else: |
|
97 | else: | |
98 | cls = FloatSliderWidget |
|
98 | cls = FloatSliderWidget | |
99 | return cls(value=value, min=min, max=max) |
|
99 | return cls(value=value, min=min, max=max) | |
100 | elif _matches(o, (float_or_int, float_or_int, float_or_int)): |
|
100 | elif _matches(o, (float_or_int, float_or_int, float_or_int)): | |
101 | step = o[2] |
|
101 | step = o[2] | |
102 | if step <= 0: |
|
102 | if step <= 0: | |
103 | raise ValueError("step must be >= 0, not %r" % step) |
|
103 | raise ValueError("step must be >= 0, not %r" % step) | |
104 | min, max, value = _get_min_max_value(o[0], o[1], step=step) |
|
104 | min, max, value = _get_min_max_value(o[0], o[1], step=step) | |
105 | if all(isinstance(_, int) for _ in o): |
|
105 | if all(isinstance(_, int) for _ in o): | |
106 | cls = IntSliderWidget |
|
106 | cls = IntSliderWidget | |
107 | else: |
|
107 | else: | |
108 | cls = FloatSliderWidget |
|
108 | cls = FloatSliderWidget | |
109 | return cls(value=value, min=min, max=max, step=step) |
|
109 | return cls(value=value, min=min, max=max, step=step) | |
110 | else: |
|
110 | else: | |
111 | return _widget_abbrev_single_value(o) |
|
111 | return _widget_abbrev_single_value(o) | |
112 |
|
112 | |||
113 | def _widget_from_abbrev(abbrev, default=empty): |
|
113 | def _widget_from_abbrev(abbrev, default=empty): | |
114 | """Build a Widget instance given an abbreviation or Widget.""" |
|
114 | """Build a Widget instance given an abbreviation or Widget.""" | |
115 | if isinstance(abbrev, Widget) or isinstance(abbrev, fixed): |
|
115 | if isinstance(abbrev, Widget) or isinstance(abbrev, fixed): | |
116 | return abbrev |
|
116 | return abbrev | |
117 |
|
117 | |||
118 | widget = _widget_abbrev(abbrev) |
|
118 | widget = _widget_abbrev(abbrev) | |
119 | if default is not empty and isinstance(abbrev, (list, tuple)): |
|
119 | if default is not empty and isinstance(abbrev, (list, tuple, dict)): | |
120 | # if it's not a single-value abbreviation, |
|
120 | # if it's not a single-value abbreviation, | |
121 | # set the initial value from the default |
|
121 | # set the initial value from the default | |
122 | try: |
|
122 | try: | |
123 | widget.value = default |
|
123 | widget.value = default | |
124 |
except |
|
124 | except Exception: | |
125 | # warn? |
|
125 | # ignore failure to set default | |
126 | pass |
|
126 | pass | |
127 | if widget is None: |
|
127 | if widget is None: | |
128 | raise ValueError("%r cannot be transformed to a Widget" % (abbrev,)) |
|
128 | raise ValueError("%r cannot be transformed to a Widget" % (abbrev,)) | |
129 | return widget |
|
129 | return widget | |
130 |
|
130 | |||
131 | def _yield_abbreviations_for_parameter(param, kwargs): |
|
131 | def _yield_abbreviations_for_parameter(param, kwargs): | |
132 | """Get an abbreviation for a function parameter.""" |
|
132 | """Get an abbreviation for a function parameter.""" | |
133 | name = param.name |
|
133 | name = param.name | |
134 | kind = param.kind |
|
134 | kind = param.kind | |
135 | ann = param.annotation |
|
135 | ann = param.annotation | |
136 | default = param.default |
|
136 | default = param.default | |
137 | not_found = (name, empty, empty) |
|
137 | not_found = (name, empty, empty) | |
138 | if kind in (Parameter.POSITIONAL_OR_KEYWORD, Parameter.KEYWORD_ONLY): |
|
138 | if kind in (Parameter.POSITIONAL_OR_KEYWORD, Parameter.KEYWORD_ONLY): | |
139 | if name in kwargs: |
|
139 | if name in kwargs: | |
140 | value = kwargs.pop(name) |
|
140 | value = kwargs.pop(name) | |
141 | elif ann is not empty: |
|
141 | elif ann is not empty: | |
142 | value = ann |
|
142 | value = ann | |
143 | elif default is not empty: |
|
143 | elif default is not empty: | |
144 | value = default |
|
144 | value = default | |
145 | else: |
|
145 | else: | |
146 | yield not_found |
|
146 | yield not_found | |
147 | yield (name, value, default) |
|
147 | yield (name, value, default) | |
148 | elif kind == Parameter.VAR_KEYWORD: |
|
148 | elif kind == Parameter.VAR_KEYWORD: | |
149 | # In this case name=kwargs and we yield the items in kwargs with their keys. |
|
149 | # In this case name=kwargs and we yield the items in kwargs with their keys. | |
150 | for k, v in kwargs.copy().items(): |
|
150 | for k, v in kwargs.copy().items(): | |
151 | kwargs.pop(k) |
|
151 | kwargs.pop(k) | |
152 | yield k, v, empty |
|
152 | yield k, v, empty | |
153 |
|
153 | |||
154 | def _find_abbreviations(f, kwargs): |
|
154 | def _find_abbreviations(f, kwargs): | |
155 | """Find the abbreviations for a function and kwargs passed to interact.""" |
|
155 | """Find the abbreviations for a function and kwargs passed to interact.""" | |
156 | new_kwargs = [] |
|
156 | new_kwargs = [] | |
157 | for param in signature(f).parameters.values(): |
|
157 | for param in signature(f).parameters.values(): | |
158 | for name, value, default in _yield_abbreviations_for_parameter(param, kwargs): |
|
158 | for name, value, default in _yield_abbreviations_for_parameter(param, kwargs): | |
159 | if value is empty: |
|
159 | if value is empty: | |
160 | raise ValueError('cannot find widget or abbreviation for argument: {!r}'.format(name)) |
|
160 | raise ValueError('cannot find widget or abbreviation for argument: {!r}'.format(name)) | |
161 | new_kwargs.append((name, value, default)) |
|
161 | new_kwargs.append((name, value, default)) | |
162 | return new_kwargs |
|
162 | return new_kwargs | |
163 |
|
163 | |||
164 | def _widgets_from_abbreviations(seq): |
|
164 | def _widgets_from_abbreviations(seq): | |
165 | """Given a sequence of (name, abbrev) tuples, return a sequence of Widgets.""" |
|
165 | """Given a sequence of (name, abbrev) tuples, return a sequence of Widgets.""" | |
166 | result = [] |
|
166 | result = [] | |
167 | for name, abbrev, default in seq: |
|
167 | for name, abbrev, default in seq: | |
168 | widget = _widget_from_abbrev(abbrev, default) |
|
168 | widget = _widget_from_abbrev(abbrev, default) | |
169 | widget.description = name |
|
169 | widget.description = name | |
170 | result.append(widget) |
|
170 | result.append(widget) | |
171 | return result |
|
171 | return result | |
172 |
|
172 | |||
173 | def interactive(__interact_f, **kwargs): |
|
173 | def interactive(__interact_f, **kwargs): | |
174 | """Build a group of widgets to interact with a function.""" |
|
174 | """Build a group of widgets to interact with a function.""" | |
175 | f = __interact_f |
|
175 | f = __interact_f | |
176 | co = kwargs.pop('clear_output', True) |
|
176 | co = kwargs.pop('clear_output', True) | |
177 | kwargs_widgets = [] |
|
177 | kwargs_widgets = [] | |
178 | container = ContainerWidget() |
|
178 | container = ContainerWidget() | |
179 | container.result = None |
|
179 | container.result = None | |
180 | container.args = [] |
|
180 | container.args = [] | |
181 | container.kwargs = dict() |
|
181 | container.kwargs = dict() | |
182 | kwargs = kwargs.copy() |
|
182 | kwargs = kwargs.copy() | |
183 |
|
183 | |||
184 | new_kwargs = _find_abbreviations(f, kwargs) |
|
184 | new_kwargs = _find_abbreviations(f, kwargs) | |
185 | # Before we proceed, let's make sure that the user has passed a set of args+kwargs |
|
185 | # Before we proceed, let's make sure that the user has passed a set of args+kwargs | |
186 | # that will lead to a valid call of the function. This protects against unspecified |
|
186 | # that will lead to a valid call of the function. This protects against unspecified | |
187 | # and doubly-specified arguments. |
|
187 | # and doubly-specified arguments. | |
188 | getcallargs(f, **{n:v for n,v,_ in new_kwargs}) |
|
188 | getcallargs(f, **{n:v for n,v,_ in new_kwargs}) | |
189 | # Now build the widgets from the abbreviations. |
|
189 | # Now build the widgets from the abbreviations. | |
190 | kwargs_widgets.extend(_widgets_from_abbreviations(new_kwargs)) |
|
190 | kwargs_widgets.extend(_widgets_from_abbreviations(new_kwargs)) | |
191 |
|
191 | |||
192 | # This has to be done as an assignment, not using container.children.append, |
|
192 | # This has to be done as an assignment, not using container.children.append, | |
193 | # so that traitlets notices the update. We skip any objects (such as fixed) that |
|
193 | # so that traitlets notices the update. We skip any objects (such as fixed) that | |
194 | # are not DOMWidgets. |
|
194 | # are not DOMWidgets. | |
195 | c = [w for w in kwargs_widgets if isinstance(w, DOMWidget)] |
|
195 | c = [w for w in kwargs_widgets if isinstance(w, DOMWidget)] | |
196 | container.children = c |
|
196 | container.children = c | |
197 |
|
197 | |||
198 | # Build the callback |
|
198 | # Build the callback | |
199 | def call_f(name, old, new): |
|
199 | def call_f(name, old, new): | |
200 | container.kwargs = {} |
|
200 | container.kwargs = {} | |
201 | for widget in kwargs_widgets: |
|
201 | for widget in kwargs_widgets: | |
202 | value = widget.value |
|
202 | value = widget.value | |
203 | container.kwargs[widget.description] = value |
|
203 | container.kwargs[widget.description] = value | |
204 | if co: |
|
204 | if co: | |
205 | clear_output(wait=True) |
|
205 | clear_output(wait=True) | |
206 | try: |
|
206 | try: | |
207 | container.result = f(**container.kwargs) |
|
207 | container.result = f(**container.kwargs) | |
208 | except Exception as e: |
|
208 | except Exception as e: | |
209 | ip = get_ipython() |
|
209 | ip = get_ipython() | |
210 | if ip is None: |
|
210 | if ip is None: | |
211 | container.log.warn("Exception in interact callback: %s", e, exc_info=True) |
|
211 | container.log.warn("Exception in interact callback: %s", e, exc_info=True) | |
212 | else: |
|
212 | else: | |
213 | ip.showtraceback() |
|
213 | ip.showtraceback() | |
214 |
|
214 | |||
215 | # Wire up the widgets |
|
215 | # Wire up the widgets | |
216 | for widget in kwargs_widgets: |
|
216 | for widget in kwargs_widgets: | |
217 | widget.on_trait_change(call_f, 'value') |
|
217 | widget.on_trait_change(call_f, 'value') | |
218 |
|
218 | |||
219 | container.on_displayed(lambda _: call_f(None, None, None)) |
|
219 | container.on_displayed(lambda _: call_f(None, None, None)) | |
220 |
|
220 | |||
221 | return container |
|
221 | return container | |
222 |
|
222 | |||
223 | def interact(__interact_f=None, **kwargs): |
|
223 | def interact(__interact_f=None, **kwargs): | |
224 | """interact(f, **kwargs) |
|
224 | """interact(f, **kwargs) | |
225 |
|
225 | |||
226 | Interact with a function using widgets.""" |
|
226 | Interact with a function using widgets.""" | |
227 | # positional arg support in: https://gist.github.com/8851331 |
|
227 | # positional arg support in: https://gist.github.com/8851331 | |
228 | if __interact_f is not None: |
|
228 | if __interact_f is not None: | |
229 | # This branch handles the cases: |
|
229 | # This branch handles the cases: | |
230 | # 1. interact(f, **kwargs) |
|
230 | # 1. interact(f, **kwargs) | |
231 | # 2. @interact |
|
231 | # 2. @interact | |
232 | # def f(*args, **kwargs): |
|
232 | # def f(*args, **kwargs): | |
233 | # ... |
|
233 | # ... | |
234 | f = __interact_f |
|
234 | f = __interact_f | |
235 | w = interactive(f, **kwargs) |
|
235 | w = interactive(f, **kwargs) | |
236 | f.widget = w |
|
236 | f.widget = w | |
237 | display(w) |
|
237 | display(w) | |
238 | return f |
|
238 | return f | |
239 | else: |
|
239 | else: | |
240 | # This branch handles the case: |
|
240 | # This branch handles the case: | |
241 | # @interact(a=30, b=40) |
|
241 | # @interact(a=30, b=40) | |
242 | # def f(*args, **kwargs): |
|
242 | # def f(*args, **kwargs): | |
243 | # ... |
|
243 | # ... | |
244 | def dec(f): |
|
244 | def dec(f): | |
245 | w = interactive(f, **kwargs) |
|
245 | w = interactive(f, **kwargs) | |
246 | f.widget = w |
|
246 | f.widget = w | |
247 | display(w) |
|
247 | display(w) | |
248 | return f |
|
248 | return f | |
249 | return dec |
|
249 | return dec | |
250 |
|
250 | |||
251 | class fixed(HasTraits): |
|
251 | class fixed(HasTraits): | |
252 | """A pseudo-widget whose value is fixed and never synced to the client.""" |
|
252 | """A pseudo-widget whose value is fixed and never synced to the client.""" | |
253 | value = Any(help="Any Python object") |
|
253 | value = Any(help="Any Python object") | |
254 | description = Unicode('', help="Any Python object") |
|
254 | description = Unicode('', help="Any Python object") | |
255 | def __init__(self, value, **kwargs): |
|
255 | def __init__(self, value, **kwargs): | |
256 | super(fixed, self).__init__(value=value, **kwargs) |
|
256 | super(fixed, self).__init__(value=value, **kwargs) |
General Comments 0
You need to be logged in to leave comments.
Login now