✨ sqlite search, docs, license, deployment, and final cleanup

.dockerignore

@@ -0,0 +1,6 @@
+**/__pycache__
+**/venv
+**/.*
+**/Dockerfile*
+LICENSE
+README.md

.github/workflows/lint.yaml

@@ -0,0 +1,21 @@
+name: Lint
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+
+      - run: make install-dev
+
+      - run: make lint

.gitignore

@@ -1,3 +1,5 @@
 venv
 /static/*.min.js
 .env
+.env.*
+*.sqlite

Dockerfile

@@ -0,0 +1,34 @@
+# syntax=docker/dockerfile:1
+
+FROM python:3.12.2-slim as base
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+RUN apt update && \
+    apt install -y make && \
+    apt clean && \
+    rm -rf /var/lib/apt/lists/*
+
+RUN adduser \
+    --disabled-password \
+    --gecos "" \
+    --home "/nonexistent" \
+    --shell "/sbin/nologin" \
+    --no-create-home \
+    --uid "10001" \
+    appuser
+
+RUN --mount=type=cache,target=/root/.cache/pip \
+    --mount=type=bind,source=requirements.txt,target=requirements.txt \
+    python -m pip install -r requirements.txt
+
+USER appuser
+
+COPY . .
+
+EXPOSE 8000
+
+CMD make start

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Francisco Marques (tofran)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,57 @@
+# Python FastAPI HTMX full-text-search demo
+
+This project is a **demo** full-text-search application that compares the results from
+[SQLite FT5](https://www.sqlite.org/fts5.html) and 
+[Algolia Search platform](https://www.algolia.com/).
+
+Conceived as an experimental venture, this project serves as a demonstration of an *unconventional*
+monolith tech stack. It features an interactive front-end, using a mix of traditional
+Server Side Rendering (SSR) declarative web framework with zero custom JS:
+
+- [FastAPI](https://fastapi.tiangolo.com/) the server framework;
+- [Jinja](https://jinja.palletsprojects.com/) for the SSR templating;
+- [HTMX](https://htmx.org/) to enable front-end interactivity declaratively directly in the HTML.
+
+## Description and demo
+
+**[Live demo](https://full-text-search-demo.tofran.com/)**
+
+https://github.com/tofran/fastapi-htmx-full-text-search-demo/assets/5692603/43d642fd-52d5-4e5b-836a-6609d0c3d782
+
+The outcome of this project is something very simple and minimal. The served content is **tiny** and
+**fast**. There's no initial loading, everything is pre-rendered on the server, and each API request
+renders HTML that is injected into the DOM - no need for Hydration, Resumability nor even data
+serialization. It is compatible with most browsers, all the way back to IE11, where it struggles a
+little with style, but *works*.
+
+![OpenAPI spec (swagger)](https://github.com/tofran/fastapi-htmx-full-text-search-demo/assets/5692603/541f1f1a-fe1d-475c-8723-8f5a13e8f0df)
+
+The application works by serving a full rendered Jinja HTML template when the user navigates to a
+Front-End route.
+These templates are composed via smaller reusable templates (using `include`).
+And then the templates (*components*) are also served, de-coupled from the whole page in the
+*HTML API* (`/html-api/...`).
+HTMX handles the rest, listens to DOM events and updates it when when necessary.
+
+![Example HTML API request/response](https://github.com/tofran/fastapi-htmx-full-text-search-demo/assets/5692603/8e1aa2a0-53dd-443a-a1d2-caee11cad65c)
+
+## Development
+
+- Create a `.env` file based on the `.env.template`.  
+  You will need an Algolia account, should be pretty simple to setup
+  (more info in their [Quick start guide](https://www.algolia.com/doc/guides/getting-started/quick-start/)).
+
+- Setup a local environment with `make setup-venv`,
+  activate it with `source ./venv/bin/activate`
+  (or with your favourite tool).
+
+- Install dependencies: `make install-dev`.
+
+- Start the development server: `make dev`.
+
+## Deployment
+
+For deployment one would use the `./Dockerfile` and set the required environment variables.
+
+For running locally a production like build, install the dependencies with `make install`
+and run the application with `make start`. That's it.

requirements-dev.txt

@@ -1,2 +1,2 @@
-pyright==1.1.355
+pyright==1.1.356
 ruff==0.3.4

static/style.css

@@ -62,6 +62,7 @@ ol {
 
 form {
     margin-bottom: 1rem;
+    line-height: 3rem;
 }
 
 input[type="text"] {
@@ -83,11 +84,6 @@ input[type="text"]:focus {
     border: 1px solid #555;
 }
 
-.algolia-logo {
-    width: 20px;
-    vertical-align: baseline;
-}
-
 label {
     color: #E0E0E0;
     margin-right: 10px;
@@ -99,7 +95,7 @@ select {
     border: none;
     padding: 10px;
     border-radius: var(--border-radius);
-    min-width: min(20rem, calc(100% - var(--padding-body)));
+    /* min-width: min(20rem, calc(100% - var(--padding-body))); */
     border: 1px solid transparent;
 }
 

