add more detail to dict section

Author: rmorshea

docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_remove.py

@@ -0,0 +1,58 @@
+from idom import component, html, run, use_state
+
+
+@component
+def Definitions():
+    term_to_add, set_term_to_add = use_state(None)
+    definition_to_add, set_definition_to_add = use_state(None)
+    all_terms, set_all_terms = use_state({})
+
+    def handle_term_to_add_change(event):
+        set_term_to_add(event["target"]["value"])
+
+    def handle_definition_to_add_change(event):
+        set_definition_to_add(event["target"]["value"])
+
+    def handle_add_click(event):
+        if term_to_add and definition_to_add:
+            set_all_terms({**all_terms, term_to_add: definition_to_add})
+            set_term_to_add(None)
+            set_definition_to_add(None)
+
+    def make_delete_click_handler(term_to_delete):
+        def handle_click(event):
+            set_all_terms({t: d for t, d in all_terms.items() if t != term_to_delete})
+
+        return handle_click
+
+    return html.div(
+        html.button({"onClick": handle_add_click}, "add term"),
+        html.label(
+            "Term: ",
+            html.input({"value": term_to_add, "onChange": handle_term_to_add_change}),
+        ),
+        html.label(
+            "Definition: ",
+            html.input(
+                {
+                    "value": definition_to_add,
+                    "onChange": handle_definition_to_add_change,
+                }
+            ),
+        ),
+        html.hr(),
+        [
+            html.div(
+                html.button(
+                    {"onClick": make_delete_click_handler(term)}, "delete term"
+                ),
+                html.dt(term),
+                html.dd(definition),
+                key=term,
+            )
+            for term, definition in all_terms.items()
+        ],
+    )
+
+
+run(Definitions)

docs/source/adding-interactivity/dangers-of-mutability/index.rst

@@ -46,6 +46,8 @@ Thus far, all the values we've been working with have been immutable. These incl
 have not had to consider the consiquences of mutations.
 
 
+.. _Why Avoid Mutation:
+
 Why Avoid Mutation?
 -------------------
 
@@ -123,54 +125,104 @@ you touch or hover over the preview:
 Working with Dictionaries
 -------------------------
 
-Below are some operations to :bdg-danger:`avoid` and stragies to :bdg-info:`prefer` when
-working with dictionaries...
+Below are some ways to update dictionaries without mutating them:
+
+.. card:: Updating Items
+    :link: updating-dictionary-items
+    :link-type: ref
+
+    Avoid using item assignment, ``dict.update``, or ``dict.setdefault``. Instead try
+    the strategies below:
+
+    .. code-block::
+
+        {**d, "key": value}
+
+        # Python >= 3.9
+        d | {"key": value}
+
+        # Equivalent to setdefault()
+        {"key": value, **d}
+
+.. card:: Removing Items
+    :link: removing-dictionary-items
+    :link-type: ref
+
+    Avoid using item deletion or ``dict.pop`` instead try the strategies below:
+
+    .. code-block::
+
+        {
+            k: v
+            for k, v in d.items()
+            if k != key
+        }
+
+        # Better for removing multiple items
+        {
+            k: d[k]
+            for k in set(d).difference([key])
+        }
 
 
+.. _updating-dictionary-items:
+
 Updating Dictionary Items
 .........................
 
-.. grid:: 1 1 2 2
+.. grid:: 1 1 1 2
     :gutter: 1
 
     .. grid-item-card:: :bdg-danger:`Avoid`
 
         .. code-block::
 
-            d["key"] = value
+            d[key] = value
 
-            d.update(key=value)
+            d.update({key: value})
 
-            d.setdefault("key", value)
+            d.setdefault(key, value)
 
     .. grid-item-card:: :bdg-info:`Prefer`
 
         .. code-block::
 
-            {**d, "key": value}
+            {**d, key: value}
 
             # Python >= 3.9
-            d | {"key": value}
+            d | {key: value}
 
             # Equivalent to setdefault()
-            {"key": value, **d}
+            {key: value, **d}
+
+As we saw in an :ref:`earlier example <why avoid mutation>`, instead of mutating
+dictionaries to update their items you should instead create a copy that contains the
+desired changes.
+
+However, sometimes you may only want to update some of the information in a dictionary
+which is held by a state variable. Consider the case below where we have a form for
+updating user information with a preview of the currently entered data. We can
+accomplish this using `"unpacking" <https://www.python.org/dev/peps/pep-0448/>`__ with
+the ``**`` syntax:
 
+.. idom:: _examples/dict_update
+
+
+.. _removing-dictionary-items:
 
 Removing Dictionary Items
 .........................
 
-.. grid:: 1 1 2 2
+.. grid:: 1 1 1 2
     :gutter: 1
 
     .. grid-item-card:: :bdg-danger:`Avoid`
 
         .. code-block::
 
-            d["key"] = value
-
-            d.update(key=value)
+            del d[key]
 
