Merge pull request #25 from volfpeter/feat/url-for-support

Feat: url_for() support

Author: volfpeter

.gitignore

@@ -21,3 +21,5 @@ uv.lock
 # Build
 
 dist/
+
+dev/

docs/file-system-based-routing.md

@@ -88,3 +88,17 @@ In the example, `my_app/navbar.py` is not a special file, so it is not routable.
 For any `page.py` file, you can also define a `handle_submit` function. This automatically creates a `POST` route at the same URL as the page. This is a convenient pattern for handling HTML form submissions that modify data.
 
 If `my_app/users/page.py` defines a `handle_submit` function, it will handle `POST /users` requests, and the `page` function in the same file will handle `GET /users` requests as usual.
+
+## Constructing URLs
+
+FastAPI provides two ways for constructing valid URLs for registered routes: `FastAPI.url_path_for()` and `Request.url_for()`. Both of these methods expect the path operation's name, and the route's path parameters (if any) as keyword arguments.
+
+To let you use these built-in FastAPI utilities, `holm` automatically assigns a name to every page route it registers. The name assignment logic is very simple: the name (import path) of the corresponding `page.py` module.
+
+Here are some examples:
+
+- `app.url_path_for("my_app.page")`: `/`
+- `app.url_path_for("my_app.users.page")`: `/users/`
+- `app.url_path_for("my_app.users._user_id_.page", user_id=1)`: `/users/1/`
+
+Submit handlers are also assigned a name: the name of the corresponding page's name, followed by the `.handle_submit` suffix. Since the only difference between pages and submit handlers is the used HTTP method, the URL for a submit handler is the same as the URL for the corresponding page.

holm/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.4.0"
+__version__ = "0.4.1"
 
 from .app import App as App
 from .fastapi import FastAPIDependency as FastAPIDependency

holm/app.py

@@ -103,7 +103,8 @@ def _build_api(
             api.get(
                 "/",
                 response_model=None,
-                name="page",
+                # mypy can't infer that the modules is not None.
+                name=page_module.__name__,  # type: ignore[union-attr]
                 description=page_dep.__doc__,
                 tags=["Page"],
             )(htmy.page(components_with_metadata)(path_operation))
@@ -119,7 +120,8 @@ def _build_api(
             api.post(
                 "/",
                 response_model=None,
-                name="submit",
+                # mypy can't infer that the modules is not None.
+                name=f"{page_module.__name__}.handle_submit",  # type: ignore[union-attr]
                 description=submit_handler_dep.__doc__,
                 tags=["Page", "Submit"],
             )(htmy.page(components_with_metadata)(path_operation))

holm/modules/_page.py

@@ -17,7 +17,17 @@ class PageDefinition(Protocol):
     """Protocol definition for objects (usually modules) that define a page."""
 
     @property
-    def page(self) -> Page: ...
+    def __name__(self) -> str:
+        """
+        Page definitions are expected to have a `__name__` attribute,
+        since they are modules.
+        """
+        ...
+
+    @property
+    def page(self) -> Page:
+        """The page implementation."""
+        ...
 
 
 def is_page_definition(obj: Any) -> TypeGuard[PageDefinition]:

test_app/api.py

@@ -0,0 +1,14 @@
+from fastapi import APIRouter, Request
+
+api = APIRouter()
+
+
+@api.get("/urls")
+def list_urls(request: Request) -> list[str]:
+    """Lists some urls to demonstrate `request.url_for()` usage."""
+    return [
+        str(request.url_for("test_app.page")),
+        str(request.url_for("test_app.calculator.page")),
+        str(request.url_for("test_app.user.page")),
+        str(request.url_for("test_app.user._id_.page", id="1")),
+    ]

tests/test_url_for.py

@@ -0,0 +1,56 @@
+from typing import Any
+
+import pytest
+from fastapi.testclient import TestClient
+
+import test_app.calculator.page as calculator_page
+import test_app.page as test_app_page
+import test_app.user._id_.page as user_by_id_page
+import test_app.user.page as user_page
+from test_app.main import app
+
+
+@pytest.mark.parametrize(
+    ("path_name", "url", "path_params"),
+    (
+        ("test_app.page", "/", {}),
+        (test_app_page.__name__, "/", {}),
+        ("test_app.calculator.page", "/calculator/", {}),
+        (calculator_page.__name__, "/calculator/", {}),
+        ("test_app.user.page", "/user/", {}),
+        (user_page.__name__, "/user/", {}),
+        ("test_app.user._id_.page", "/user/1/", {"id": 1}),
+        (user_by_id_page.__name__, "/user/1/", {"id": 1}),
+        ("test_app.user._id_.page", "/user/C0FF33/", {"id": "C0FF33"}),
+        (user_by_id_page.__name__, "/user/C0FF33/", {"id": "C0FF33"}),
+    ),
+)
+def test_app_url_path_for_page(path_name: str, url: str, path_params: dict[str, Any]) -> None:
+    """
+    Tests that `app.url_path_for()` can construct URLs for pages
+    based on page module name (import path).
+    """
+    assert app.url_path_for(path_name, **path_params) == url
+
+
+@pytest.mark.parametrize(
+    ("path_name", "url"),
+    (("test_app.calculator.page.handle_submit", "/calculator/"),),
+)
+def test_app_url_path_for_handle_submit(path_name: str, url: str) -> None:
+    """
+    Tests that `app.url_path_for()` can construct URLs for submit handlers
+    based on page module name (import path) with the `.handle_submit` suffix.
+    """
+    assert app.url_path_for(path_name) == url
+
+
+def test_request_url_for(client: TestClient) -> None:
+    response = client.get("/urls")
+    assert response.status_code == 200
+    assert response.json() == [
+        "http://testserver/",
+        "http://testserver/calculator/",
+        "http://testserver/user/",
+        "http://testserver/user/1/",
+    ]