Release 0.0.8

docs-src/apidocs/pymerlin/pymerlin.model_actions.rst

@@ -21,8 +21,12 @@ Functions
      - .. autodoc2-docstring:: pymerlin.model_actions.delay
           :parser: myst
           :summary:
-   * - :py:obj:`spawn <pymerlin.model_actions.spawn>`
-     - .. autodoc2-docstring:: pymerlin.model_actions.spawn
+   * - :py:obj:`spawn_activity <pymerlin.model_actions.spawn_activity>`
+     - .. autodoc2-docstring:: pymerlin.model_actions.spawn_activity
+          :parser: myst
+          :summary:
+   * - :py:obj:`spawn_task <pymerlin.model_actions.spawn_task>`
+     - .. autodoc2-docstring:: pymerlin.model_actions.spawn_task
           :parser: myst
           :summary:
    * - :py:obj:`call <pymerlin.model_actions.call>`
@@ -43,34 +47,36 @@ API
 
 .. py:function:: delay(duration)
    :canonical: pymerlin.model_actions.delay
-   :async:
 
    .. autodoc2-docstring:: pymerlin.model_actions.delay
       :parser: myst
 
-.. py:function:: spawn(model, child)
-   :canonical: pymerlin.model_actions.spawn
+.. py:function:: spawn_activity(child)
+   :canonical: pymerlin.model_actions.spawn_activity
+
+   .. autodoc2-docstring:: pymerlin.model_actions.spawn_activity
+      :parser: myst
+
+.. py:function:: spawn_task(child, args)
+   :canonical: pymerlin.model_actions.spawn_task
 
-   .. autodoc2-docstring:: pymerlin.model_actions.spawn
+   .. autodoc2-docstring:: pymerlin.model_actions.spawn_task
       :parser: myst
 
-.. py:function:: call(model, child)
+.. py:function:: call(child)
    :canonical: pymerlin.model_actions.call
-   :async:
 
    .. autodoc2-docstring:: pymerlin.model_actions.call
       :parser: myst
 
 .. py:function:: wait_until(condition)
    :canonical: pymerlin.model_actions.wait_until
-   :async:
 
    .. autodoc2-docstring:: pymerlin.model_actions.wait_until
       :parser: myst
 
 .. py:function:: _yield_with(status)
    :canonical: pymerlin.model_actions._yield_with
-   :async:
 
    .. autodoc2-docstring:: pymerlin.model_actions._yield_with
       :parser: myst

docs/_sources/apidocs/pymerlin/pymerlin.model_actions.rst.txt

@@ -21,8 +21,12 @@ Functions
      - .. autodoc2-docstring:: pymerlin.model_actions.delay
           :parser: myst
           :summary:
-   * - :py:obj:`spawn <pymerlin.model_actions.spawn>`
-     - .. autodoc2-docstring:: pymerlin.model_actions.spawn
+   * - :py:obj:`spawn_activity <pymerlin.model_actions.spawn_activity>`
+     - .. autodoc2-docstring:: pymerlin.model_actions.spawn_activity
+          :parser: myst
+          :summary:
+   * - :py:obj:`spawn_task <pymerlin.model_actions.spawn_task>`
+     - .. autodoc2-docstring:: pymerlin.model_actions.spawn_task
           :parser: myst
           :summary:
    * - :py:obj:`call <pymerlin.model_actions.call>`
@@ -43,34 +47,36 @@ API
 
 .. py:function:: delay(duration)
    :canonical: pymerlin.model_actions.delay
-   :async:
 
    .. autodoc2-docstring:: pymerlin.model_actions.delay
       :parser: myst
 
-.. py:function:: spawn(model, child)
-   :canonical: pymerlin.model_actions.spawn
+.. py:function:: spawn_activity(child)
+   :canonical: pymerlin.model_actions.spawn_activity
+
+   .. autodoc2-docstring:: pymerlin.model_actions.spawn_activity
+      :parser: myst
+
+.. py:function:: spawn_task(child, args)
+   :canonical: pymerlin.model_actions.spawn_task
 
-   .. autodoc2-docstring:: pymerlin.model_actions.spawn
+   .. autodoc2-docstring:: pymerlin.model_actions.spawn_task
       :parser: myst
 
-.. py:function:: call(model, child)
+.. py:function:: call(child)
    :canonical: pymerlin.model_actions.call
