add sections for working with dicts and lists

still need more content there
reactive-python · Jan 5, 2022 · 956152c · 956152c
1 parent ad88514
commit 956152c
Show file tree

Hide file tree

Showing 10 changed files with 241 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 # IDOM &middot; [![Tests](https://github.com/idom-team/idom/workflows/Test/badge.svg?event=push)](https://github.com/idom-team/idom/actions?query=workflow%3ATest) [![PyPI Version](https://img.shields.io/pypi/v/idom.svg)](https://pypi.python.org/pypi/idom) [![License](https://img.shields.io/badge/License-MIT-purple.svg)](https://github.com/idom-team/idom/blob/main/LICENSE)
 
-IDOM is a Python package for making user interfaces. These interfaces are built from
-small elements of functionality like buttons text and images. IDOM allows you to combine
-these elements into reusable "components" that can be composed together to create
-complex views.
+IDOM is a Python web framework for building **interactive websites without needing a
+single line of Javascript**. These sites are built from small elements of functionality
+like buttons text and images. IDOM allows you to combine these elements into reusable
+"components" that can be composed together to create complex views.
 
 Ecosystem independence is also a core feature of IDOM. It can be added to existing
 applications built on a variety of sync and async web servers, as well as integrated

diff --git a/docs/source/_static/css/sphinx-design-overrides.css b/docs/source/_static/css/sphinx-design-overrides.css
@@ -17,3 +17,7 @@ body {
   max-height: 700px;
   overflow: auto;
 }
+
+.sd-card-title .sd-badge {
+  font-size: 1em;
+}
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_update.py b/docs/source/adding-interactivity/dangers-of-mutability/_examples/dict_update.py
@@ -0,0 +1,46 @@
+from idom import component, html, run, use_state
+
+
+@component
+def Form():
+    person, set_person = use_state(
+        {
+            "first_name": "Barbara",
+            "last_name": "Hepworth",
+            "email": "[email protected]",
+        }
+    )
+
+    def handle_first_name_change(event):
+        set_person({**person, "first_name": event["target"]["value"]})
+
+    def handle_last_name_change(event):
+        set_person({**person, "last_name": event["target"]["value"]})
+
+    def handle_email_change(event):
+        set_person({**person, "email": event["target"]["value"]})
+
+    return html.div(
+        html.label(
+            "First name: ",
+            html.input(
+                {"value": person["first_name"], "onChange": handle_first_name_change},
+            ),
+        ),
+        html.label(
+            "First name: ",
+            html.input(
+                {"value": person["last_name"], "onChange": handle_last_name_change},
+            ),
+        ),
+        html.label(
+            "First name: ",
+            html.input(
+                {"value": person["email"], "onChange": handle_email_change},
+            ),
+        ),
+        html.p(f"{person['first_name']} {person['last_name']} {person['email']}"),
+    )
+
+
+run(Form)
diff --git a/docs/source/adding-interactivity/dangers-of-mutability/index.rst b/docs/source/adding-interactivity/dangers-of-mutability/index.rst
@@ -119,28 +119,199 @@ you touch or hover over the preview:
     depends on it. This is called a “local mutation.” You can even do local mutation
     while rendering. Very convenient and completely okay!
 
-Python provides a number of mutable built in data types:
 
-- :ref:`Dictionaries <working with dictionaries>`
-- :ref:`Lists <working with lists>`
-- :ref:`Sets <working with sets>`
+Working with Dictionaries
+-------------------------
 
-Below we suggest a number of strategies for safely working with these types...
+Below are some operations to :bdg-danger:`avoid` and stragies to :bdg-info:`prefer` when
+working with dictionaries...
 
 
-Working with Dictionaries
--------------------------
+Updating Dictionary Items
+.........................
+
+.. grid:: 1 1 2 2
+    :gutter: 1
+
+    .. grid-item-card:: :bdg-danger:`Avoid`
+
+        .. code-block::
+
+            d["key"] = value
+
+            d.update(key=value)
+
+            d.setdefault("key", value)
+
+    .. grid-item-card:: :bdg-info:`Prefer`
+
+        .. code-block::
+
+            {**d, "key": value}
+
+            # Python >= 3.9
+            d | {"key": value}
+
+            # Equivalent to setdefault()
+            {"key": value, **d}
+
+
+Removing Dictionary Items
+.........................
+
+.. grid:: 1 1 2 2
+    :gutter: 1
+
+    .. grid-item-card:: :bdg-danger:`Avoid`
+
+        .. code-block::
+
+            d["key"] = value
+
+            d.update(key=value)
 
