Update unreleased documentation (#446)

* Update versions.json * Deployed 5377498 to unreleased in versions with MkDocs 1.5.3 and mike 1.1.2 * Sort docs versions --------- Co-authored-by: GitHub Actions Bot <[email protected]>
PrefectHQ · Oct 26, 2023 · 9a237cc · 9a237cc
1 parent 41eee52
commit 9a237cc
Show file tree

Hide file tree

Showing 8 changed files with 999 additions and 833 deletions.
diff --git a/versions/unreleased/api-ref/prefect/engine/index.html b/versions/unreleased/api-ref/prefect/engine/index.html
diff --git a/versions/unreleased/api-ref/prefect/flows/index.html b/versions/unreleased/api-ref/prefect/flows/index.html
diff --git a/versions/unreleased/api-ref/prefect/settings/index.html b/versions/unreleased/api-ref/prefect/settings/index.html
diff --git a/versions/unreleased/api-ref/prefect/utilities/callables/index.html b/versions/unreleased/api-ref/prefect/utilities/callables/index.html
@@ -7722,7 +7722,7 @@ <h2 id="prefect.utilities.callables.parameter_schema" class="doc doc-heading">
         <tr>
           <td><code>fn</code></td>
           <td>
-                <code>function</code>
+                <code><span title="typing.Callable">Callable</span></code>
           </td>
           <td>
             <div class="doc-md-description">
@@ -7748,7 +7748,7 @@ <h2 id="prefect.utilities.callables.parameter_schema" class="doc doc-heading">
     </thead>
     <tbody>
         <tr>
-<td><code>dict</code></td>          <td>
+<td><code>ParameterSchema</code></td>          <td>
                 <code><a class="autorefs autorefs-internal" title="prefect.utilities.callables.ParameterSchema" href="#prefect.utilities.callables.ParameterSchema">ParameterSchema</a></code>
           </td>
           <td>
@@ -7829,10 +7829,10 @@ <h2 id="prefect.utilities.callables.parameter_schema" class="doc doc-heading">
 <span class="sd">        - additional constraints (like possible enum values)</span>
 
 <span class="sd">    Args:</span>
-<span class="sd">        fn (function): The function whose arguments will be serialized</span>
+<span class="sd">        fn (Callable): The function whose arguments will be serialized</span>
 
 <span class="sd">    Returns:</span>
-<span class="sd">        dict: the argument schema</span>
+<span class="sd">        ParameterSchema: the argument schema</span>
 <span class="sd">    &quot;&quot;&quot;</span>
     <span class="n">signature</span> <span class="o">=</span> <span class="n">inspect</span><span class="o">.</span><span class="n">signature</span><span class="p">(</span><span class="n">fn</span><span class="p">)</span>
     <span class="n">model_fields</span> <span class="o">=</span> <span class="p">{}</span>

diff --git a/versions/unreleased/concepts/states/index.html b/versions/unreleased/concepts/states/index.html
@@ -2119,6 +2119,19 @@
     </span>
   </a>
 
+</li>
+
+          <li class="md-nav__item">
+  <a href="#pass-kwargs-to-your-hooks" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        <span class="md-typeset">
+          Pass <code>kwargs</code> to your hooks
+        </span>
+
+    </span>
+  </a>
+
 </li>
 
       </ul>
@@ -7000,6 +7013,19 @@
     </span>
   </a>
 
+</li>
+
+          <li class="md-nav__item">
+  <a href="#pass-kwargs-to-your-hooks" class="md-nav__link">
+    <span class="md-ellipsis">
+
+        <span class="md-typeset">
+          Pass <code>kwargs</code> to your hooks
+        </span>
+
+    </span>
+  </a>
+
 </li>
 
       </ul>
@@ -7335,6 +7361,50 @@ <h4 id="use-multiple-state-change-hooks">Use multiple state change hooks<a class
     <span class="n">on_failure</span><span class="o">=</span><span class="p">[</span><span class="n">my_failure_hook</span><span class="p">,</span> <span class="n">my_succeed_or_fail_hook</span><span class="p">]</span>
 <span class="p">)</span>
 </code></pre></div>
