You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<li><code>set_up_database</code>: Sets up the test database before running the test suite by dropping all tables and recreating them to ensure a clean state.</li>
237
237
<li><code>session</code>: Provides a session for database operations in tests.</li>
238
238
<li><code>clean_db</code>: Cleans up the database tables before each test by deleting all entries in the <code>PasswordResetToken</code> and <code>User</code> tables.</li>
239
-
<li><code>client</code>: Provides a <code>TestClient</code> instance with the session fixture, overriding the <code>get_session</code> dependency to use the test session.</li>
239
+
<li><code>auth_client</code>: Provides a <code>TestClient</code> instance with access and refresh token cookies set, overriding the <code>get_session</code> dependency to use the <code>session</code> fixture.</li>
240
+
<li><code>unauth_client</code>: Provides a <code>TestClient</code> instance without authentication cookies set, overriding the <code>get_session</code> dependency to use the <code>session</code> fixture.</li>
240
241
<li><code>test_user</code>: Creates a test user in the database with a predefined name, email, and hashed password.</li>
<h3class="anchored" data-anchor-id="type-checking-with-mypy">Type checking with mypy</h3>
252
253
<p>The project uses type annotations and mypy for static type checking. To run mypy, use this command from the root directory:</p>
253
-
<divclass="sourceCode" id="cb1"><preclass="sourceCode bash code-with-copy"><codeclass="sourceCode bash"><spanid="cb1-1"><ahref="#cb1-1" aria-hidden="true" tabindex="-1"></a><spanclass="ex">mypy</span></span></code><buttontitle="Copy to Clipboard" class="code-copy-button"><iclass="bi"></i></button></pre></div>
254
-
<p>We find that mypy is an enormous time-saver, catching many errors early and greatly reducing time spent debugging unit tests. However, note that mypy requires you type annotate every variable, function, and method in your code base, so taking advantage of it is a lifestyle change!</p>
<p>We find that mypy is an enormous time-saver, catching many errors early and greatly reducing time spent debugging unit tests. However, note that mypy requires you type annotate every variable, function, and method in your code base, so taking advantage of it requires a lifestyle change!</p>
255
256
</section>
256
257
<sectionid="developing-with-llms" class="level3">
257
258
<h3class="anchored" data-anchor-id="developing-with-llms">Developing with LLMs</h3>
258
-
<p>In line with the <ahref="https://llmstxt.org/">llms.txt standard</a>, we have exposed the full Markdown-formatted project documentation as a <ahref="https://promptlytechnologies.com/docs/static/llms.txt">single text file</a> to make it more usable by LLM agents.</p>
259
+
<p>In line with the <ahref="https://llmstxt.org/">llms.txt standard</a>, we have provided a Markdown-formatted prompt—designed to help LLM agents understand how to work with this template—as a <ahref="https://promptlytechnologies.com/docs/static/llms.txt">text file</a>. One use case for this file is to rename it to <code>.cursorrules</code> and place it in your project directory is using the Cursor IDE (see the <ahref="https://docs.cursor.com/context/rules-for-ai">Cursor docs</a> on this for more information).</p>
260
+
<p>We have also exposed the full Markdown-formatted project documentation as a <ahref="https://promptlytechnologies.com/docs/static/documentation.txt">single text file</a> for easy downloading and embedding.</p>
<p>We also create POST endpoints, which accept form submissions so the user can create, update, and delete data in the database. This template follows the Post-Redirect-Get (PRG) pattern to handle POST requests. When a form is submitted, the server processes the data and then returns a “redirect” response, which sends the user to a GET endpoint to re-render the page with the updated data. (See <ahref="https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/docs/architecture.html">Architecture</a> for more details.)</p>
<h4class="anchored" data-anchor-id="routing-patterns-in-this-template">Routing patterns in this template</h4>
301
-
<p>In this template, GET routes are defined in the main entry point for the application, <code>main.py</code>. POST routes are organized into separate modules within the <code>routers/</code> directory. We name our GET routes using the convention <code>read_<name></code>, where <code><name></code> is the name of the page, to indicate that they are read-only endpoints that do not modify the database.</p>
303
+
<p>In this template, GET routes are defined in the main entry point for the application, <code>main.py</code>. POST routes are organized into separate modules within the <code>routers/</code> directory.</p>
304
+
<p>We name our GET routes using the convention <code>read_<name></code>, where <code><name></code> is the name of the page, to indicate that they are read-only endpoints that do not modify the database.</p>
302
305
<p>We divide our GET routes into authenticated and unauthenticated routes, using commented section headers in our code that look like this:</p>
<p>Some of our routes take request parameters, which we pass as keyword arguments to the route handler. These parameters should be type annotated for validation purposes. Some parameters are shared across all authenticated or unauthenticated routes, so we define them in the <code>common_authenticated_parameters</code> and <code>common_unauthenticated_parameters</code> dependencies defined in <code>main.py</code>.</p>
307
+
<p>Some of our routes take request parameters, which we pass as keyword arguments to the route handler. These parameters should be type annotated for validation purposes.</p>
308
+
<p>Some parameters are shared across all authenticated or unauthenticated routes, so we define them in the <code>common_authenticated_parameters</code> and <code>common_unauthenticated_parameters</code> dependencies defined in <code>main.py</code>.</p>
<spanid="cb3-6"><ahref="#cb3-6" aria-hidden="true" tabindex="-1"></a> )</span></code><buttontitle="Copy to Clipboard" class="code-copy-button"><iclass="bi"></i></button></pre></div>
320
-
<p>In this example, the <code>welcome.html</code> template will receive two pieces of context: the user’s <code>request</code>, which is always passed automatically by FastAPI, and a <code>username</code> variable, which we specify as “Alice”. We can then use the <code>{ username }</code> syntax in the <code>welcome.html</code> template (or any of its parent or child templates) to insert the value into the HTML.</p>
324
+
<p>In this example, the <code>welcome.html</code> template will receive two pieces of context: the user’s <code>request</code>, which is always passed automatically by FastAPI, and a <code>username</code> variable, which we specify as “Alice”. We can then use the <code>{{ username }}</code> syntax in the <code>welcome.html</code> template (or any of its parent or child templates) to insert the value into the HTML.</p>
<p>Cascade deletes (in which deleting a record from one table deletes related records from another table) can be handled at either the ORM level or the database level. This template handles cascade deletes at the ORM level, via SQLModel relationships. Inside a SQLModel <code>Relationship</code>, we set:</p>
<spanid="cb9-3"><ahref="#cb9-3" aria-hidden="true" tabindex="-1"></a>}</span></code><buttontitle="Copy to Clipboard" class="code-copy-button"><iclass="bi"></i></button></pre></div>
454
+
<p>This tells SQLAlchemy to cascade all operations (e.g., <code>SELECT</code>, <code>INSERT</code>, <code>UPDATE</code>, <code>DELETE</code>) to the related table. Since this happens through the ORM, we need to be careful to do all our database operations through the ORM using supported syntax. That generally means loading database records into Python objects and then deleting those objects rather than deleting records in the database directly.</p>
455
+
<p>For example,</p>
456
+
<divclass="sourceCode" id="cb10"><preclass="sourceCode python code-with-copy"><codeclass="sourceCode python"><spanid="cb10-1"><ahref="#cb10-1" aria-hidden="true" tabindex="-1"></a>session.<spanclass="bu">exec</span>(delete(Role))</span></code><buttontitle="Copy to Clipboard" class="code-copy-button"><iclass="bi"></i></button></pre></div>
457
+
<p>will not trigger the cascade delete. Instead, we need to select the role objects and then delete them:</p>
458
+
<divclass="sourceCode" id="cb11"><preclass="sourceCode python code-with-copy"><codeclass="sourceCode python"><spanid="cb11-1"><ahref="#cb11-1" aria-hidden="true" tabindex="-1"></a><spanclass="cf">for</span> role <spanclass="kw">in</span> session.<spanclass="bu">exec</span>(select(Role)).<spanclass="bu">all</span>():</span>
459
+
<spanid="cb11-2"><ahref="#cb11-2" aria-hidden="true" tabindex="-1"></a> session.delete(role)</span></code><buttontitle="Copy to Clipboard" class="code-copy-button"><iclass="bi"></i></button></pre></div>
460
+
<p>This is slower than deleting the records directly, but it makes <ahref="https://sqlmodel.tiangolo.com/tutorial/many-to-many/create-models-with-link/#create-the-tables">many-to-many relationships</a> much easier to manage.</p>
<spanid="cb1-9"><ahref="#cb1-9" aria-hidden="true" tabindex="-1"></a><spanclass="fu">}</span></span></code><buttontitle="Copy to Clipboard" class="code-copy-button"><iclass="bi"></i></button></pre></div>
229
229
<p>Simply create a <code>.devcontainer</code> folder in the root of the project and add a <code>devcontainer.json</code> file in the folder with the above content. VSCode may prompt you to install the Dev Container extension if you haven’t already, and/or to open the project in a container. If not, you can manually select “Dev Containers: Reopen in Container” from View > Command Palette.</p>
230
+
<p><em>IMPORTANT: If using this dev container configuration, you will need to set the <code>DB_HOST</code> environment variable to “host.docker.internal” in the <code>.env</code> file.</em></p>
<p>Generate a 256 bit secret key with <code>openssl rand -base64 32</code> and paste it into the .env file.</p>
291
292
<p>Set your desired database name, username, and password in the .env file.</p>
292
293
<p>To use password recovery, register a <ahref="https://resend.com/">Resend</a> account, verify a domain, get an API key, and paste the API key into the .env file.</p>
294
+
<p>If using the dev container configuration, you will need to set the <code>DB_HOST</code> environment variable to “host.docker.internal” in the .env file. Otherwise, set <code>DB_HOST</code> to “localhost” for local development. (In production, <code>DB_HOST</code> will be set to the hostname of the database server.)</p>
<h2class="anchored" data-anchor-id="start-development-database">Start development database</h2>
298
+
<p>To start the development database, run the following command in your terminal from the root directory:</p>
296
299
<divclass="sourceCode" id="cb9"><preclass="sourceCode bash code-with-copy"><codeclass="sourceCode bash"><spanid="cb9-1"><ahref="#cb9-1" aria-hidden="true" tabindex="-1"></a><spanclass="ex">docker</span> compose up <spanclass="at">-d</span></span></code><buttontitle="Copy to Clipboard" class="code-copy-button"><iclass="bi"></i></button></pre></div>
300
+
<p>If at any point you change the environment variables in the .env file, you will need to stop the database service <em>and tear down the volume</em>:</p>
301
+
<divclass="sourceCode" id="cb10"><preclass="sourceCode bash code-with-copy"><codeclass="sourceCode bash"><spanid="cb10-1"><ahref="#cb10-1" aria-hidden="true" tabindex="-1"></a><spanclass="co"># Don't forget the -v flag to tear down the volume!</span></span>
302
+
<spanid="cb10-2"><ahref="#cb10-2" aria-hidden="true" tabindex="-1"></a><spanclass="ex">docker</span> compose down <spanclass="at">-v</span></span></code><buttontitle="Copy to Clipboard" class="code-copy-button"><iclass="bi"></i></button></pre></div>
303
+
<p>You may also need to restart the terminal session to pick up the new environment variables. You can also add the <code>--force-recreate</code> and <code>--build</code> flags to the startup command to ensure the container is rebuilt:</p>
304
+
<divclass="sourceCode" id="cb11"><preclass="sourceCode bash code-with-copy"><codeclass="sourceCode bash"><spanid="cb11-1"><ahref="#cb11-1" aria-hidden="true" tabindex="-1"></a><spanclass="ex">docker</span> compose up <spanclass="at">-d</span><spanclass="at">--force-recreate</span><spanclass="at">--build</span></span></code><buttontitle="Copy to Clipboard" class="code-copy-button"><iclass="bi"></i></button></pre></div>
<p>Before running the development server, make sure the development database is running and tables and default permissions/roles are created first. Then run the following command in your terminal from the root directory:</p>
0 commit comments