Deployed 312723d to v5.1 with Zensical 0.0.51 and mike 2.2.0+zensical-0.1.0

2026-09-19 03:09:56 +00:00 · 2026-08-29 21:49:48 +00:00
parent eca29a5bdb
commit c6a50f35a3
4 changed files with 119 additions and 4 deletions
@@ -2088,7 +2088,7 @@
 </span><span id="__span-1-16"><a id="__codelineno-1-16" name="__codelineno-1-16" href="#__codelineno-1-16"></a><span class="p">)</span>
 </span></code></pre></div>
 <h2 id="committing-before-the-response">Committing before the response<a class="headerlink" href="#committing-before-the-response" title="Permanent link">&para;</a></h2>
-<p><a href="../../reference/db/#fastapi_toolsets.db.Database"><code>db.install(app)</code></a> adds a middleware that commits the request's session when the response starts, after the endpoint returns and before the body is sent. With the middleware installed, the dependency does not commit again.</p>
+<p><a href="../../reference/db/#fastapi_toolsets.db.Database"><code>db.install(app)</code></a> adds a middleware that commits the request's session when the response starts, after the endpoint returns and before the body is sent. The dependency commits only if the middleware did not: when a function-scoped dependency unwinds before the response, or when the response never passes through the middleware. Either way the request is committed exactly once.</p>
 <p>The request is committed as a single transaction:</p>
 <ul>
 <li><strong>Read-after-write</strong>: a follow-up request sees the write.</li>
@@ -718,6 +718,17 @@
    </span>
  </a>
  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#eager-loading" class="md-nav__link">
+    <span class="md-ellipsis">
+      <span class="md-typeset">
+        Eager loading
+      </span>
+    </span>
+  </a>
+  
 </li>
      
    </ul>
@@ -1663,6 +1674,17 @@
    </span>
  </a>
  
+</li>
+      
+        <li class="md-nav__item">
+  <a href="#eager-loading" class="md-nav__link">
+    <span class="md-ellipsis">
+      <span class="md-typeset">
+        Eager loading
+      </span>
+    </span>
+  </a>
+  
 </li>
      
    </ul>
@@ -1817,6 +1839,31 @@
 </span><span id="__span-2-17"><a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a>    <span class="n">user</span> <span class="o">=</span> <span class="n">User</span><span class="p">(</span><span class="n">username</span><span class="o">=</span><span class="n">body</span><span class="o">.</span><span class="n">username</span><span class="p">,</span> <span class="n">role</span><span class="o">=</span><span class="n">role</span><span class="p">)</span>
 </span><span id="__span-2-18"><a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a>    <span class="o">...</span>
 </span></code></pre></div>
