formatting

2026-06-19 01:29:05 -05:00
parent 964cd6f76d
commit 3347443ca9
27 changed files with 275 additions and 238 deletions
@@ -22,10 +22,10 @@ Bring an existing Python project into full conformance with cloud-native best pr

 Load these references only when needed:

- FastAPI patterns and app structure: [./references/fastapi-best-practices.md](./references/fastapi-best-practices.md)
- uv project layout and dependency management: [./references/uv-project-layout.md](./references/uv-project-layout.md)
- uvicorn CLI settings reference: [./references/uvicorn-settings.md](./references/uvicorn-settings.md)
- Docker and cloud-native patterns: [./references/docker-cloud-native.md](./references/docker-cloud-native.md)
+- FastAPI patterns and app structure: [FastAPI best practices](./references/fastapi-best-practices.md)
+- uv project layout and dependency management: [uv project layout](./references/uv-project-layout.md)
+- uvicorn CLI settings reference: [uvicorn settings](./references/uvicorn-settings.md)
+- Docker and cloud-native patterns: [Docker cloud-native patterns](./references/docker-cloud-native.md)

 ---

@@ -44,9 +44,9 @@ Before making changes, map the current state across six areas. Produce a short g
 | **Container** | Is there a `Dockerfile`? Multi-stage? Non-root user? `.dockerignore` present? |
 | **Cloud-native** | Is there a `/healthz` endpoint? Graceful shutdown? Structured logs? |

-Load [./references/fastapi-best-practices.md](./references/fastapi-best-practices.md) for structure rules.
-Load [./references/uv-project-layout.md](./references/uv-project-layout.md) for uv migration rules.
-Load [./references/uvicorn-settings.md](./references/uvicorn-settings.md) for uvicorn CLI reference.
+Load the [FastAPI best practices reference](./references/fastapi-best-practices.md) for structure rules.
+Load the [uv project layout reference](./references/uv-project-layout.md) for uv migration rules.
+Load the [uvicorn settings reference](./references/uvicorn-settings.md) for uvicorn CLI reference.

 Completion check: You can name every gap before touching any file.

@@ -145,7 +145,7 @@ Completion check: `uv run python -m my_app` starts the server.

 ### Step 3: Wire the FastAPI App Factory

-Load [./references/fastapi-best-practices.md](./references/fastapi-best-practices.md) for the full patterns. Key rules:
+Load the [FastAPI best practices reference](./references/fastapi-best-practices.md) for the full patterns. Key rules:

 **`src/my_app/main.py`:**

@@ -211,7 +211,7 @@ Completion check: `uv run uvicorn my_app.main:app --reload` starts with no impor

 ### Step 4: uvicorn Production Configuration

-Load [./references/uvicorn-settings.md](./references/uvicorn-settings.md) for the full settings reference.
+Load the [uvicorn settings reference](./references/uvicorn-settings.md) for the full settings reference.

 **Never** configure uvicorn inside application code. Pass all settings via CLI or environment variables (`UVICORN_*` prefix).

@@ -270,7 +270,7 @@ Completion check: `curl http://localhost:8000/healthz` returns `{"status":"ok"}`

 ### Step 5: Write the Dockerfile

-Load [./references/docker-cloud-native.md](./references/docker-cloud-native.md) for the full template and cloud-native rules. Key requirements:
+Load the [Docker cloud-native patterns reference](./references/docker-cloud-native.md) for the full template and cloud-native rules. Key requirements:

 - Multi-stage build: `builder` stage installs deps; `runtime` stage is slim.
 - Pin uv version (copy from official image, not `latest`).
@@ -1,6 +1,10 @@
 # Docker and Cloud-Native Patterns

-Source: https://docs.docker.com/build/building/best-practices/ | https://docs.astral.sh/uv/guides/integration/docker/ | https://fastapi.tiangolo.com/deployment/docker/ | https://uvicorn.dev/deployment/
+!!! info "Primary sources"
+    - [Docker build best practices](https://docs.docker.com/build/building/best-practices/)
+    - [uv Docker integration](https://docs.astral.sh/uv/guides/integration/docker/)
+    - [FastAPI Docker deployment](https://fastapi.tiangolo.com/deployment/docker/)
+    - [uvicorn deployment](https://uvicorn.dev/deployment/)

 ---

@@ -1,6 +1,8 @@
 # FastAPI Best Practices

-Source: https://fastapi.tiangolo.com/deployment/ | https://fastapi.tiangolo.com/advanced/events/
+!!! info "Primary sources"
+    - [FastAPI deployment](https://fastapi.tiangolo.com/deployment/)
+    - [FastAPI lifespan events](https://fastapi.tiangolo.com/advanced/events/)

 ---

@@ -44,7 +46,8 @@ def create_app(settings: Settings | None = None) -> FastAPI:
 app = create_app()
 ```

-**Never use `@app.on_event("startup")` / `@app.on_event("shutdown")`** — these are deprecated. The `asynccontextmanager` lifespan is the canonical approach since FastAPI 0.95.
+!!! warning "Prefer lifespan handlers"
+    Never use `@app.on_event("startup")` / `@app.on_event("shutdown")`. These are deprecated. The `asynccontextmanager` lifespan is the canonical approach since FastAPI 0.95.

 ---

@@ -1,6 +1,9 @@
 # uv Project Layout and Dependency Management

-Source: https://docs.astral.sh/uv/guides/projects/ | https://docs.astral.sh/uv/concepts/projects/layout/ | https://docs.astral.sh/uv/guides/integration/docker/
+!!! info "Primary sources"
+    - [uv project guide](https://docs.astral.sh/uv/guides/projects/)
+    - [uv project layout](https://docs.astral.sh/uv/concepts/projects/layout/)
+    - [uv Docker integration](https://docs.astral.sh/uv/guides/integration/docker/)

 ---

@@ -13,7 +16,8 @@ Source: https://docs.astral.sh/uv/guides/projects/ | https://docs.astral.sh/uv/c
 | `.python-version` | Default Python version for the project | Yes |
 | `.venv/` | Local virtual environment | No (`.gitignore`) |

-**`uv.lock` must be committed.** It is the source of truth for reproducible installs in CI and Docker. Never edit it by hand.
+!!! warning "Commit the lockfile"
+    `uv.lock` must be committed. It is the source of truth for reproducible installs in CI and Docker. Never edit it by hand.

 ---

@@ -1,6 +1,8 @@
 # uvicorn Settings Reference

-Source: https://uvicorn.dev/settings/ | https://uvicorn.dev/deployment/
+!!! info "Primary sources"
+    - [uvicorn settings](https://uvicorn.dev/settings/)
+    - [uvicorn deployment](https://uvicorn.dev/deployment/)

 ---

@@ -21,7 +23,8 @@ uvicorn main:app
 uvicorn.run("main:app", host="0.0.0.0", port=8000)
 ```

-**Note:** `UVICORN_*` env vars cannot be used from within an `--env-file`. The `--env-file` flag is for the ASGI *application's* config, not uvicorn's own config.
+!!! note "Environment file scope"
+    `UVICORN_*` env vars cannot be used from within an `--env-file`. The `--env-file` flag is for the ASGI *application's* config, not uvicorn's own config.

 ---