v2.5.0 more docs

Author: jamesdbrock

_modules/edifice/engine.html

@@ -973,7 +973,8 @@ <h1>Source code for edifice.engine</h1><div class="highlight"><pre>
 <span class="sd">    The **props** are the arguments passed to the :func:`@component&lt;component&gt;` function.</span>
 
 <span class="sd">    The :func:`@component&lt;component&gt;` will be re-rendered when some of its **props** are not</span>
-<span class="sd">    :code:`__eq__` to the **props** from the last time the @component rendered.</span>
+<span class="sd">    :code:`__eq__` to the **props** from the last time the</span>
+<span class="sd">    :func:`@component&lt;component&gt;` rendered.</span>
 <span class="sd">    If the **props** are all :code:`__eq__`, the :func:`@component&lt;component&gt;`</span>
 <span class="sd">    will not re-render.</span>
 

_modules/edifice/hooks.html

@@ -449,7 +449,8 @@ <h1>Source code for edifice.hooks</h1><div class="highlight"><pre>
 
 <span class="sd">    An **initializer function** is a function of no arguments.</span>
 
-<span class="sd">    If an **initializer function** is passed to :func:`use_state`, then the</span>
+<span class="sd">    If an **initializer function** is passed to :func:`use_state` instead</span>
+<span class="sd">    of an initial value, then the</span>
 <span class="sd">    **initializer function** will be called once before</span>
 <span class="sd">    this :func:`components`’s first render to get the **initial state**.</span>
 
@@ -512,11 +513,20 @@ <h1>Source code for edifice.hooks</h1><div class="highlight"><pre>
 <span class="sd">    Do not mutate the state variable. The old state variable must be left</span>
 <span class="sd">    unmodified so that it can be compared to the new state variable during</span>
 <span class="sd">    the next render.</span>
-<span class="sd">    Instead create a shallow `copy &lt;https://docs.python.org/3/library/copy.html#copy.copy&gt;`_</span>
-<span class="sd">    of the state, modify the copy, then call the **setter function** with the modified copy.</span>
+
+<span class="sd">    If Python does not have an</span>
+<span class="sd">    `immutable &lt;https://docs.python.org/3/glossary.html#term-immutable&gt;`_</span>
+<span class="sd">    version of your state data structure,</span>
+<span class="sd">    like for example the :code:`dict`, then you just have to take care to never</span>
+<span class="sd">    mutate it.</span>
+
+<span class="sd">    Instead of mutating a state :code:`list`, create a</span>
+<span class="sd">    shallow `copy &lt;https://docs.python.org/3/library/copy.html#copy.copy&gt;`_</span>
+<span class="sd">    of the :code:`list`, modify the copy, then call the **setter function**</span>
+<span class="sd">    with the modified copy.</span>
 
 <span class="sd">    .. code-block:: python</span>
-<span class="sd">        :caption: Updater function with shallow copy</span>
+<span class="sd">        :caption: Updater function with shallow copy of a list</span>
 
 <span class="sd">        from copy import copy</span>
 <span class="sd">        from typing import cast</span>
@@ -537,12 +547,35 @@ <h1>Source code for edifice.hooks</h1><div class="highlight"><pre>
 <span class="sd">                for t in x:</span>
 <span class="sd">                    Label(text=t)</span>
 
