Update unreleased documentation (#555)

* Update versions.json * Deployed c9fa680 to unreleased in versions with MkDocs 1.5.3 and mike 2.0.0 * Sort docs versions --------- Co-authored-by: GitHub Actions Bot <[email protected]>
PrefectHQ · Jan 10, 2024 · 9b484c9 · 9b484c9
1 parent efad5c0
commit 9b484c9
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 24 deletions.
diff --git a/versions/unreleased/api-ref/prefect/blocks/core/index.html b/versions/unreleased/api-ref/prefect/blocks/core/index.html
@@ -9959,7 +9959,13 @@ <h2 id="prefect.blocks.core.Block" class="doc doc-heading">
 <span class="normal">1080</span>
 <span class="normal">1081</span>
 <span class="normal">1082</span>
-<span class="normal">1083</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@register_base_type</span>
+<span class="normal">1083</span>
+<span class="normal">1084</span>
+<span class="normal">1085</span>
+<span class="normal">1086</span>
+<span class="normal">1087</span>
+<span class="normal">1088</span>
+<span class="normal">1089</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@register_base_type</span>
 <span class="nd">@instrument_method_calls_on_class_instances</span>
 <span class="k">class</span> <span class="nc">Block</span><span class="p">(</span><span class="n">BaseModel</span><span class="p">,</span> <span class="n">ABC</span><span class="p">):</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
@@ -10718,11 +10724,14 @@ <h2 id="prefect.blocks.core.Block" class="doc doc-heading">
 <span class="sd">                `is_anonymous` is `True`.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="k">if</span> <span class="n">name</span> <span class="ow">is</span> <span class="kc">None</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">is_anonymous</span><span class="p">:</span>
-            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
-                <span class="s2">&quot;You&#39;re attempting to save a block document without a name. &quot;</span>
-                <span class="s2">&quot;Please either save a block document with a name or set &quot;</span>
-                <span class="s2">&quot;is_anonymous to True.&quot;</span>
-            <span class="p">)</span>
+            <span class="k">if</span> <span class="bp">self</span><span class="o">.</span><span class="n">_block_document_name</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+                <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
+                    <span class="s2">&quot;You&#39;re attempting to save a block document without a name.&quot;</span>
+                    <span class="s2">&quot; Please either call `save` with a `name` or pass&quot;</span>
+                    <span class="s2">&quot; `is_anonymous=True` to save an anonymous block.&quot;</span>
+                <span class="p">)</span>
+            <span class="k">else</span><span class="p">:</span>
+                <span class="n">name</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">_block_document_name</span>
 
         <span class="bp">self</span><span class="o">.</span><span class="n">_is_anonymous</span> <span class="o">=</span> <span class="n">is_anonymous</span>
 
@@ -10763,7 +10772,10 @@ <h2 id="prefect.blocks.core.Block" class="doc doc-heading">
     <span class="nd">@sync_compatible</span>
     <span class="nd">@instrument_instance_method_call</span><span class="p">()</span>
     <span class="k">async</span> <span class="k">def</span> <span class="nf">save</span><span class="p">(</span>
-        <span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">overwrite</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span> <span class="n">client</span><span class="p">:</span> <span class="s2">&quot;PrefectClient&quot;</span> <span class="o">=</span> <span class="kc">None</span>
+        <span class="bp">self</span><span class="p">,</span>
+        <span class="n">name</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+        <span class="n">overwrite</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+        <span class="n">client</span><span class="p">:</span> <span class="s2">&quot;PrefectClient&quot;</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
     <span class="p">):</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">        Saves the values of a block as a block document.</span>
@@ -11324,13 +11336,7 @@ <h3 id="prefect.blocks.core.Block.get_block_placeholder" class="doc doc-heading"
 
           <details class="quote">
             <summary>Source code in <code>prefect/blocks/core.py</code></summary>
-            <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1063</span>
-<span class="normal">1064</span>
-<span class="normal">1065</span>
-<span class="normal">1066</span>
-<span class="normal">1067</span>
-<span class="normal">1068</span>
-<span class="normal">1069</span>
+            <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal">1069</span>
 <span class="normal">1070</span>
 <span class="normal">1071</span>
 <span class="normal">1072</span>
@@ -11344,7 +11350,13 @@ <h3 id="prefect.blocks.core.Block.get_block_placeholder" class="doc doc-heading"
 <span class="normal">1080</span>
 <span class="normal">1081</span>
 <span class="normal">1082</span>
