[codex] add framework component quickstarts - #161
Merged
Conversation
lbliii
changed the title
There was a problem hiding this comment.
Pull request overview
This PR makes Kida’s optional framework adapters (Flask/Django/Starlette/FastAPI) a first-class, CI-exercised onboarding path by adding current-version integration quickstarts, runnable examples, and contract tests—while keeping Kida’s runtime dependency set empty.
Changes:
- Added dev-only framework dependency locks plus adapter contract tests (including “imports without optional frameworks” coverage).
- Added runnable, smoke-tested framework examples (Flask/Django/FastAPI) demonstrating typed components + full-page + fragment rendering with XSS-escaping assertions.
- Replaced/reshaped integration docs into “ten-minute” framework-first quickstarts and updated tutorial landing/README references to match the real adapter APIs.
Reviewed changes
Copilot reviewed 26 out of 27 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
uv.lock |
Locks new dev-only framework dependencies (Flask/Django/FastAPI/Starlette/Uvicorn/etc.) for CI compatibility coverage. |
pyproject.toml |
Adds optional framework packages to the dev dependency group (explicitly dev-only). |
README.md |
Updates integration snippets to the current contrib API names (init_kida, KidaTemplates, KidaTemplates backend). |
tests/test_examples.py |
Adds subprocess smoke tests for framework examples without starting servers. |
tests/test_docs_install_snippets.py |
Adds a contract test to keep framework quickstarts consistent (Python 3.14 floor + uv install + migration link + fragment path). |
tests/contrib/test_framework_adapters.py |
New contract tests for contrib adapters (import boundary, Flask helper wiring, Django backend behavior, Starlette response/metadata contract). |
src/kida/contrib/__init__.py |
Fixes stale contrib package docs to reference real adapter entry points (no re-exports). |
src/kida/contrib/flask.py |
Updates documentation to reflect “does not replace Flask’s Jinja env” positioning. |
src/kida/contrib/starlette.py |
Clarifies TemplateResponse() is synchronous and documents the async/streaming path. |
site/content/docs/tutorials/_index.md |
Reorders Tutorials landing to lead with framework quickstarts. |
site/content/docs/tutorials/flask-integration.md |
Replaces stale integration doc with a 10-minute typed-component + fragment quickstart. |
site/content/docs/tutorials/django-integration.md |
Replaces stale integration doc with a 10-minute backend + fragment quickstart. |
site/content/docs/tutorials/starlette-integration.md |
Replaces stale Starlette/FastAPI doc with a FastAPI-first quickstart + Starlette notes + async/streaming guidance. |
examples/README.md |
Lists the new runnable framework examples and updates install/run snippets to uv. |
examples/flask_components/app.py |
New runnable Flask example with --smoke path + XSS escaping assertion + fragment rendering. |
examples/flask_components/README.md |
Run/smoke instructions for the Flask example. |
examples/flask_components/templates/components.html |
Typed component template used by the Flask example (form + preview fragment). |
examples/django_components/app.py |
New runnable Django example with --smoke path + fragment rendering + XSS escaping assertion. |
examples/django_components/README.md |
Run/smoke instructions for the Django example. |
examples/django_components/templates/components.html |
Typed component template used by the Django example. |
examples/fastapi_components/app.py |
New runnable FastAPI example with ASGI-client smoke path + fragment rendering + XSS escaping assertion. |
examples/fastapi_components/README.md |
Run/smoke instructions for the FastAPI example. |
examples/fastapi_components/templates/components.html |
Typed component template used by the FastAPI example. |
examples/fastapi_async/app.py |
Updates the “not installed” message to uv add ... wording. |
examples/fastapi_async/README.md |
Updates install/test commands to use uv and clarifies Python 3.14+. |
examples/fastapi_async/test_fastapi_async.py |
Switches example tests to HTTPX ASGI transport + async pytest style. |
changelog.d/156.added.md |
Changelog entry for the new guides and smoke-tested examples. |
Comment on lines
+79
to
+87
| example_dir = EXAMPLES_DIR / example | ||
| result = subprocess.run( | ||
| [sys.executable, "app.py", "--smoke"], | ||
| cwd=example_dir, | ||
| capture_output=True, | ||
| text=True, | ||
| timeout=30, | ||
| check=False, | ||
| ) |
Comment on lines
8
to
12
| import importlib | ||
| import subprocess | ||
| import sys | ||
| from pathlib import Path | ||
|
|
Comment on lines
+46
to
+52
| result = subprocess.run( | ||
| [sys.executable, "-c", script], | ||
| capture_output=True, | ||
| text=True, | ||
| timeout=30, | ||
| check=False, | ||
| ) |
Comment on lines
+9
to
+13
| import subprocess | ||
| import sys | ||
| from pathlib import Path | ||
| from types import ModuleType, SimpleNamespace | ||
| from typing import TYPE_CHECKING, cast |
Comment on lines
305
to
+308
| ```python | ||
| # Flask | ||
| from kida.contrib.flask import KidaFlask | ||
| kida = KidaFlask(app) | ||
| from kida.contrib.flask import init_kida, render_template | ||
| kida_env = init_kida(app) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
uv add, form + fragment, and prominent Jinja2{% set %}scoping migration linkWhy
The adapter APIs already shipped, but their docs advertised stale names, current framework releases were not exercised in CI, and users had to assemble component and fragment patterns themselves. These changes make the existing-framework path a tested first-class entry point.
Impact
Kida's runtime contract remains dependency-free:
[project].dependencies = []. Flask, Django, FastAPI, Starlette, HTTPX, and Uvicorn are locked only in the development group for compatibility tests and examples. No adapter signature or render behavior changes.Contract parity
init_kida,render_template,render_blockdefrender,backend.env.render_blockdefTemplateResponse,render_blockdefValidation
make lintmake format-checkmake tyPYTHON_GIL=0make docscompleted; Bengal reported the existing 23 internal-link health findings across 8 unrelated pagesmake package-smokepassed for wheel and sdistuv lock --check --offlinedependencies = []Steward Notes
Closes #137.
Closes #156.