-            d.setdefault("key", value)
+            d.pop(key)
 
     .. grid-item-card:: :bdg-info:`Prefer`
 
@@ -179,9 +231,23 @@ Removing Dictionary Items
             {
                 k: v
                 for k, v in d.items()
-                if k != "key"
+                if k != key
+            }
+
+            # Better for removing multiple items
+            {
+                k: d[k]
+                for k in set(d).difference([key])
             }
 
+This scenario doesn't come up very frequently. When it does though, the best way to
+remove items from dictionaries is to create a copy of the original, but with a filtered
+set of keys. One way to do this is with a dictionary comprehension. The example below
+shows an interface where you're able to enter a new term and definition. Once added,
+you can click a delete button to remove the term and definition:
+
+.. idom:: _examples/dict_remove
+
 
 Working with Lists
 ------------------
@@ -193,7 +259,7 @@ working with lists...
 Replacing List Items
 ....................
 
-.. grid:: 1 1 2 2
+.. grid:: 1 1 1 2
 
     .. grid-item-card:: :bdg-danger:`Avoid`
 
@@ -215,7 +281,7 @@ Replacing List Items
 Inserting List Items
 ....................
 
-.. grid:: 1 1 2 2
+.. grid:: 1 1 1 2
 
     .. grid-item-card:: :bdg-danger:`Avoid`
 
@@ -231,6 +297,8 @@ Inserting List Items
 
         .. code-block::
 
+            [*l, value]
+
             l + [value]
 
             l + values
@@ -241,7 +309,7 @@ Inserting List Items
 Removing List Items
 ...................
 
-.. grid:: 1 1 2 2
+.. grid:: 1 1 1 2
 
     .. grid-item-card:: :bdg-danger:`Avoid`
 
@@ -251,21 +319,17 @@ Removing List Items
 
             l.pop(index)
 
-            l.clear()
-
     .. grid-item-card:: :bdg-info:`Prefer`
 
         .. code-block::
 
             l[:index - 1] + l[index:]
 
-            []
-
 
 Re-ordering List Items
 ......................
 
-.. grid:: 1 1 2 2
+.. grid:: 1 1 1 2
 
     .. grid-item-card:: :bdg-danger:`Avoid`
 
@@ -290,10 +354,32 @@ Working with Sets
 Below are some operations to :bdg-danger:`avoid` and stragies to :bdg-info:`prefer` when
 working with sets...
 
-Ading Set Items
-...............
+Adding Set Items
+................
+
+.. grid:: 1 1 1 2
+
+    .. grid-item-card:: :bdg-danger:`Avoid`
+
+        .. code-block::
+
+            l[index] = value
+
+            l[start:end] = values
+
+    .. grid-item-card:: :bdg-info:`Prefer`
+
+        .. code-block::
+
+            l[:index] + [value] + l[index + 1:]
+
+            l[:start] + values + l[end + 1:]
+
+
+Removing Set Items
+..................
 
-.. grid:: 1 1 2 2
+.. grid:: 1 1 1 2
 
     .. grid-item-card:: :bdg-danger:`Avoid`
 

docs/source/adding-interactivity/index.rst

@@ -16,7 +16,7 @@ Adding Interactivity
     :animate: fade-in
     :open:
 
-    .. grid:: 1 1 2 2
+    .. grid:: 1 2 2 2
 
         .. grid-item-card:: :octicon:`bell` Responding to Events
             :link: responding-to-events/index

docs/source/creating-interfaces/index.rst

@@ -13,7 +13,7 @@ Creating Interfaces
     :animate: fade-in
     :open:
 
-    .. grid:: 1 1 2 2
+    .. grid:: 1 2 2 2
 
         .. grid-item-card:: :octicon:`code-square` HTML with IDOM
             :link: html-with-idom

docs/source/developing-idom/index.rst

@@ -21,7 +21,7 @@ or simply sharing your work with your colleagues and friends. We're excited to s
 you can help move this project and community forward!
 
 
-.. grid:: 1 1 2 2
+.. grid:: 1 2 2 2
     :gutter: 1
 
     .. grid-item-card:: :octicon:`people` Discussion Forum

docs/source/getting-started/index.rst

@@ -12,7 +12,7 @@ Getting Started
     :animate: fade-in
     :open:
 
-    .. grid:: 1 1 2 2
+    .. grid:: 1 2 2 2
 
         .. grid-item-card:: :octicon:`tools` Installing IDOM
             :link: installing-idom

docs/source/index.rst

@@ -93,7 +93,7 @@ more detailed information about how to :ref:`run IDOM <Running IDOM>` in differe
 contexts. For example, if you want to embed IDOM into an existing application, or run
 IDOM within a Jupyter Notebook, this is where you can learn how to do those things.
 
-.. grid:: 1 1 2 2
+.. grid:: 1 2 2 2
 
     .. grid-item::