-There are a number of different ways to idiomatically construct dictionaries
+            d.setdefault("key", value)
+
+    .. grid-item-card:: :bdg-info:`Prefer`
+
+        .. code-block::
+
+            {
+                k: v
+                for k, v in d.items()
+                if k != "key"
+            }
 
 
 Working with Lists
 ------------------
 
+Below are some operations to :bdg-danger:`avoid` and stragies to :bdg-info:`prefer` when
+working with lists...
+
+
+Replacing List Items
+....................
+
+.. grid:: 1 1 2 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:]
+
+
+Inserting List Items
+....................
+
+.. grid:: 1 1 2 2
+
+    .. grid-item-card:: :bdg-danger:`Avoid`
+
+        .. code-block::
+
+            l.append(value)
+
+            l.extend(values)
+
+            l.insert(index, value)
+
+    .. grid-item-card:: :bdg-info:`Prefer`
+
+        .. code-block::
+
+            l + [value]
+
+            l + values
+
+            l[:index] + [value] + l[index:]
+
+
+Removing List Items
+...................
+
+.. grid:: 1 1 2 2
+
+    .. grid-item-card:: :bdg-danger:`Avoid`
+
+        .. code-block::
+
+            del l[index]
+
+            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-item-card:: :bdg-danger:`Avoid`
+
+        .. code-block::
+
+            l.sort()
+
+            l.reverse()
+
+    .. grid-item-card:: :bdg-info:`Prefer`
+
+        .. code-block::
+
+            list(sorted(l))
+
+            list(reversed(l))
+
 
 Working with Sets
 -----------------
 
+Below are some operations to :bdg-danger:`avoid` and stragies to :bdg-info:`prefer` when
+working with sets...
+
+Ading Set Items
+...............
+
+.. grid:: 1 1 2 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:]
+
+
+Useful Packages
+---------------
 
-Working with Nested Data
-------------------------
diff --git a/docs/source/adding-interactivity/index.rst b/docs/source/adding-interactivity/index.rst
@@ -16,7 +16,7 @@ Adding Interactivity
     :animate: fade-in
     :open:
 
-    .. grid:: 2
+    .. grid:: 1 1 2 2
 
         .. grid-item-card:: :octicon:`bell` Responding to Events
             :link: responding-to-events/index

diff --git a/docs/source/creating-interfaces/html-with-idom.rst b/docs/source/creating-interfaces/html-with-idom.rst
@@ -9,7 +9,7 @@ code examples below. The one on the left shows how to make a basic title and tod
 using standard HTML, the one of the right uses IDOM in Python, and below is a view of
 what the HTML would look like if displayed:
 
-.. grid:: 2
+.. grid:: 1 1 2 2
     :margin: 0
     :padding: 0
 

diff --git a/docs/source/creating-interfaces/index.rst b/docs/source/creating-interfaces/index.rst
@@ -13,7 +13,7 @@ Creating Interfaces
     :animate: fade-in
     :open:
 
-    .. grid:: 2
+    .. grid:: 1 1 2 2
 
         .. grid-item-card:: :octicon:`code-square` HTML with IDOM
             :link: html-with-idom

diff --git a/docs/source/developing-idom/index.rst b/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:: 2
+.. grid:: 1 1 2 2
     :gutter: 1
 
     .. grid-item-card:: :octicon:`people` Discussion Forum

diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst
@@ -12,7 +12,7 @@ Getting Started
     :animate: fade-in
     :open:
 
-    .. grid:: 2
+    .. grid:: 1 1 2 2
 
         .. grid-item-card:: :octicon:`tools` Installing IDOM
             :link: installing-idom

diff --git a/docs/source/index.rst b/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:: 2
+.. grid:: 1 1 2 2
 
     .. grid-item::