-<span class="sd">    A good technique for declaring immutable state datastructures is to use</span>
-<span class="sd">    `frozen dataclasses &lt;https://docs.python.org/3/library/dataclasses.html#frozen-instances&gt;`_.</span>
-<span class="sd">    Use the</span>
-<span class="sd">    `replace() &lt;https://docs.python.org/3/library/dataclasses.html#dataclasses.replace&gt;`_</span>
-<span class="sd">    function to update the dataclass.</span>
+<span class="sd">    Techniques for `immutable &lt;https://docs.python.org/3/glossary.html#term-immutable&gt;`_ datastructures in Python</span>
+<span class="sd">    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^</span>
+
+<span class="sd">    - `Shallow copy &lt;https://docs.python.org/3/library/copy.html#copy.copy&gt;`_.</span>
+<span class="sd">      We never need a deep copy because all the data structure items are also immutable.</span>
+<span class="sd">    - `Frozen dataclasses &lt;https://docs.python.org/3/library/dataclasses.html#frozen-instances&gt;`_.</span>
+<span class="sd">      Use the</span>
+<span class="sd">      `replace() &lt;https://docs.python.org/3/library/dataclasses.html#dataclasses.replace&gt;`_</span>
+<span class="sd">      function to update the dataclass.</span>
+<span class="sd">    - Tuples (:code:`my_list:tuple[str, ...]`) instead of lists (:code:`my_list:list[str]`).</span>
+
+<span class="sd">    .. code-block:: python</span>
+<span class="sd">        :caption: Updater function with shallow copy of a tuple</span>
+
+<span class="sd">        from typing import cast</span>
+
+<span class="sd">        def Stateful(self):</span>
+<span class="sd">            x, x_setter = use_state(cast(tuple[str, ...], ()))</span>
+
+<span class="sd">            def updater(x_previous:tuple[str, ...]) -&gt; tuple[str, ...]:</span>
+<span class="sd">                return x_previous + (&quot;Label Text &quot; + str(len(x_previous)),)</span>
 
+<span class="sd">            with View():</span>
+<span class="sd">                Button(</span>
+<span class="sd">                    title=&quot;Add One&quot;,</span>
+<span class="sd">                    on_click = lambda _event: x_setter(updater)</span>
+<span class="sd">                )</span>
+<span class="sd">                for t in x:</span>
+<span class="sd">                    Label(text=t)</span>
 <span class="sd">    Args:</span>
 <span class="sd">        initial_state: The initial **state value** or **initializer function**.</span>
 <span class="sd">    Returns:</span>
@@ -653,19 +686,26 @@ <h1>Source code for edifice.hooks</h1><div class="highlight"><pre>
 <span class="sd">        :caption: use_async to fetch from the network</span>
 
 <span class="sd">        @component</span>
-<span class="sd">        def Asynchronous(self):</span>
-<span class="sd">            myword, myword_set = use_state(&quot;&quot;)</span>
+<span class="sd">        def WordDefinition(self, word:str):</span>
+<span class="sd">            definition, definition_set = use_state(&quot;&quot;)</span>
 
 <span class="sd">            async def fetcher():</span>
 <span class="sd">                try:</span>
-<span class="sd">                    x = await fetch_word_from_the_internet()</span>
-<span class="sd">                    myword_set(x)</span>
+<span class="sd">                    definition_set(&quot;Fetch definition pending&quot;)</span>
+<span class="sd">                    x = await fetch_definition_from_the_internet(word)</span>
+<span class="sd">                    definition_set(x)</span>
 <span class="sd">                except asyncio.CancelledError:</span>
-<span class="sd">                    myword_set(&quot;Fetch word cancelled&quot;)</span>
+<span class="sd">                    definition_set(&quot;Fetch definition cancelled&quot;)</span>
 <span class="sd">                    raise</span>
+<span class="sd">                except BaseException:</span>
+<span class="sd">                    defintion_set(&quot;Fetch definition failed&quot;)</span>
+
+<span class="sd">            cancel_fetcher = use_async(fetcher, word)</span>
 
-<span class="sd">            _cancel_fetcher = use_async(fetcher, 0)</span>
-<span class="sd">            Label(text=myword)</span>
+<span class="sd">            with VBoxView():</span>
+<span class="sd">                Label(text=word)</span>
+<span class="sd">                Label(text=definition)</span>
+<span class="sd">                Button(text=&quot;Cancel fetch&quot;, on_click=lambda _:cancel_fetcher())</span>
 
 <span class="sd">    Cancellation</span>
 <span class="sd">    ============</span>

_sources/edifice.rst.txt

@@ -59,17 +59,19 @@ Declaring an Element tree in a :func:`@component <component>` Element render fun
 like this.
 To declare an Element to be the parent of some other
 child Elements in the tree, use the parent as a
-`with statement context manager <https://docs.python.org/3/reference/datamodel.html#context-managers>`_::
+`with statement context manager <https://docs.python.org/3/reference/datamodel.html#context-managers>`_.
+
+.. code-block:: python
 
     @component
     def MyApp(self):
         with Window():
             with VBoxView():
                 with HBoxView():
