Merging

.github/workflows/test.yml

@@ -12,7 +12,6 @@ jobs:
       fail-fast: false
       matrix:
         python-version: ["3.12"]
-        poetry-version: [latest]
         os: [ubuntu-latest]
 
     runs-on: ${{ matrix.os }}
@@ -35,15 +34,16 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - uses: actions/setup-python@v5
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
 
-      - name: Install and configure Poetry
-        uses: snok/install-poetry@v1
-
       - name: Install project
-        run: poetry install
+        run: uv sync --all-extras --dev
 
       - name: Set env variables for pytest
         run: |
@@ -54,6 +54,7 @@ jobs:
           echo "DB_NAME=test_db" >> $GITHUB_ENV
           echo "SECRET_KEY=$(openssl rand -base64 32)" >> $GITHUB_ENV
           echo "BASE_URL=http://localhost:8000" >> $GITHUB_ENV
+          echo "RESEND_API_KEY=resend_api_key" >> $GITHUB_ENV
 
       - name: Verify environment variables
         run: |
@@ -63,10 +64,11 @@ jobs:
           [ -n "$DB_HOST" ] && \
           [ -n "$DB_PORT" ] && \
           [ -n "$DB_NAME" ] && \
-          [ -n "$SECRET_KEY" ]
+          [ -n "$SECRET_KEY" ] && \
+          [ -n "$RESEND_API_KEY" ]
 
       - name: Run type checking with mypy
-        run: poetry run mypy .
+        run: uv run mypy .
 
       - name: Run tests with pytest
-        run: poetry run pytest -s tests/
+        run: uv run pytest tests/

.gitignore

@@ -5,4 +5,5 @@ __pycache__
 /.quarto/
 _docs/
 .pytest_cache/
-.mypy_cache/
+.mypy_cache/
+.cursorrules

README.md

@@ -55,7 +55,7 @@ to deploy to any major cloud hosting platform.
 
 **Additional technologies:**
 