-   :async:
 
    .. autodoc2-docstring:: pymerlin.model_actions.call
       :parser: myst
 
 .. py:function:: wait_until(condition)
    :canonical: pymerlin.model_actions.wait_until
-   :async:
 
    .. autodoc2-docstring:: pymerlin.model_actions.wait_until
       :parser: myst
 
 .. py:function:: _yield_with(status)
    :canonical: pymerlin.model_actions._yield_with
-   :async:
 
    .. autodoc2-docstring:: pymerlin.model_actions._yield_with
       :parser: myst

docs/_sources/architecture.md.txt

@@ -34,11 +34,10 @@ that can be understood by the rest of the system.
 
 ## Async/await vs threads
 
-pymerlin requires tasks to be defined as async functions (a.k.a coroutines), and for them to pause by calling and awaiting
-a model action. The task's loop is pause, and kept in memory until it is time to resume the task, at which point that
-loop is resumed. Alternatively, this could be done via threads, though as of writing that has not been prototyped. Python's
-Global Interpreter Lock (GIL) poses some restrictions to threads - but in the Aerie paradigm, where only one thread is
-running at a time, perhaps these restrictions are insignificant. It would be worth a try.
+pymerlin originally required tasks to be defined as async functions (a.k.a coroutines), but that was in tension with
+the "approachability over performance" principle. Version 0.0.8 replaced async functions with regular functions, and
+used threads instead. This significantly simplified the implementation, as well as the mental model. If thread switching
+turns out to be a performance bottleneck, async tasks should be reintroduced as an optional alternative. 
 
 ## Use pythonic idioms
 