-                    Label("Username: ")
+                    Label(text="Username: ")
                     TextInput()
                 with HBoxView():
-                    Label("Email: ")
+                    Label(text="Email: ")
                     TextInput()
 
 In HTML/XML/JSX, this would be written as:
@@ -85,6 +87,7 @@ In HTML/XML/JSX, this would be written as:
             <HBoxView>
                 <Label text="Email: " />
                 <TextInput />
+            </HBoxView>
         </VBoxView>
     </Window>
 
@@ -225,19 +228,23 @@ Element tree.
 
 Because Element initialization is a render side-effect,
 we have to be careful about binding Elements to variables
-and passing them around. They will insert themselves at the time they are
-created. This code will **NOT** declare the intended Element tree::
+and passing them around. They will insert themselves in the tree at the time
+they are initialized. This code will **NOT** declare the intended Element tree.
+
+.. code-block:: python
 
     @component
     def MySimpleComp(self, prop1, prop2, prop3):
         label3 = Label(text=prop3)
         with VBoxView():
             Label(text=prop1)
             Label(text=prop2)
-            label3
+            label3 # This will NOT render here as intended
 
 To solve this, defer the construction of the Element with a lambda function.
-This code will declare the same intended Element tree as the code above::
+This code will declare the same intended Element tree as the code above.
+
+.. code-block:: python
 
     @component
     def MySimpleComp(self, prop1, prop2, prop3):
@@ -248,7 +255,9 @@ This code will declare the same intended Element tree as the code above::
             label3()
 
 If these component Elements are render functions, then why couldn’t we just write
-a normal render function with no decorator instead::
+a normal render function with no decorator instead?
+
+.. code-block:: python
 
     # No decorator
     def MySimpleComp(prop1, prop2, prop3):

_sources/index.rst.txt

@@ -81,7 +81,8 @@ Table of Contents
 Why Edifice?
 ------------
 
-**Declarative**
+Declarative
+^^^^^^^^^^^
 
 Most existing GUI libraries in Python, such as Tkinter and Qt, operate imperatively.
 To create a dynamic application using these libraries,
@@ -112,14 +113,16 @@ a button and a label with the current value of :code:`number`.
 Clicking the button will add 5 to the :code:`number`.
 If the :code:`number` is “mid” then another label will reveal that fact.
 
-**Developer Tools**
+Developer Tools
+^^^^^^^^^^^^^^^
 
 - Dynamic hot-reloading of source code changes.
 - Element Inspector.
 
 See :doc:`developer_tools` for more details.
 
-**Edifice vs. Qt Quick**
+Edifice vs. Qt Quick
+^^^^^^^^^^^^^^^^^^^^
 
 `Qt Quick <https://doc.qt.io/qtforpython-6/PySide6/QtQuick/>`_ is Qt’s declarative GUI framework for Qt.
 
@@ -139,7 +142,8 @@ they require imperative logic in another language for dynamism.
 Edifice and React allow fully dynamic applications to be specified
 declaratively in one language.
 
-**Extendable**
+Extendable
+^^^^^^^^^^
 
 Edifice does not support every feature of Qt,
 but it is easy to interface with Qt, either :ref:`incorporating a Qt Widget<custom_widget>` into an Edifice component,

edifice.html

@@ -440,16 +440,16 @@ <h2>Declaring Element Trees<a class="headerlink" href="#declaring-element-trees"
 like this.
 To declare an Element to be the parent of some other
 child Elements in the tree, use the parent as a
-<a class="reference external" href="https://docs.python.org/3/reference/datamodel.html#context-managers">with statement context manager</a>:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@component</span>
+<a class="reference external" href="https://docs.python.org/3/reference/datamodel.html#context-managers">with statement context manager</a>.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@component</span>
 <span class="k">def</span> <span class="nf">MyApp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
     <span class="k">with</span> <span class="n">Window</span><span class="p">():</span>
         <span class="k">with</span> <span class="n">VBoxView</span><span class="p">():</span>
             <span class="k">with</span> <span class="n">HBoxView</span><span class="p">():</span>
