add last instruction for lists and sets

Author: rmorshea

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

@@ -10,7 +10,7 @@ def handle_change(event):
         set_artist_to_add(event["target"]["value"])
 
     def handle_click(event):
-        if artist_to_add not in artists:
+        if artist_to_add and artist_to_add not in artists:
             set_artists([*artists, artist_to_add])
             set_artist_to_add("")
 

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

@@ -0,0 +1,41 @@
+from idom import component, html, run, use_state
+
+
+@component
+def Grid():
+    line_size = 5
+    selected_indices, set_selected_indices = use_state({1, 2, 4})
+
+    def make_handle_click(index):
+        def handle_click(event):
+            if index in selected_indices:
+                set_selected_indices(selected_indices - {index})
+            else:
+                set_selected_indices(selected_indices | {index})
+
+        return handle_click
+
+    return html.div(
+        {"style": {"display": "flex", "flex-direction": "row"}},
+        [
+            html.div(
+                {
+                    "onClick": make_handle_click(index),
+                    "style": {
+                        "height": "30px",
+                        "width": "30px",
+                        "backgroundColor": (
+                            "black" if index in selected_indices else "white"
+                        ),
+                        "outline": "1px solid grey",
+                        "cursor": "pointer",
+                    },
+                },
+                key=index,
+            )
+            for index in range(line_size)
+        ],
+    )
+
+
+run(Grid)

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

@@ -0,0 +1,38 @@
+from idom import component, html, run, use_state
+
+
+@component
+def Grid():
+    line_size = 5
+    selected_indices, set_selected_indices = use_state(set())
+
+    def make_handle_click(index):
+        def handle_click(event):
+            set_selected_indices(selected_indices | {index})
+
+        return handle_click
+
+    return html.div(
+        {"style": {"display": "flex", "flex-direction": "row"}},
+        [
+            html.div(
+                {
+                    "onClick": make_handle_click(index),
+                    "style": {
+                        "height": "30px",
+                        "width": "30px",
+                        "backgroundColor": (
+                            "black" if index in selected_indices else "white"
+                        ),
+                        "outline": "1px solid grey",
+                        "cursor": "pointer",
+                    },
+                },
+                key=index,
+            )
+            for index in range(line_size)
+        ],
+    )
+
+
+run(Grid)

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

@@ -141,7 +141,7 @@ Below are some ways to update dictionaries without mutating them:
         # Python >= 3.9
         d | {"key": value}
 
-        # Equivalent to setdefault()
+        # Equivalent to dict.setdefault()
         {"key": value, **d}
 
 .. card:: Removing Items
@@ -165,6 +165,9 @@ Below are some ways to update dictionaries without mutating them:
         }
 
 
+----
+
+
 .. _updating-dictionary-items:
 
 Updating Dictionary Items
@@ -293,11 +296,10 @@ Below are some ways to update lists without mutating them:
 
         l[:start] + values + l[end + 1:]
 
-..card:: Re-ordering Items
+.. card:: Re-ordering Items
     :link: re-ordering-list-items
     :link-type: ref
 
-
     Avoid using ``list.sort`` or ``list.reverse``. Instead try the strategies below:
 
     .. code-block::
@@ -307,6 +309,9 @@ Below are some ways to update lists without mutating them:
         list(reversed(l))
 
 
+----
+
+
 .. _inserting-list-items:
 
 Inserting List Items
@@ -324,6 +329,9 @@ Inserting List Items
 
             l.insert(index, value)
 
+            # Adding a list "in-place" mutates!
+            l += [value]
+
     .. grid-item-card:: :bdg-info:`Prefer`
 
         .. code-block::
@@ -336,6 +344,11 @@ Inserting List Items
 
             l[:index] + [value] + l[index:]
 
+Instead of mutating a list to add items to it, we need to create a new list which has
+the items we want to append instead. There are several ways to do this for one or more
+values however it's often simplest to use `"unpacking"
+<https://www.python.org/dev/peps/pep-0448/>`__ with the ``*`` syntax.
+
 .. idom:: _examples/list_insert
 
 
@@ -358,7 +371,12 @@ Removing List Items
 
         .. code-block::
 
-            l[:index - 1] + l[index:]
+            l[:index] + l[index + 1:]
+
+Unfortunately, the syntax for creating a copy of a list with one of its items removed is
+not quite as clean. You must select the portion the list prior to the item which should
+be removed (``l[:index]``) and the portion after the item (``l[index + 1:]``) and add
+them together:
 
 .. idom:: _examples/list_remove
 
@@ -386,6 +404,11 @@ Replacing List Items
 
             l[:start] + values + l[end + 1:]
 
+In a similar manner to :ref:`removing list items`, to replace an item in a list, you
+must select the portion before and after the item in question. But this time, instead
+of adding those two selections together, you must insert that values you want to replace
+between them:
+
 .. idom:: _examples/list_replace
 
 
@@ -412,6 +435,12 @@ Re-ordering List Items
 
             list(reversed(l))
 
+There are many different ways that list items could be re-ordered, but two of the most
+common are reversing or sorting items. Instead of calling the associated methods on a
+list object, you should use the builtin functions :func:`sorted` and :func:`reversed`
+and pass the resulting iterator into the :class:`list` constructor to create a sorted
+or reversed copy of the given list:
+
 .. idom:: _examples/list_re_order
 
 
@@ -448,6 +477,9 @@ Below are ways to update sets without mutating them:
         s.intersection(values)
 
 
+----
+
+
 .. _adding-set-items:
 
 Adding Set Items
@@ -460,16 +492,27 @@ Adding Set Items
         .. code-block::
 
             s.add(value)
+            s |= {value}  # "in-place" operators mutate!
 
             s.update(values)
+            s |= values  # "in-place" operators mutate!
 
     .. grid-item-card:: :bdg-info:`Prefer`
 
         .. code-block::
 
             s.union({value})
+            s | {value}
 
             s.union(values)
+            s | values
+
+Sets have some nice ways for evolving them without requiring mutation. The binary
+or operator ``|`` serves as a succinct way to compute the union of two sets. However,
+you should be careful to not use an in-place assignment with this operator as that will
+(counterintuitively) mutate the original set rather than creating a new one.
+
+.. idom:: _examples/set_update
 
 
 .. _removing-set-items:
@@ -486,8 +529,14 @@ Removing Set Items
             s.remove(value)
 
             s.difference_update(values)
+            s -= values  # "in-place" operators mutate!
+
+            s.symetric_difference_update(values)
+            s ^= values  # "in-place" operators mutate!
 
             s.intersection_update(values)
+            s &= values  # "in-place" operators mutate!
+
 
     .. grid-item-card:: :bdg-info:`Prefer`
 
@@ -496,10 +545,25 @@ Removing Set Items
             s.difference({value})
 
             s.difference(values)
+            s - values
+
+            s.symetric_difference(values)
+            s ^ values
 
             s.intersection(values)
+            s & values
+
+To remove items from sets you can use the various binary operators or their associated
+methods to return new sets without mutating them. As before when :ref:`adding items to
+sets` you need to avoid using the inline assignment operators since that will
+(counterintuitively) mutate the original set rather than given you a new one:
+
+.. idom:: _examples/set_remove
 
 
 Useful Packages
 ---------------
 
+Under construction 🚧
+
+https://pypi.org/project/pyrsistent/