+<h2 id="eager-loading">Eager loading<a class="headerlink" href="#eager-loading" title="Permanent link">&para;</a></h2>
+<p>By default both factories fetch through a bare <code>CrudFactory(model)</code>, so relationships are not loaded. Pass <code>load_options</code> for a one-off, or <code>crud</code> to reuse a CRUD class you already configured:</p>
+<div class="language-python highlight"><pre><span></span><code><span id="__span-3-1"><a id="__codelineno-3-1" name="__codelineno-3-1" href="#__codelineno-3-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">sqlalchemy.orm</span><span class="w"> </span><span class="kn">import</span> <span class="n">selectinload</span>
+</span><span id="__span-3-2"><a id="__codelineno-3-2" name="__codelineno-3-2" href="#__codelineno-3-2"></a>
+</span><span id="__span-3-3"><a id="__codelineno-3-3" name="__codelineno-3-3" href="#__codelineno-3-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.crud</span><span class="w"> </span><span class="kn">import</span> <span class="n">CrudFactory</span>
+</span><span id="__span-3-4"><a id="__codelineno-3-4" name="__codelineno-3-4" href="#__codelineno-3-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">fastapi_toolsets.dependencies</span><span class="w"> </span><span class="kn">import</span> <span class="n">PathDependency</span>
+</span><span id="__span-3-5"><a id="__codelineno-3-5" name="__codelineno-3-5" href="#__codelineno-3-5"></a>
+</span><span id="__span-3-6"><a id="__codelineno-3-6" name="__codelineno-3-6" href="#__codelineno-3-6"></a><span class="n">UserDep</span> <span class="o">=</span> <span class="n">PathDependency</span><span class="p">(</span>
+</span><span id="__span-3-7"><a id="__codelineno-3-7" name="__codelineno-3-7" href="#__codelineno-3-7"></a>    <span class="n">model</span><span class="o">=</span><span class="n">User</span><span class="p">,</span>
+</span><span id="__span-3-8"><a id="__codelineno-3-8" name="__codelineno-3-8" href="#__codelineno-3-8"></a>    <span class="n">field</span><span class="o">=</span><span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">,</span>
+</span><span id="__span-3-9"><a id="__codelineno-3-9" name="__codelineno-3-9" href="#__codelineno-3-9"></a>    <span class="n">session_dep</span><span class="o">=</span><span class="n">get_db</span><span class="p">,</span>
+</span><span id="__span-3-10"><a id="__codelineno-3-10" name="__codelineno-3-10" href="#__codelineno-3-10"></a>    <span class="n">load_options</span><span class="o">=</span><span class="p">[</span><span class="n">selectinload</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">role</span><span class="p">)],</span>
+</span><span id="__span-3-11"><a id="__codelineno-3-11" name="__codelineno-3-11" href="#__codelineno-3-11"></a><span class="p">)</span>
+</span><span id="__span-3-12"><a id="__codelineno-3-12" name="__codelineno-3-12" href="#__codelineno-3-12"></a>
+</span><span id="__span-3-13"><a id="__codelineno-3-13" name="__codelineno-3-13" href="#__codelineno-3-13"></a><span class="c1"># Or reuse the app&#39;s configured CRUD and its default_load_options</span>
+</span><span id="__span-3-14"><a id="__codelineno-3-14" name="__codelineno-3-14" href="#__codelineno-3-14"></a><span class="n">UserCrud</span> <span class="o">=</span> <span class="n">CrudFactory</span><span class="p">(</span><span class="n">User</span><span class="p">,</span> <span class="n">default_load_options</span><span class="o">=</span><span class="p">[</span><span class="n">selectinload</span><span class="p">(</span><span class="n">User</span><span class="o">.</span><span class="n">role</span><span class="p">)])</span>
+</span><span id="__span-3-15"><a id="__codelineno-3-15" name="__codelineno-3-15" href="#__codelineno-3-15"></a><span class="n">UserDep</span> <span class="o">=</span> <span class="n">PathDependency</span><span class="p">(</span><span class="n">model</span><span class="o">=</span><span class="n">User</span><span class="p">,</span> <span class="n">field</span><span class="o">=</span><span class="n">User</span><span class="o">.</span><span class="n">id</span><span class="p">,</span> <span class="n">session_dep</span><span class="o">=</span><span class="n">get_db</span><span class="p">,</span> <span class="n">crud</span><span class="o">=</span><span class="n">UserCrud</span><span class="p">)</span>
+</span><span id="__span-3-16"><a id="__codelineno-3-16" name="__codelineno-3-16" href="#__codelineno-3-16"></a>
+</span><span id="__span-3-17"><a id="__codelineno-3-17" name="__codelineno-3-17" href="#__codelineno-3-17"></a>
+</span><span id="__span-3-18"><a id="__codelineno-3-18" name="__codelineno-3-18" href="#__codelineno-3-18"></a><span class="nd">@router</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;/users/</span><span class="si">{user_id}</span><span class="s2">&quot;</span><span class="p">)</span>
+</span><span id="__span-3-19"><a id="__codelineno-3-19" name="__codelineno-3-19" href="#__codelineno-3-19"></a><span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">get_user</span><span class="p">(</span><span class="n">user</span><span class="p">:</span> <span class="n">User</span> <span class="o">=</span> <span class="n">UserDep</span><span class="p">):</span>
+</span><span id="__span-3-20"><a id="__codelineno-3-20" name="__codelineno-3-20" href="#__codelineno-3-20"></a>    <span class="k">return</span> <span class="n">user</span><span class="o">.</span><span class="n">role</span><span class="o">.</span><span class="n">name</span>  <span class="c1"># already loaded, no extra query</span>
+</span></code></pre></div>
+<p>Both parameters work the same way on <code>BodyDependency</code>. When given together, the
+usual <a href="../crud/#relationship-loading">relationship loading</a> precedence applies.</p>
 <hr />
 <p><a href="../../reference/dependencies/"><span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M7 7H5a2 2 0 0 0-2 2v8h2v-4h2v4h2V9a2 2 0 0 0-2-2m0 4H5V9h2m7-2h-4v10h2v-4h2a2 2 0 0 0 2-2V9a2 2 0 0 0-2-2m0 4h-2V9h2m6 0v6h1v2h-4v-2h1V9h-1V7h4v2Z"/></svg></span> API Reference</a></p>

@@ -1757,7 +1757,7 @@


 <h2 id="fastapi_toolsets.dependencies.PathDependency" class="doc doc-heading">
