Merge pull request #3556 from jasongrout/optionwarning

Make the selection widgets mapping options error more helpful.

docs/source/user_migration_guides.md

@@ -48,8 +48,7 @@ For these, it is no longer possible to use `dict`s or other mapping types as val
 `options` trait. Using mapping types in this way has been deprecated since version 7.4, and
 will now raise a `TypeError`.
 
-Suggested migration: Clean up the `options` use. The following snippet can be used to convert
-a `dict` to the new format: `w.options = tuple((str(k), v) for k, v in your_dict.items())`.
+Suggested migration: Instead of using a dict `my_dict` as options, use `my_dict.items()`, which returns the items in `my_dict` as key-value pairs. For example, `Select(options=my_dict.items())`.
 
 #### Description Sanitization
 

python/ipywidgets/ipywidgets/widgets/widget_selection.py

@@ -112,7 +112,7 @@ def _make_options(x):
     * an iterable of values, and labels will be generated
     """
     if isinstance(x, Mapping):
-        raise TypeError("options must be a list of values or a list of (label, value) tuples")
+        raise TypeError("options must be a iterable of values or of (label, value) pairs. If x is your Mapping, use x.items() for the options.")
 
     # only iterate once through the options.
     xlist = tuple(x)