@@ -58,4 +57,9 @@ To the extent possible, pymerlin should expose pythonic APIs. This means:
 Consult [PEP8](https://peps.python.org/pep-0008/#naming-conventions) for additional ideas.
 
 ### But what about Aerie idioms?
-For now, stick to pythonic style - cross that bridge when uploading pymerlin can build Aerie-compatible jars
+For now, stick to pythonic style - cross that bridge when uploading pymerlin can build Aerie-compatible jars
+
+## Emphasize debuggability
+On one hand, we need to do our best not to show users Java stack traces - or at least show them when they're useful and
+not overwhelming. On the other hand, we must not _obscure_ useful debugging information. This is a delicate balance to
+strike.

docs/apidocs/pymerlin/pymerlin.model_actions.html

@@ -321,17 +321,21 @@ <h3>Functions<a class="headerlink" href="#functions" title="Link to this heading
 <tr class="row-odd"><td><p><a class="reference internal" href="#pymerlin.model_actions.delay" title="pymerlin.model_actions.delay"><code class="xref py py-obj docutils literal notranslate"><span class="pre">delay</span></code></a></p></td>
 <td></td>
 </tr>
-<tr class="row-even"><td><p><a class="reference internal" href="#pymerlin.model_actions.spawn" title="pymerlin.model_actions.spawn"><code class="xref py py-obj docutils literal notranslate"><span class="pre">spawn</span></code></a></p></td>
+<tr class="row-even"><td><p><a class="reference internal" href="#pymerlin.model_actions.spawn_activity" title="pymerlin.model_actions.spawn_activity"><code class="xref py py-obj docutils literal notranslate"><span class="pre">spawn_activity</span></code></a></p></td>
 <td><p>:param coro:
 :return:</p></td>
 </tr>
-<tr class="row-odd"><td><p><a class="reference internal" href="#pymerlin.model_actions.call" title="pymerlin.model_actions.call"><code class="xref py py-obj docutils literal notranslate"><span class="pre">call</span></code></a></p></td>
+<tr class="row-odd"><td><p><a class="reference internal" href="#pymerlin.model_actions.spawn_task" title="pymerlin.model_actions.spawn_task"><code class="xref py py-obj docutils literal notranslate"><span class="pre">spawn_task</span></code></a></p></td>
+<td><p>:param coro:
+:return:</p></td>
+</tr>
+<tr class="row-even"><td><p><a class="reference internal" href="#pymerlin.model_actions.call" title="pymerlin.model_actions.call"><code class="xref py py-obj docutils literal notranslate"><span class="pre">call</span></code></a></p></td>
 <td></td>
 </tr>
-<tr class="row-even"><td><p><a class="reference internal" href="#pymerlin.model_actions.wait_until" title="pymerlin.model_actions.wait_until"><code class="xref py py-obj docutils literal notranslate"><span class="pre">wait_until</span></code></a></p></td>
+<tr class="row-odd"><td><p><a class="reference internal" href="#pymerlin.model_actions.wait_until" title="pymerlin.model_actions.wait_until"><code class="xref py py-obj docutils literal notranslate"><span class="pre">wait_until</span></code></a></p></td>
 <td><p>:param condition: A function returning True or False</p></td>
 </tr>
-<tr class="row-odd"><td><p><a class="reference internal" href="#pymerlin.model_actions._yield_with" title="pymerlin.model_actions._yield_with"><code class="xref py py-obj docutils literal notranslate"><span class="pre">_yield_with</span></code></a></p></td>
+<tr class="row-even"><td><p><a class="reference internal" href="#pymerlin.model_actions._yield_with" title="pymerlin.model_actions._yield_with"><code class="xref py py-obj docutils literal notranslate"><span class="pre">_yield_with</span></code></a></p></td>
 <td></td>
 </tr>
 </tbody>
@@ -342,30 +346,37 @@ <h3>Functions<a class="headerlink" href="#functions" title="Link to this heading
 <h3>API<a class="headerlink" href="#api" title="Link to this heading">¶</a></h3>
 <dl class="py function">
 <dt class="sig sig-object py" id="pymerlin.model_actions.delay">
-<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">delay</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">duration</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions.delay" title="Link to this definition">¶</a></dt>
+<span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">delay</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">duration</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions.delay" title="Link to this definition">¶</a></dt>
 <dd></dd></dl>
 
 <dl class="py function">
-<dt class="sig sig-object py" id="pymerlin.model_actions.spawn">
-<span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">spawn</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">model</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">child</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions.spawn" title="Link to this definition">¶</a></dt>
+<dt class="sig sig-object py" id="pymerlin.model_actions.spawn_activity">
+<span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">spawn_activity</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">child</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions.spawn_activity" title="Link to this definition">¶</a></dt>
+<dd><p>:param coro:
+:return:</p>
+</dd></dl>
+
+<dl class="py function">
+<dt class="sig sig-object py" id="pymerlin.model_actions.spawn_task">
+<span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">spawn_task</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">child</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">args</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions.spawn_task" title="Link to this definition">¶</a></dt>
 <dd><p>:param coro:
 :return:</p>
 </dd></dl>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pymerlin.model_actions.call">
-<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">call</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">model</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">child</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions.call" title="Link to this definition">¶</a></dt>
+<span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">call</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">child</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions.call" title="Link to this definition">¶</a></dt>
 <dd></dd></dl>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pymerlin.model_actions.wait_until">
-<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">wait_until</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">condition</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions.wait_until" title="Link to this definition">¶</a></dt>
+<span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">wait_until</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">condition</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions.wait_until" title="Link to this definition">¶</a></dt>
 <dd><p>:param condition: A function returning True or False</p>
 </dd></dl>
 
 <dl class="py function">
 <dt class="sig sig-object py" id="pymerlin.model_actions._yield_with">
-<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">_yield_with</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions._yield_with" title="Link to this definition">¶</a></dt>
+<span class="sig-prename descclassname"><span class="pre">pymerlin.model_actions.</span></span><span class="sig-name descname"><span class="pre">_yield_with</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">status</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#pymerlin.model_actions._yield_with" title="Link to this definition">¶</a></dt>
 <dd></dd></dl>
 
 </section>
@@ -432,7 +443,8 @@ <h3>API<a class="headerlink" href="#api" title="Link to this heading">¶</a></h3
 <li><a class="reference internal" href="#functions">Functions</a></li>
 <li><a class="reference internal" href="#api">API</a><ul>
 <li><a class="reference internal" href="#pymerlin.model_actions.delay"><code class="docutils literal notranslate"><span class="pre">delay()</span></code></a></li>
-<li><a class="reference internal" href="#pymerlin.model_actions.spawn"><code class="docutils literal notranslate"><span class="pre">spawn()</span></code></a></li>
+<li><a class="reference internal" href="#pymerlin.model_actions.spawn_activity"><code class="docutils literal notranslate"><span class="pre">spawn_activity()</span></code></a></li>
+<li><a class="reference internal" href="#pymerlin.model_actions.spawn_task"><code class="docutils literal notranslate"><span class="pre">spawn_task()</span></code></a></li>
 <li><a class="reference internal" href="#pymerlin.model_actions.call"><code class="docutils literal notranslate"><span class="pre">call()</span></code></a></li>
 <li><a class="reference internal" href="#pymerlin.model_actions.wait_until"><code class="docutils literal notranslate"><span class="pre">wait_until()</span></code></a></li>
 <li><a class="reference internal" href="#pymerlin.model_actions._yield_with"><code class="docutils literal notranslate"><span class="pre">_yield_with()</span></code></a></li>

docs/architecture.html

@@ -341,11 +341,10 @@ <h2>Round trips<a class="headerlink" href="#round-trips" title="Link to this hea
 </section>
 <section id="async-await-vs-threads">
 <h2>Async/await vs threads<a class="headerlink" href="#async-await-vs-threads" title="Link to this heading">¶</a></h2>
-<p>pymerlin requires tasks to be defined as async functions (a.k.a coroutines), and for them to pause by calling and awaiting
-a model action. The task’s loop is pause, and kept in memory until it is time to resume the task, at which point that
-loop is resumed. Alternatively, this could be done via threads, though as of writing that has not been prototyped. Python’s
-Global Interpreter Lock (GIL) poses some restrictions to threads - but in the Aerie paradigm, where only one thread is
-running at a time, perhaps these restrictions are insignificant. It would be worth a try.</p>
+<p>pymerlin originally required tasks to be defined as async functions (a.k.a coroutines), but that was in tension with
+the “approachability over performance” principle. Version 0.0.8 replaced async functions with regular functions, and
+used threads instead. This significantly simplified the implementation, as well as the mental model. If thread switching
+turns out to be a performance bottleneck, async tasks should be reintroduced as an optional alternative.</p>
 </section>
 <section id="use-pythonic-idioms">
 <h2>Use pythonic idioms<a class="headerlink" href="#use-pythonic-idioms" title="Link to this heading">¶</a></h2>
@@ -369,6 +368,12 @@ <h3>But what about Aerie idioms?<a class="headerlink" href="#but-what-about-aeri
 <p>For now, stick to pythonic style - cross that bridge when uploading pymerlin can build Aerie-compatible jars</p>
 </section>
 </section>
+<section id="emphasize-debuggability">
+<h2>Emphasize debuggability<a class="headerlink" href="#emphasize-debuggability" title="Link to this heading">¶</a></h2>
+<p>On one hand, we need to do our best not to show users Java stack traces - or at least show them when they’re useful and
+not overwhelming. On the other hand, we must not <em>obscure</em> useful debugging information. This is a delicate balance to
+strike.</p>
+</section>
 </section>
 
         </article>
@@ -434,6 +439,7 @@ <h3>But what about Aerie idioms?<a class="headerlink" href="#but-what-about-aeri
 <li><a class="reference internal" href="#but-what-about-aerie-idioms">But what about Aerie idioms?</a></li>
 </ul>
 </li>
+<li><a class="reference internal" href="#emphasize-debuggability">Emphasize debuggability</a></li>
 </ul>
 </li>
 </ul>

docs/genindex.html

@@ -495,12 +495,14 @@ <h2>S</h2>
   <table style="width: 100%" class="indextable genindextable"><tr>
     <td style="width: 33%; vertical-align: top;"><ul>
         <li><a href="apidocs/pymerlin/pymerlin.duration.html#pymerlin.duration.SECOND">SECOND (in module pymerlin.duration)</a>
+</li>
+        <li><a href="apidocs/pymerlin/pymerlin.duration.html#pymerlin.duration.SECONDS">SECONDS (in module pymerlin.duration)</a>
 </li>
     </ul></td>
     <td style="width: 33%; vertical-align: top;"><ul>
-        <li><a href="apidocs/pymerlin/pymerlin.duration.html#pymerlin.duration.SECONDS">SECONDS (in module pymerlin.duration)</a>
+        <li><a href="apidocs/pymerlin/pymerlin.model_actions.html#pymerlin.model_actions.spawn_activity">spawn_activity() (in module pymerlin.model_actions)</a>
 </li>
-        <li><a href="apidocs/pymerlin/pymerlin.model_actions.html#pymerlin.model_actions.spawn">spawn() (in module pymerlin.model_actions)</a>
+        <li><a href="apidocs/pymerlin/pymerlin.model_actions.html#pymerlin.model_actions.spawn_task">spawn_task() (in module pymerlin.model_actions)</a>
 </li>
     </ul></td>
   </tr></table>