-- [Poetry](https://python-poetry.org/): Python dependency manager
+- [uv](https://docs.astral.sh/uv/): Python dependency manager
 - [Pytest](https://docs.pytest.org/en/7.4.x/): testing framework
 - [Docker](https://www.docker.com/): development containerization
 - [Github Actions](https://docs.github.com/en/actions): CI/CD pipeline
@@ -72,56 +72,73 @@ to deploy to any major cloud hosting platform.
 For comprehensive installation instructions, see the [installation
 page](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/docs/installation.html).
 
-### Python and Docker
+### uv
 
-- [Python 3.12 or higher](https://www.python.org/downloads/)
-- [Docker and Docker Compose](https://docs.docker.com/get-docker/)
+MacOS and Linux:
 
-### PostgreSQL headers
+``` bash
+wget -qO- https://astral.sh/uv/install.sh | sh
+```
 
-For Ubuntu/Debian:
+Windows:
 
 ``` bash
-sudo apt update && sudo apt install -y python3-dev libpq-dev
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
 ```
 
-For macOS:
+See the [uv installation
+docs](https://docs.astral.sh/uv/getting-started/installation/) for more
+information.
+
+### Python
+
+Install Python 3.12 or higher from either the official [downloads
+page](https://www.python.org/downloads/) or using uv:
 
 ``` bash
-brew install postgresql
+# Installs the latest version
+uv python install
 ```
 
-For Windows:
+### Docker and Docker Compose
 
-- No installation required
+Install Docker Desktop and Coker Compose for your operating system by
+following the [instructions in the
+documentation](https://docs.docker.com/compose/install/).
 
-### Python dependencies
+### PostgreSQL headers
 
-1.  Install Poetry
+For Ubuntu/Debian:
 
 ``` bash
-pipx install poetry
+sudo apt update && sudo apt install -y python3-dev libpq-dev
 ```
 
-2.  Install project dependencies
+For macOS:
 
 ``` bash
-poetry install
+brew install postgresql
 ```
 
-3.  Activate shell
+For Windows:
+
+- No installation required
+
+### Python dependencies
+
+From the root directory, run:
 
 ``` bash
-poetry shell
+uv venv
+uv sync
 ```
 
-(Note: You will need to activate the shell every time you open a new
-terminal session. Alternatively, you can use the `poetry run` prefix
-before other commands to run them without activating the shell.)
+This will create an in-project virtual environment and install all
+dependencies.
 
 ### Set environment variables
 
-Copy .env.example to .env with `cp .env.example .env`.
+Copy `.env.example` to `.env` with `cp .env.example .env`.
 
 Generate a 256 bit secret key with `openssl rand -base64 32` and paste
 it into the .env file.
@@ -134,6 +151,9 @@ account, verify a domain, get an API key, and paste the API key into the
 
 ### Start development database
 
+To start the development database, run the following command in your
+terminal from the root directory:
+
 ``` bash
 docker compose up -d
 ```
@@ -155,14 +175,31 @@ Navigate to http://localhost:8000/
 mypy .
 ```
 
-### Contributing
+## Developing with LLMs
+
+In line with the [llms.txt standard](https://llmstxt.org/), we have
+provided a Markdown-formatted prompt—designed to help LLM agents
+understand how to work with this template—as a text file:
+[llms.txt](docs/static/llms.txt).
+
+One use case for this file, if using the Cursor IDE, is to rename it to
+`.cursorrules` and place it in your project directory (see the [Cursor
+docs](https://docs.cursor.com/context/rules-for-ai) on this for more
+information). Alternatively, you could use it as a custom system prompt
+in the web interface for ChatGPT, Claude, or the LLM of your choice.
+
+We have also exposed the full Markdown-formatted project documentation
+as a [single text file](docs/static/documentation.txt) for easy
+downloading and embedding for RAG workflows.
+
+## Contributing
 
 Your contributions are welcome! See the [issues
 page](https://github.com/promptly-technologies-llc/fastapi-jinja2-postgres-webapp/issues)
 for ideas. Fork the repository, create a new branch, make your changes,
 and submit a pull request.
 
-### License
+## License
 
 This project is created and maintained by [Promptly Technologies,
 LLC](https://promptlytechnologies.com/) and licensed under the MIT

docs/architecture.qmd

@@ -59,4 +59,103 @@ dot.render('static/data_flow', format='png', cleanup=True)
 
 ![Data flow diagram](static/data_flow.png)
 
-The advantage of the PRG pattern is that it is very straightforward to implement and keeps most of the rendering logic on the server side. The disadvantage is that it requires an extra round trip to the database to fetch the updated data, and re-rendering the entire page template may be less efficient than a partial page update on the client side.
+The advantage of the PRG pattern is that it is very straightforward to implement and keeps most of the rendering logic on the server side. The disadvantage is that it requires an extra round trip to the database to fetch the updated data, and re-rendering the entire page template may be less efficient than a partial page update on the client side.
+
+## Form validation flow
+
+We've experimented with several approaches to validating form inputs in the FastAPI endpoints.
+
+### Objectives
+
+Ideally, on an invalid input, we would redirect the user back to the form, preserving their inputs and displaying an error message about which input was invalid.
+
+This would keep the error handling consistent with the PRG pattern described in the [Architecture](https://promptlytechnologies.com/fastapi-jinja2-postgres-webapp/docs/architecture) section of this documentation.
+
+To keep the code DRY, we'd also like to handle such validation with Pydantic dependencies, Python exceptions, and exception-handling middleware as much as possible.
+
+### Obstacles
+
+One challenge is that if we redirect back to the page with the form, the page is re-rendered with empty form fields. 
+
+This can be overcome by passing the inputs from the request as context variables to the template. 
+
+But that's a bit clunky, because then we have to support form-specific context variables in every form page and corresponding GET endpoint.
+
+Also, we have to:
+
+1. access the request object (which is not by default available to our middleware), and 
+2. extract the form inputs (at least one of which is invalid in this error case), and 
+3. pass the form inputs to the template (which is a bit challenging to do in a DRY way since there are different sets of form inputs for different forms).
+
+Solving these challenges is possible, but gets high-complexity pretty quickly.
+
+### Approaches
+
+The best solution, I think, is to use really robust client-side form validation to prevent invalid inputs from being sent to the server in the first place. That makes it less important what we do on the server side, although we still need to handle the server-side error case as a backup in the event that something slips past our validation on the client side.
+
+Here are some patterns we've considered for server-side error handling:
+
+<style>
+.styled-table, .styled-table th, .styled-table td {
+  border: 1px solid black;
+  padding: 8px;
+  border-collapse: collapse;
+}
+
+.styled-table th:nth-child(1) { width: 50%; }
+.styled-table th:nth-child(2), 
+.styled-table th:nth-child(3),
+.styled-table th:nth-child(4) { width: 15%; }
+.styled-table th:nth-child(5) { width: 10%; }
+</style>
+
+<table class="styled-table">
+  <thead>
+    <tr>
+      <th>Approach</th>
+      <th>Returns to same page</th>
+      <th>Preserves form inputs</th>
+      <th>Follows PRG pattern</th>
+      <th>Complexity</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Validate with Pydantic dependency, catch and redirect from middleware (with exception message as context) to an error page with "go back" button</td>
+      <td>No</td>
+      <td>Yes</td>
+      <td>Yes</td>
+      <td>Low</td>
+    </tr>
+    <tr>
+      <td>Validate in FastAPI endpoint function body, redirect to origin page with error message query param</td>
+      <td>Yes</td>
+      <td>No</td>
+      <td>Yes</td>
+      <td>Medium</td>
+    </tr>
+    <tr>
+      <td>Validate in FastAPI endpoint function body, redirect to origin page with error message query param and form inputs as context so we can re-render page with original form inputs</td>
+      <td>Yes</td>
+      <td>Yes</td>
+      <td>Yes</td>
+      <td>High</td>
+    </tr>
+    <tr>
+      <td>Validate with Pydantic dependency, use session context to get form inputs from request, redirect to origin page from middleware with exception message and form inputs as context so we can re-render page with original form inputs</td>
+      <td>Yes</td>
+      <td>Yes</td>
+      <td>Yes</td>
+      <td>High</td>
+    </tr>
+    <tr>
+      <td>Validate in either Pydantic dependency or function endpoint body and directly return error message or error toast HTML partial in JSON, then mount error toast with HTMX or some simple layout-level Javascript</td>
+      <td>Yes</td>
+      <td>Yes</td>
+      <td>No</td>
+      <td>Low</td>
+    </tr>
+  </tbody>
+</table>
+
+Presently this template primarily uses option 1 but also supports option 2. Ultimately, I think option 5 will be preferable; support for that [is planned](https://github.com/Promptly-Technologies-LLC/fastapi-jinja2-postgres-webapp/issues/5) for a future update or fork of this template.