+<h4 id="pass-kwargs-to-your-hooks">Pass <code>kwargs</code> to your hooks<a class="headerlink" href="#pass-kwargs-to-your-hooks" title="Permanent link">&para;</a></h4>
+<p>The Prefect engine will call your hooks for you upon the state change, passing in the flow, flow run, and state objects.</p>
+<p>However, you can define your hook to have additional default arguments:
+<div class="highlight"><pre><span></span><code><span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span>
+
+<span class="n">data</span> <span class="o">=</span> <span class="p">{}</span>
+
+<span class="k">def</span> <span class="nf">my_hook</span><span class="p">(</span><span class="n">flow</span><span class="p">,</span> <span class="n">flow_run</span><span class="p">,</span> <span class="n">state</span><span class="p">,</span> <span class="n">my_arg</span><span class="o">=</span><span class="s2">&quot;custom_value&quot;</span><span class="p">):</span>
+    <span class="n">data</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">my_arg</span><span class="o">=</span><span class="n">my_arg</span><span class="p">,</span> <span class="n">state</span><span class="o">=</span><span class="n">state</span><span class="p">)</span>
+
+<span class="nd">@flow</span><span class="p">(</span><span class="n">on_completion</span><span class="o">=</span><span class="p">[</span><span class="n">my_hook</span><span class="p">])</span>
+<span class="k">def</span> <span class="nf">lazy_flow</span><span class="p">():</span>
+    <span class="k">pass</span>
+
+<span class="n">state</span> <span class="o">=</span> <span class="n">lazy_flow</span><span class="p">(</span><span class="n">return_state</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+
+<span class="k">assert</span> <span class="n">data</span> <span class="o">==</span> <span class="p">{</span><span class="s2">&quot;my_arg&quot;</span><span class="p">:</span> <span class="s2">&quot;custom_value&quot;</span><span class="p">,</span> <span class="s2">&quot;state&quot;</span><span class="p">:</span> <span class="n">state</span><span class="p">}</span>
+</code></pre></div></p>
+<p>... or define your hook to accept arbitrary keyword arguments:
+<div class="highlight"><pre><span></span><code><span class="kn">from</span> <span class="nn">functools</span> <span class="kn">import</span> <span class="n">partial</span>
+<span class="kn">from</span> <span class="nn">prefect</span> <span class="kn">import</span> <span class="n">flow</span><span class="p">,</span> <span class="n">task</span>
+
+<span class="n">data</span> <span class="o">=</span> <span class="p">{}</span>
+
+<span class="k">def</span> <span class="nf">my_hook</span><span class="p">(</span><span class="n">task</span><span class="p">,</span> <span class="n">task_run</span><span class="p">,</span> <span class="n">state</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
+    <span class="n">data</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">state</span><span class="o">=</span><span class="n">state</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
+
+<span class="nd">@task</span>
+<span class="k">def</span> <span class="nf">bad_task</span><span class="p">():</span>
+    <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;meh&quot;</span><span class="p">)</span>
+
+<span class="nd">@flow</span>
+<span class="k">def</span> <span class="nf">ok_with_failure_flow</span><span class="p">(</span><span class="n">x</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;foo&quot;</span><span class="p">,</span> <span class="n">y</span><span class="p">:</span> <span class="nb">int</span> <span class="o">=</span> <span class="mi">42</span><span class="p">):</span>
+    <span class="n">bad_task_with_a_hook</span> <span class="o">=</span> <span class="n">bad_task</span><span class="o">.</span><span class="n">with_options</span><span class="p">(</span>
+        <span class="n">on_failure</span><span class="o">=</span><span class="p">[</span><span class="n">partial</span><span class="p">(</span><span class="n">my_hook</span><span class="p">,</span> <span class="o">**</span><span class="nb">dict</span><span class="p">(</span><span class="n">x</span><span class="o">=</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="o">=</span><span class="n">y</span><span class="p">))]</span>
+    <span class="p">)</span>
+    <span class="c1"># return a tuple of &quot;bar&quot; and the task run state</span>
+    <span class="c1"># to avoid raising the task&#39;s exception</span>
+    <span class="k">return</span> <span class="s2">&quot;bar&quot;</span><span class="p">,</span> <span class="n">bad_task_with_a_hook</span><span class="p">(</span><span class="n">return_state</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+
+<span class="n">_</span><span class="p">,</span> <span class="n">task_run_state</span> <span class="o">=</span> <span class="n">ok_with_failure_flow</span><span class="p">()</span>
+
+<span class="k">assert</span> <span class="n">data</span> <span class="o">==</span> <span class="p">{</span><span class="s2">&quot;x&quot;</span><span class="p">:</span> <span class="s2">&quot;foo&quot;</span><span class="p">,</span> <span class="s2">&quot;y&quot;</span><span class="p">:</span> <span class="mi">42</span><span class="p">,</span> <span class="s2">&quot;state&quot;</span><span class="p">:</span> <span class="n">task_run_state</span><span class="p">}</span>
+</code></pre></div></p>
 <h3 id="more-examples-of-state-change-hooks">More examples of state change hooks<a class="headerlink" href="#more-examples-of-state-change-hooks" title="Permanent link">&para;</a></h3>
 <ul>
 <li><a href="/guides/state-change-hooks/#send-a-notification-when-a-flow-run-fails">Send a notification when a flow run fails</a></li>

diff --git a/versions/unreleased/search/search_index.json b/versions/unreleased/search/search_index.json