Merge pull request #2130 from jtpio/mapping-deprecation-warning

Add DeprecationWarning when using Mapping for options

Author: SylvainCorlay

docs/source/examples/Using Interact.ipynb

@@ -499,7 +499,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "If you want a dropdown menu that passes non-string values to the Python function, you can pass a dictionary. The keys in the dictionary are used for the names in the dropdown menu UI and the values are the arguments that are passed to the underlying Python function."
+    "If you want a dropdown menu that passes non-string values to the Python function, you can pass a list of (label, value) pairs."
    ]
   },
   {
@@ -515,15 +515,15 @@
        "version_minor": 0
       },
       "text/plain": [
-       "interactive(children=(Dropdown(description='x', options={'one': 10, 'two': 20}, value=10), Output()), _dom_cla…"
+       "interactive(children=(Dropdown(description='x', options=(('one', 10), ('two', 20)), value=10), Output()), _dom…"
       ]
      },
      "metadata": {},
      "output_type": "display_data"
     }
    ],
    "source": [
-    "interact(f, x={'one': 10, 'two': 20});"
+    "interact(f, x=[('one', 10), ('two', 20)]);"
    ]
   },
   {

docs/source/examples/Widget List.ipynb

@@ -686,7 +686,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "There are several widgets that can be used to display single selection lists, and two that can be used to select multiple values.  All inherit from the same base class.  You can specify the **enumeration of selectable options by passing a list** (options are either (label, value) pairs, or simply values for which the labels are derived by calling `str`).  You can **also specify the enumeration as a dictionary**, in which case the **keys will be used as the item displayed** in the list and the corresponding **value will be used** when an item is selected (in this case, since dictionaries are unordered, the displayed order of items in the widget is unspecified)."
+    "There are several widgets that can be used to display single selection lists, and two that can be used to select multiple values.  All inherit from the same base class.  You can specify the **enumeration of selectable options by passing a list** (options are either (label, value) pairs, or simply values for which the labels are derived by calling `str`)."
    ]
   },
   {
@@ -729,41 +729,6 @@
     ")"
    ]
   },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "The following is also valid:"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 18,
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "application/vnd.jupyter.widget-view+json": {
-       "model_id": "91ed9917c1f84bd890c071bf40ffbbf8",
-       "version_major": 2,
-       "version_minor": 0
-      },
-      "text/plain": [
-       "Dropdown(description='Number:', index=1, options={'One': 1, 'Two': 2, 'Three': 3}, value=2)"
-      ]
-     },
-     "metadata": {},
-     "output_type": "display_data"
-    }
-   ],
-   "source": [
-    "widgets.Dropdown(\n",
-    "    options={'One': 1, 'Two': 2, 'Three': 3},\n",
-    "    value=2,\n",
-    "    description='Number:',\n",
-    ")"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {
@@ -3411,5 +3376,5 @@
   }
  },
  "nbformat": 4,
- "nbformat_minor": 1
+ "nbformat_minor": 2
 }

ipywidgets/widgets/tests/test_widget_selection.py

@@ -1,11 +1,34 @@
 # Copyright (c) Jupyter Development Team.
 # Distributed under the terms of the Modified BSD License.
 
+import inspect
+import warnings
 from unittest import TestCase
 
 from traitlets import TraitError
 
-from ipywidgets import SelectionSlider, Select
+from ipywidgets import Dropdown, SelectionSlider, Select
+
+
+class TestDropdown(TestCase):
+
+    def test_construction(self):
+        Dropdown()
+
+    def test_deprecation_warning_mapping_options(self):
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+
+            # Clearing the internal __warningregistry__ seems to be required for
+            # Python 2 (but not for Python 3)
+            module = inspect.getmodule(Dropdown)
+            getattr(module, '__warningregistry__', {}).clear()
+
+            Dropdown(options={'One': 1, 'Two': 2, 'Three': 3})
+            assert len(w) > 0
+            assert issubclass(w[-1].category, DeprecationWarning)
+            assert "Support for mapping types has been deprecated" in str(w[-1].message)
+
 
 class TestSelectionSlider(TestCase):
 

ipywidgets/widgets/widget_selection.py

@@ -26,16 +26,11 @@
 
 _doc_snippets = {}
 _doc_snippets['selection_params'] = """
-    options: list or dict
+    options: list
         The options for the dropdown. This can either be a list of values, e.g.
-        ``['Galileo', 'Brahe', 'Hubble']`` or ``[0, 1, 2]``, a list of
+        ``['Galileo', 'Brahe', 'Hubble']`` or ``[0, 1, 2]``, or a list of
         (label, value) pairs, e.g.
-        ``[('Galileo', 0), ('Brahe', 1), ('Hubble', 2)]``,
-        or a dictionary mapping the labels to the values, e.g. ``{'Galileo': 0,
-        'Brahe': 1, 'Hubble': 2}``. The labels are the strings that will be
-        displayed in the UI, representing the actual Python choices, and should
-        be unique. If this is a dictionary, the order in which they are
-        displayed is not guaranteed.
+        ``[('Galileo', 0), ('Brahe', 1), ('Hubble', 2)]``.
 
     index: int
         The index of the current selection.
@@ -113,12 +108,13 @@ def _make_options(x):
     The returned tuple should be in the format (('label', value), ('label', value), ...).
 
     The input can be
-    * a Mapping of labels to values
     * an iterable of (label, value) pairs
     * an iterable of values, and labels will be generated
     """
     # Check if x is a mapping of labels to values
     if isinstance(x, Mapping):
+        import warnings
+        warnings.warn("Support for mapping types has been deprecated and will be dropped in a future release.", DeprecationWarning)
         return tuple((unicode_type(k), v) for k, v in x.items())
 
     # only iterate once through the options.