Use Pydantic to model API requests/responses

.dockerignore

@@ -6,3 +6,9 @@
 
 # Omit Python cache files.
 __pycache__/
+
+# Ignore pytest cache files.
+.pytest_cache/
+
+# Ignore ruff cache files.
+.ruff_cache/

.github/workflows/ci.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Check formatting
         run: uv run ruff format --check -- src/
 
-      - name: Linting
+      - name: Lint
         run: uv run ruff check -- src/
 
       # Note: This spins up containers running the default services.
@@ -47,8 +47,8 @@ jobs:
       - name: Spin up Docker Compose stack in background
         run: docker compose up --detach
 
-      # Note: The `--exit-code-from test` option applies the exit code of the `test` container
-      #       to the `docker compose` process, so that the GHA step fails if tests fail.
+      # Note: The `--exit-code-from test` option applies the exit code of the `ingest` container
+      #       to the `docker compose` process, so that the GHA step fails if ingest fails.
       #       Reference: https://docs.docker.com/reference/cli/docker/compose/up/
       - name: Spin up `test` container
         run: docker compose up --exit-code-from test test

.gitignore

@@ -22,3 +22,12 @@ __pycache__
 
 # Top-level environment configuration file.
 /.env
+
+# Ignore pytest cache files.
+/.pytest_cache/
+
+# Ignore ruff cache files.
+/.ruff_cache/
+
+# Ignore Vite files.
+/.vite/

CONTRIBUTING.md

@@ -68,6 +68,7 @@ to make sure the Python virtual environment has the updated dependencies.
 
 ## Spin up container-based development environment
 
+### Start the server
 This repository includes a container-based development environment. If you have Docker installed, you can spin up that development environment by running:
 
 ```sh
@@ -76,4 +77,45 @@ docker compose up --detach
 
 Once that's up and running, you can access the API at: http://localhost:8000
 
-Also, you can access the MongoDB server at: `localhost:27017` (its admin credentials are in `docker-compose.yml`)
+Also, you can access the MongoDB server at: `localhost:27017` (its admin credentials are in `docker-compose.yml`)
+
+### Run Ingest
+To populate the database with data run
+```sh
+docker compose run --volume /path/to/data:/data --rm ingest \
+    uv run --active \
+        python /app/mongodb/ingest_data.py \
+        --mongo-uri "mongodb://${MONGO_USERNAME}:${MONGO_PASSWORD}@${MONGO_HOST}:${MONGO_PORT}" \
+        --input /data --clean
+```
+(See `docker-compose.yml` for details)
+
+Or if you want to use data in tests/data simply use:
+```sh
+docker compose up ingest
+```
+
+### Run Tests
+
+Run the tests:
+
+```sh
+docker compose up test
+```
+
+<details>
+<summary>Show/hide FAQ about the ingest script's role in testing</summary>
+
+Note: The test suite includes a fixture, named `seeded_db`, that will invoke the ingest script automatically before each test that specifies that fixture as a dependency.
+
+```py
+def test_foo(seeded_db):
+    # The ingest script will be invoked automatically before this test runs.
+    pass
+
+def test_foo()
+    # The ingest script will _not_ be invoked automatically before this test runs.
+    pass
+```
+
+</details>

Dockerfile

@@ -43,4 +43,19 @@ COPY . /app
 
 # Run the FastAPI development server on port 8000, accepting HTTP requests from any host.
 # Reference: https://fastapi.tiangolo.com/deployment/manually/
-CMD [ "uv", "run", "fastapi", "dev", "--host", "0.0.0.0", "/app/src/server.py" ]
+CMD [ "uv", "run", "fastapi", "dev", "--host", "0.0.0.0", "/app/src/server.py" ]
+
+# ────────────────────────────────────────────────────────────────────────────┐
+FROM development AS test
+# ────────────────────────────────────────────────────────────────────────────┘
+
+# Create a local virtual environment directory 
+# This is necessary for keeping the test environment isolated from
+# running server environment in /app/.venv
+RUN mkdir -p /app_venv
+ENV VIRTUAL_ENV="/app_venv"
+
+# This target inherits from development and is used for running tests
+# No additional setup needed as development already has dev dependencies
+# --active flag ensures that the local virtual environment is used
+CMD [ "uv", "run", "--active", "pytest", "-v" ]