-<span class="normal">1083</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">get_block_placeholder</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
+<span class="normal">1083</span>
+<span class="normal">1084</span>
+<span class="normal">1085</span>
+<span class="normal">1086</span>
+<span class="normal">1087</span>
+<span class="normal">1088</span>
+<span class="normal">1089</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="k">def</span> <span class="nf">get_block_placeholder</span><span class="p">(</span><span class="bp">self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Returns the block placeholder for the current block which can be used for</span>
 <span class="sd">    templating.</span>
@@ -12167,7 +12179,7 @@ <h3 id="prefect.blocks.core.Block.save" class="doc doc-heading">
         <tr>
           <td><code>name</code></td>
           <td>
-                <code>str</code>
+                <code><span title="typing.Optional">Optional</span>[str]</code>
           </td>
           <td>
             <div class="doc-md-description">
@@ -12176,7 +12188,7 @@ <h3 id="prefect.blocks.core.Block.save" class="doc doc-heading">
             </div>
           </td>
           <td>
-              <em>required</em>
+                <code>None</code>
           </td>
         </tr>
         <tr>
@@ -12199,10 +12211,7 @@ <h3 id="prefect.blocks.core.Block.save" class="doc doc-heading">
 
           <details class="quote">
             <summary>Source code in <code>prefect/blocks/core.py</code></summary>
-            <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 995</span>
-<span class="normal"> 996</span>
-<span class="normal"> 997</span>
-<span class="normal"> 998</span>
+            <div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"> 998</span>
 <span class="normal"> 999</span>
 <span class="normal">1000</span>
 <span class="normal">1001</span>
@@ -12216,10 +12225,19 @@ <h3 id="prefect.blocks.core.Block.save" class="doc doc-heading">
 <span class="normal">1009</span>
 <span class="normal">1010</span>
 <span class="normal">1011</span>
-<span class="normal">1012</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@sync_compatible</span>
+<span class="normal">1012</span>
+<span class="normal">1013</span>
+<span class="normal">1014</span>
+<span class="normal">1015</span>
+<span class="normal">1016</span>
+<span class="normal">1017</span>
+<span class="normal">1018</span></pre></div></td><td class="code"><div><pre><span></span><code><span class="nd">@sync_compatible</span>
 <span class="nd">@instrument_instance_method_call</span><span class="p">()</span>
 <span class="k">async</span> <span class="k">def</span> <span class="nf">save</span><span class="p">(</span>
-    <span class="bp">self</span><span class="p">,</span> <span class="n">name</span><span class="p">:</span> <span class="nb">str</span><span class="p">,</span> <span class="n">overwrite</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span> <span class="n">client</span><span class="p">:</span> <span class="s2">&quot;PrefectClient&quot;</span> <span class="o">=</span> <span class="kc">None</span>
+    <span class="bp">self</span><span class="p">,</span>
+    <span class="n">name</span><span class="p">:</span> <span class="n">Optional</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
+    <span class="n">overwrite</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+    <span class="n">client</span><span class="p">:</span> <span class="s2">&quot;PrefectClient&quot;</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
 <span class="p">):</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Saves the values of a block as a block document.</span>

diff --git a/versions/unreleased/concepts/blocks/index.html b/versions/unreleased/concepts/blocks/index.html
@@ -9390,6 +9390,16 @@ <h3 id="saving-blocks">Saving blocks<a class="headerlink" href="#saving-blocks"
 <p>If this JSON value needs to be retrieved later to be used within a flow or task, we can use the <code>.save()</code> method on the block to store the value in a block document on the Prefect database for retrieval later:</p>
 <div class="highlight"><pre><span></span><code><span class="n">json_block</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;life-the-universe-everything&quot;</span><span class="p">)</span>
 </code></pre></div>
+<p>If you'd like to update the block value stored for a given <code>name</code>, you can overwrite the existing block document by setting <code>overwrite=True</code>:</p>
+<div class="highlight"><pre><span></span><code><span class="n">json_block</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">overwrite</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
+</code></pre></div>
+<div class="admonition tip">
+<p class="admonition-title">Tip</p>
+<p>in the above example, the name <code>"life-the-universe-everything"</code> is inferred from the existing block document</p>
+</div>
+<p>... or save the same block value as a new block document by setting the <code>name</code> parameter to a new value:</p>
+<div class="highlight"><pre><span></span><code><span class="n">json_block</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;actually-life-the-universe-everything&quot;</span><span class="p">)</span>
+</code></pre></div>
 <div class="admonition tip">
 <p class="admonition-title">Utilizing the UI</p>
 <p>Blocks documents can also be created and updated via the <a href="/ui/blocks/">Prefect UI</a>.</p>

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