-            <code class="highlight language-python"><span class="n">fastapi_toolsets</span><span class="o">.</span><span class="n">dependencies</span><span class="o">.</span><span class="n">PathDependency</span><span class="p">(</span><span class="n">model</span><span class="p">,</span> <span class="n">field</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">session_dep</span><span class="p">,</span> <span class="n">param_name</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span></code>
+            <code class="highlight language-python"><span class="n">fastapi_toolsets</span><span class="o">.</span><span class="n">dependencies</span><span class="o">.</span><span class="n">PathDependency</span><span class="p">(</span><span class="n">model</span><span class="p">,</span> <span class="n">field</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">session_dep</span><span class="p">,</span> <span class="n">param_name</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">crud</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">load_options</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span></code>

 <a href="#fastapi_toolsets.dependencies.PathDependency" class="headerlink" title="Permanent link">&para;</a></h2>

@@ -1842,6 +1842,40 @@
                  <code>None</code>
            </td>
          </tr>
+          <tr class="doc-section-item">
+            <td>
+                <code>crud</code>
+            </td>
+            <td>
+                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#type">type</a>[<a class="autorefs autorefs-internal" title="&lt;code&gt;fastapi_toolsets.crud.factory.AsyncCrud&lt;/code&gt;" href="../crud/#fastapi_toolsets.crud.factory.AsyncCrud">AsyncCrud</a>[<span title="fastapi_toolsets.types.ModelType">ModelType</span>]] | None</code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>Existing CRUD class to fetch with, so its <code>default_load_options</code>
+apply. Defaults to a bare <code>CrudFactory(model)</code>.</p>
+              </div>
+            </td>
+            <td>
+                  <code>None</code>
+            </td>
+          </tr>
+          <tr class="doc-section-item">
+            <td>
+                <code>load_options</code>
+            </td>
+            <td>
+                  <code><a class="autorefs autorefs-external" title="collections.abc.Sequence" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence">Sequence</a>[<span title="sqlalchemy.sql.base.ExecutableOption">ExecutableOption</span>] | None</code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>SQLAlchemy loader options for the fetch. Overrides the CRUD's
+<code>default_load_options</code> entirely rather than merging with them.</p>
+              </div>
+            </td>
+            <td>
+                  <code>None</code>
+            </td>
+          </tr>
      </tbody>
    </table>

@@ -1911,7 +1945,7 @@


 <h2 id="fastapi_toolsets.dependencies.BodyDependency" class="doc doc-heading">
-            <code class="highlight language-python"><span class="n">fastapi_toolsets</span><span class="o">.</span><span class="n">dependencies</span><span class="o">.</span><span class="n">BodyDependency</span><span class="p">(</span><span class="n">model</span><span class="p">,</span> <span class="n">field</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">session_dep</span><span class="p">,</span> <span class="n">body_field</span><span class="p">)</span></code>
+            <code class="highlight language-python"><span class="n">fastapi_toolsets</span><span class="o">.</span><span class="n">dependencies</span><span class="o">.</span><span class="n">BodyDependency</span><span class="p">(</span><span class="n">model</span><span class="p">,</span> <span class="n">field</span><span class="p">,</span> <span class="o">*</span><span class="p">,</span> <span class="n">session_dep</span><span class="p">,</span> <span class="n">body_field</span><span class="p">,</span> <span class="n">crud</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="n">load_options</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span></code>

 <a href="#fastapi_toolsets.dependencies.BodyDependency" class="headerlink" title="Permanent link">&para;</a></h2>

@@ -1996,6 +2030,40 @@
                <em>required</em>
            </td>
          </tr>
+          <tr class="doc-section-item">
+            <td>
+                <code>crud</code>
+            </td>
+            <td>
+                  <code><a class="autorefs autorefs-external" href="https://docs.python.org/3/library/functions.html#type">type</a>[<a class="autorefs autorefs-internal" title="&lt;code&gt;fastapi_toolsets.crud.factory.AsyncCrud&lt;/code&gt;" href="../crud/#fastapi_toolsets.crud.factory.AsyncCrud">AsyncCrud</a>[<span title="fastapi_toolsets.types.ModelType">ModelType</span>]] | None</code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>Existing CRUD class to fetch with, so its <code>default_load_options</code>
+apply. Defaults to a bare <code>CrudFactory(model)</code>.</p>
+              </div>
+            </td>
+            <td>
+                  <code>None</code>
+            </td>
+          </tr>
+          <tr class="doc-section-item">
+            <td>
+                <code>load_options</code>
+            </td>
+            <td>
+                  <code><a class="autorefs autorefs-external" title="collections.abc.Sequence" href="https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence">Sequence</a>[<span title="sqlalchemy.sql.base.ExecutableOption">ExecutableOption</span>] | None</code>
+            </td>
+            <td>
+              <div class="doc-md-description">
+                <p>SQLAlchemy loader options for the fetch. Overrides the CRUD's
+<code>default_load_options</code> entirely rather than merging with them.</p>
+              </div>
+            </td>
+            <td>
+                  <code>None</code>
+            </td>
+          </tr>
      </tbody>
    </table>