07: Resource listing.

Author: pauleveritt

docs/building/index.md

@@ -32,4 +32,5 @@ playwright
 first_pyscript
 bulma
 examples_template
+resource_listing
 ```

docs/building/resource_listing.md

@@ -0,0 +1,67 @@
+# Resource Listing
+
+Our navigation needs to list the available examples.
+Equally, we need a cleaner way to extract the data from an example.
+In this step, we make "resource" objects for various models: page, example, contributor.
+We'll leave page and contributor for the next step.
+
+Big ideas: A standard model helps us with all the representations of an example.
+
+## What's an Example?
+
+We'll start with, of course, tests.
+This time in `test_resources`.
+Let's write `test_example` and see if we can correctly construct an instance.
+It will need all the bits the template relies on.
+
+Our resource implementation will use dataclasses, with a base `Resource`.
+We'll use `__post_init__` to fill in the bits by opening the file.
+Also, as "keys", we'll use a `PurePath` scheme to name/id each example.
+
+To help testing and to keep `__post_init__` dead-simple, we move most of the logic to easily-testable helpers.
+
+## Gathering the Resources
+
+We'll make a "resource dB" available at startup with the examples.
+For now, we'll do a `Resources` dataclass with an examples field as `dict[PurePath, Example]`.
+Later, we'll add fields for pages and contributors.
+
+First a test, of course, to see if `get_resources` returns a `Resources.examples` with `PurePath("hello_world")` mapping to an `Example`.
+
+We then write the `resources.get_resources` function that generates a populated `Resources`.
+
+## Listing Examples
+
+Now that we have the listing of examples, we head back to `app.py` and put it to work.
+We'll use Starlette's "lifespan" support to:
+
+- Register a startup function which...
+- Runs `get_resources` and...
+- Assigns to `app.state.resources`
+
+We'll then change the `example` view to get the resource from `request.app.state.resources`.
+
+When we do this, though, `TestClient` breaks.
+It doesn't ordinarily run the lifecycle methods.
+Instead, we need to use the [context manager](https://www.starlette.io/events/#running-event-handlers-in-tests).
+We do this, and along the way, refactor the tests to inject the test_client.
+In fact, we also make a `get_soup` fixture that further eases test writing.
+
+We then add a `/examples` view, starting with a test of course.
+This uses an `examples.jinja2` template.
+We wire this up into the navbar and have the test ensure that it is there via navbar.
+
+The listings use a [Bulma tile 3 column](https://bulma.io/documentation/layout/tiles/#3-columns) layout.
+Lots that can be done here.
+
+## Cleanup
+
+- Arrange for `/example/hello_world` and `/example/hello_world/index.html` to both resolve
+- Fix the silly BeautifulSoup "allow str or List[str]" in upstream so tests don't have to cast all the time
+- Get a "subtitle" from `/examples/hello_world/index.html` and a `<meta name="subtitle" content="...">` tag
+- Don't extract `<main>` itself from the example, as we want to control it in the layout...just the children
+
+## Future
+
+- Have the rows in the tiles be yielded by a generator, allowing multi-column title
+- Include contributor information at bottom of each tile

src/psc/app.py

@@ -1,8 +1,9 @@
 """Provide a web server to browse the examples."""
-from http.client import HTTPException
-from pathlib import Path
+import contextlib
+from pathlib import PurePath
+from typing import AsyncContextManager
+from typing import Iterator
 
-from bs4 import BeautifulSoup
 from starlette.applications import Starlette
 from starlette.requests import Request
 from starlette.responses import FileResponse
@@ -12,12 +13,14 @@
 from starlette.templating import Jinja2Templates
 from starlette.templating import _TemplateResponse
 
+from psc.here import HERE
 from psc.here import PYODIDE
 from psc.here import PYSCRIPT
-from psc.here import STATIC
+from psc.resources import Example
+from psc.resources import Resources
+from psc.resources import get_resources
 
 
-HERE = Path(__file__).parent
 templates = Jinja2Templates(directory=HERE / "templates")
 
 
@@ -40,53 +43,34 @@ async def homepage(request: Request) -> _TemplateResponse:
     )
 
 
+async def examples(request: Request) -> _TemplateResponse:
+    """Handle the examples listing page."""
+    these_examples: Iterator[Example] = request.app.state.resources.examples.values()
+
+    return templates.TemplateResponse(
+        "examples.jinja2",
+        dict(
+            title="Examples",
+            examples=these_examples,
+            request=request,
+        ),
+    )
+
+
 async def example(request: Request) -> _TemplateResponse:
     """Handle an example page."""
-    example_name = request.path_params["example_name"]
-    example_file = HERE / "examples" / example_name / "index.html"
-    example_content = example_file.read_text()
-    soup = BeautifulSoup(example_content, "html5lib")
-
-    # Get the example title from the HTML file
-    title_node = soup.select_one("title")
-    title = title_node.text if title_node else ""
-
-    # Assemble any extra head
-    extra_head_links = [
-        link.prettify()
-        for link in soup.select("head link")
-        if not link.attrs["href"].endswith("pyscript.css")
-        and not link.attrs["href"].endswith("favicon.png")
-    ]
-    extra_head_scripts = [
-        script.prettify()
-        for script in soup.select("head script")
-        if not script.attrs["src"].endswith("pyscript.js")
-    ]
-    extra_head_nodes = extra_head_links + extra_head_scripts
-    extra_head = "\n".join(extra_head_nodes)
-
-    # Assemble the main element
-    main_element = soup.select_one("main")
-    if main_element is None:
-        raise HTTPException("Example file has no <main> element")
-    main = f"<main>{main_element.decode_contents()}</main>"
-
-    # Get any non-py-config PyScript nodes
-    pyscript_nodes = [
-        pyscript.prettify()
-        for pyscript in soup.select("body > *")
-        if pyscript.name.startswith("py-") and pyscript.name != "py-config"
-    ]
-    extra_pyscript = "\n".join(pyscript_nodes)
+    example_path = PurePath(request.path_params["example_name"])
+    resources: Resources = request.app.state.resources
+    this_example = resources.examples[example_path]
 
     return templates.TemplateResponse(
         "example.jinja2",
         dict(
-            title=title,
-            extra_head=extra_head,
-            main=main,
-            extra_pyscript=extra_pyscript,
+            title=this_example.title,
+            subtitle=this_example.subtitle,
+            extra_head=this_example.extra_head,
+            main=this_example.main,
+            extra_pyscript=this_example.extra_pyscript,
             request=request,
         ),
     )
@@ -96,11 +80,26 @@ async def example(request: Request) -> _TemplateResponse:
     Route("/", homepage),
     Route("/index.html", homepage),
     Route("/favicon.png", favicon),
+    Route("/examples/index.html", examples),
+    Route("/examples", examples),
     Route("/examples/{example_name}/index.html", example),
+    Route("/examples/{example_name}/", example),
     Mount("/examples", StaticFiles(directory=HERE / "examples")),
-    Mount("/static", StaticFiles(directory=STATIC)),
+    Mount("/static", StaticFiles(directory=HERE / "static")),
     Mount("/pyscript", StaticFiles(directory=PYSCRIPT)),
     Mount("/pyodide", StaticFiles(directory=PYODIDE)),
 ]
 
-app = Starlette(debug=True, routes=routes)
+
+@contextlib.asynccontextmanager  # type: ignore
+async def lifespan(a: Starlette) -> AsyncContextManager:  # type: ignore
+    """Run the resources factory at startup and make available to views."""
+    a.state.resources = get_resources()
+    yield
+
+
+app = Starlette(
+    debug=True,
+    routes=routes,
+    lifespan=lifespan,
+)

src/psc/examples/hello_world/index.html

@@ -10,10 +10,10 @@
     <meta name="viewport" content="width=device-width,initial-scale=1">
 
     <title>Hello World</title>
+    <meta name="subtitle" content="The classic hello world, but in Python -- in a browser!" >
 
     <link rel="icon" type="image/png" href="../../favicon.png">
-    <link rel="stylesheet" href="../../static/pyscript.css">
-    <script defer src="../../static/pyscript.js"></script>
+    <script defer src="../../pyscript/pyscript.js"></script>
     <link rel="stylesheet" href="hello_world.css">
     <script defer src="hello_world.js"></script>
   </head>

src/psc/examples/hello_world/index.md

@@ -0,0 +1 @@
+This is the *hello world* example.

src/psc/fixtures.py

@@ -5,6 +5,7 @@
 from dataclasses import field
 from mimetypes import guess_type
 from typing import Callable
+from typing import Generator
 from urllib.parse import urlparse
 
 import pytest
@@ -45,18 +46,17 @@ def get(self, url: str) -> Response:
 
 
 @pytest.fixture
-def test_client() -> TestClient:
-    """Get a TestClient for the app."""
-    return TestClient(app)
+def test_client() -> Generator[TestClient, None, None]:
+    """Return the app in a context manager to allow lifecyle to run."""
+    with TestClient(app) as client:
+        yield client
 
 
 def _base_page(client: TestClient | MockTestClient) -> PageT:
     """Automate ``TestClient`` to return BeautifulSoup.
 
-    Along the way, default to raising an exception if the status
-    code isn't 200.
+    Default to raising an exception if the status code isn't 200.
     """
-    # Allow passing in a fake TestClient, for testing this fixture.
 
     def _page(url: str, *, enforce_status: bool = True) -> BeautifulSoup:
         """Callable that retrieves and returns soup."""