-                <span class="n">Label</span><span class="p">(</span><span class="s2">&quot;Username: &quot;</span><span class="p">)</span>
+                <span class="n">Label</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="s2">&quot;Username: &quot;</span><span class="p">)</span>
                 <span class="n">TextInput</span><span class="p">()</span>
             <span class="k">with</span> <span class="n">HBoxView</span><span class="p">():</span>
-                <span class="n">Label</span><span class="p">(</span><span class="s2">&quot;Email: &quot;</span><span class="p">)</span>
+                <span class="n">Label</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="s2">&quot;Email: &quot;</span><span class="p">)</span>
                 <span class="n">TextInput</span><span class="p">()</span>
 </pre></div>
 </div>
@@ -463,6 +463,7 @@ <h2>Declaring Element Trees<a class="headerlink" href="#declaring-element-trees"
 <span class="w">        </span><span class="nt">&lt;HBoxView&gt;</span>
 <span class="w">            </span><span class="nt">&lt;Label</span><span class="w"> </span><span class="na">text=</span><span class="s">&quot;Email: &quot;</span><span class="w"> </span><span class="nt">/&gt;</span>
 <span class="w">            </span><span class="nt">&lt;TextInput</span><span class="w"> </span><span class="nt">/&gt;</span>
+<span class="w">        </span><span class="nt">&lt;/HBoxView&gt;</span>
 <span class="w">    </span><span class="nt">&lt;/VBoxView&gt;</span>
 <span class="nt">&lt;/Window&gt;</span>
 </pre></div>
@@ -588,20 +589,20 @@ <h2>Element initialization is a render side-effect<a class="headerlink" href="#e
 Element tree.</p>
 <p>Because Element initialization is a render side-effect,
 we have to be careful about binding Elements to variables
-and passing them around. They will insert themselves at the time they are
-created. This code will <strong>NOT</strong> declare the intended Element tree:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@component</span>
+and passing them around. They will insert themselves in the tree at the time
+they are initialized. This code will <strong>NOT</strong> declare the intended Element tree.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@component</span>
 <span class="k">def</span> <span class="nf">MySimpleComp</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">prop1</span><span class="p">,</span> <span class="n">prop2</span><span class="p">,</span> <span class="n">prop3</span><span class="p">):</span>
     <span class="n">label3</span> <span class="o">=</span> <span class="n">Label</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="n">prop3</span><span class="p">)</span>
     <span class="k">with</span> <span class="n">VBoxView</span><span class="p">():</span>
         <span class="n">Label</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="n">prop1</span><span class="p">)</span>
         <span class="n">Label</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="n">prop2</span><span class="p">)</span>
-        <span class="n">label3</span>
+        <span class="n">label3</span> <span class="c1"># This will NOT render here as intended</span>
 </pre></div>
 </div>
 <p>To solve this, defer the construction of the Element with a lambda function.
-This code will declare the same intended Element tree as the code above:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="nd">@component</span>
+This code will declare the same intended Element tree as the code above.</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="nd">@component</span>
 <span class="k">def</span> <span class="nf">MySimpleComp</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">prop1</span><span class="p">,</span> <span class="n">prop2</span><span class="p">,</span> <span class="n">prop3</span><span class="p">):</span>
     <span class="n">label3</span> <span class="o">=</span> <span class="k">lambda</span><span class="p">:</span> <span class="n">Label</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="n">prop3</span><span class="p">)</span>
     <span class="k">with</span> <span class="n">VBoxView</span><span class="p">():</span>
@@ -611,8 +612,8 @@ <h2>Element initialization is a render side-effect<a class="headerlink" href="#e
 </pre></div>
 </div>
 <p>If these component Elements are render functions, then why couldn’t we just write
-a normal render function with no decorator instead:</p>
-<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># No decorator</span>
+a normal render function with no decorator instead?</p>
+<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># No decorator</span>
 <span class="k">def</span> <span class="nf">MySimpleComp</span><span class="p">(</span><span class="n">prop1</span><span class="p">,</span> <span class="n">prop2</span><span class="p">,</span> <span class="n">prop3</span><span class="p">):</span>
     <span class="k">with</span> <span class="n">VBoxView</span><span class="p">():</span>
         <span class="n">Label</span><span class="p">(</span><span class="n">text</span><span class="o">=</span><span class="n">prop1</span><span class="p">)</span>