templates/index.jinja.html

@@ -6,21 +6,38 @@ <h1>Text search example</h1>
 
     <form
         hx-get="/html-api/items"
-        hx-params="search_query"
+        hx-params="search_query, search_index"
         hx-target="#search-results-container"
-        hx-trigger="keyup delay:800ms"
-        >
-        <input type="text" name="search_query" placeholder="Search...">
+        hx-trigger="
+            keyup delay:800ms from:input queue:last changed,
+            change from:select queue:last,
+            submit
+        "
+    >
+        <input
+            type="text"
+            name="search_query"
+            placeholder="Search..."
+            value="{{ search_query }}"
+        />
 
-        <!-- TODO: add more search providers -->
-        <!-- <label for="index">Search with:</label>
-        <select id="index" name="index">
-            <option value="algolia">Algolia</option>
-            <option value="sqlite">SQLite</option>
-        </select> -->
+        <label for="search-index-select">Search with:</label>
+        <select
+            id="search-index-select"
+            name="search_index"
+            hx-trigger="change"
+        >
+            {% for index in search_indexes %}
+                <option
+                    value="{{ index.name }}"
+                    {% if index.is_selected %}selected{% endif %}
+                >
+                    {{ index.name }}
+                </option>
+            {% endfor %}
+        </select>
     </form>
 
-
     <div id="search-results-container">
         {% include "results.jinja.html" %}
     </div>

text_search_app/app.py

@@ -1,23 +1,43 @@
+from contextlib import asynccontextmanager
+
 from fastapi import FastAPI
 from fastapi.requests import Request
 from fastapi.staticfiles import StaticFiles
 from starlette.exceptions import HTTPException as StarletteHTTPException
 
-from text_search_app.config import DEVELOPMENT_MODE
-from text_search_app.routers import html_api_router, index_management_router, page_router
+from text_search_app.config import DEVELOPMENT_MODE, ENABLE_INDEX_MANAGEMENT
+from text_search_app.routers import (
+    html_api_router,
+    index_management_router,
+    misc_router,
+    page_router,
+)
+from text_search_app.search_indexes import sqlite_index
 from text_search_app.templates import make_template_response
 
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    sqlite_index.setup_db()
+    yield
+
+
 app = FastAPI(
-    title="Search sample",
+    title="Python FastAPI HTMX full-text-search demo",
     debug=DEVELOPMENT_MODE,
     openapi_url="/openapi.json" if DEVELOPMENT_MODE else None,
+    lifespan=lifespan,
 )
 
 
 app.include_router(page_router.router)
-app.include_router(index_management_router.router)
 app.include_router(html_api_router.router)
 
+if ENABLE_INDEX_MANAGEMENT:
+    app.include_router(index_management_router.router)
+
+app.include_router(misc_router.router)
+
 
 app.mount(
     path="/static",

text_search_app/config.py

@@ -5,8 +5,21 @@
 
 load_dotenv()
 
-DEVELOPMENT_MODE = getenv("DEVELOPMENT_MODE", "false").lower() == "true"
+
+def get_bool_env(name: str, default: bool) -> bool:
+    return getenv(name, str(default)).lower() == "true"
+
+
+DEVELOPMENT_MODE = get_bool_env("DEVELOPMENT_MODE", False)
+ENABLE_INDEX_MANAGEMENT = get_bool_env("ENABLE_INDEX_MANAGEMENT", True)
+PREVENT_HTML_API_DIRECT_ACCESS = get_bool_env(
+    "PREVENT_HTML_API_DIRECT_ACCESS", not DEVELOPMENT_MODE
+)
 
 ALGOLIA_APP_ID = os.environ["ALGOLIA_APP_ID"]
 ALGOLIA_API_KEY = os.environ["ALGOLIA_API_KEY"]
 ALGOLIA_INDEX_NAME = os.environ["ALGOLIA_INDEX_NAME"]
+
+SQLITE_DATABASE_PATH = "products.sqlite"
+
+RESULTS_PAGE_SIZE = 8

text_search_app/logging.py

@@ -4,7 +4,7 @@
 
 logging.basicConfig(
     level=logging.INFO,
-    format="[%(asctime)s] [%(levelname)s] %(pathname)s:%(lineno)d | %(message)s",
+    format="[%(asctime)s] [%(levelname)s] %(message)s (%(pathname)s:%(lineno)d)",
 )
 
 logger = logging.getLogger(text_search_app.__name__)

text_search_app/models.py

@@ -1,4 +1,4 @@
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, field_validator
 
 
 class Product(BaseModel):
@@ -7,8 +7,8 @@ class Product(BaseModel):
     description: str
     price: float
     currency: str
-    terms: str
-    section: str
+    terms: str | None
+    section: str | None
 
     @field_validator("price", mode="before")
     def transform_str_to_float(
@@ -19,9 +19,3 @@ def transform_str_to_float(
             return float(value.replace(",", "."))
 
         return value
-
-
-class AlgoliaSearchResult(Product):
-    object_id: str = Field(
-        alias="objectId",
-    )