Merge pull request #35 from volfpeter/feat/use-hyphens-in-urls

volfpeter · web-flow · commit 33cf63d3daba · 2025-11-10T10:50:59.000+01:00
Replace underscores with hyphens in routes by default, except in path parameters
diff --git a/docs/application-components.md b/docs/application-components.md
@@ -57,7 +57,7 @@ Rules for *actions*:
 
 - An action must be a FastAPI dependency, just like a page.
 - Actions can be registered with any HTTP method (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`), using the appropriate `@action` decorator.
-- You can specify a custom URL path for an action (e.g., `@action.post("/do-something")`), but it is optional. If no path is provided, the function's name is used as the path. In both cases, the path is relative to the URL corresponding to the package that contains the action.
+- You can specify a custom URL path for an action (e.g., `@action.post("/do-something")`), but it is optional. If no path is provided, the function's name is used as the path, with underscores (`_`) being replaced by hyphens (`-`). In both cases, the path is relative to the URL corresponding to the package that contains the action.
 - By default, components returned from actions are not wrapped in layouts. This is ideal for returning HTML fragments for client frameworks like HTMX.
 - To render an action's return value in its owner layouts (like it is done by default for pages), you can set `use_layout=True` in the decorator: `@action.get(use_layout=True)`. This behavior can of course be combined with the [`without_layout` utility](utilities.md#without_layout).
 - Actions can also have `metadata`: `@action.get(metadata={"title": "Hello"})`. `metadata` works identically to page metadata and is particularly useful when combined with `use_layout`.
diff --git a/docs/file-system-based-routing.md b/docs/file-system-based-routing.md
@@ -9,6 +9,7 @@ Going through the [Application components](application-components.md) documentat
 ## Core concepts
 
 - Packages define URL segments: Each Python package within your application's root maps to a URL segment. Nesting directories creates nested routes. For example, the `my_app/users/` package will create routes under the `/users` URL path.
+- Underscores (`_`) are replaced with hyphens (`-`) in paths by default, unless a path segment corresponds to a path parameter, in which case the underscore is preserved.
 - Special files mark application components: `holm` looks for specific filenames within your application directory to discover application components and compose your application.
   - `page.py`: Creates a publicly accessible URL for a route segment.
   - `layout.py`: Defines a shared UI that wraps a route segment and its children.
@@ -63,7 +64,7 @@ An `actions.py` file offers a dedicated place to define actions, which are flexi
 Actions are declared using the `@action` decorators (for example `@action.post()`). Their paths are always prefixed with the package's URL path.
 
 - An action in `my_app/users/actions.py` (or `my_app/users/page.py`) decorated with `@action.post("/enable")` creates a route that handles `POST /users/enable` requests.
-- If no path is specified in the decorator, the action function's name is used. Decorating a `def disable(): ...` function without setting a path would create a route at `/users/disable`.
+- If no path is specified in the decorator, the action function's name is used with underscores (`_`) being replaced by hyphens (`-`). Decorating a `def deactivate_user(): ...` function without setting a path would create a route at `/users/deactivate-user`.
 
 ### APIs
 
diff --git a/docs/guides/actions-with-htmx.md b/docs/guides/actions-with-htmx.md
@@ -74,7 +74,7 @@ Note: `holm` applies file-system based routing to both pages and actions! If bot
 
 The action we create will be very simple, just a `welcome_message() -> str` function that returns a welcome message in a randomly chosen language. The returned message is just a string (which happens to be a `htmy` `Component`), which `holm` automatically renders into an HTML response.
 
-The `welcome_message()` function is registered as an action using the `@action.get()` decorator. Since we don't pass a path to it, it will be registered under `/welcome_message`.
+The `welcome_message()` function is registered as an action using the `@action.get()` decorator. Since we don't pass a path to it and underscores (`_`) are replaced with hyphens (`-`) by default, it will be registered under `/welcome-message`.
 
 ```python hl_lines="15-16"
 import random
@@ -136,7 +136,7 @@ def page() -> Component:
     return html.div(
         html.h1(
             "Welcome to My App",
-            hx_get="/welcome_message",
+            hx_get="/welcome-message",
             hx_trigger="every 2s",
         ),
         html.p("This is a minimal holm application demonstrating:"),
diff --git a/examples/actions-with-htmx/page.py b/examples/actions-with-htmx/page.py
@@ -9,7 +9,7 @@ def page() -> Component:
     return html.div(
         html.h1(
             "Welcome to My App",
-            hx_get="/welcome_message",
+            hx_get="/welcome-message",
             hx_trigger="every 2s",
         ),
         html.p("This is a minimal holm application demonstrating:"),
diff --git a/holm/__init__.py b/holm/__init__.py
@@ -1,4 +1,4 @@
-__version__ = "0.6.0"
+__version__ = "0.7.0"
 
 from .app import App as App
 from .fastapi import FastAPIDependency as FastAPIDependency
diff --git a/holm/_model.py b/holm/_model.py
@@ -172,7 +172,14 @@ def from_marker_file(cls, file_path: Path, *, config: AppConfig) -> PackageInfo:
         # That option is to use the `_name_` pattern instead and convert such package/directory
         # names to the `{name}` format here and use that as the URL segment.
         url = "/".join(
-            (f"{{{p[1:-1]}}}" if len(p) > 2 and p[0] == p[-1] == "_" else p for p in url.split("/"))
+            (
+                f"{{{p[1:-1]}}}"
+                if len(p) > 2 and p[0] == p[-1] == "_"
+                else p.replace(
+                    "_", "-"
+                )  # Replace underscores with hyphens if the given part is not a path parameter.
+                for p in url.split("/")
+            )
         )
         return cls(package_dir=package_dir, package_name=package_name, url=url)
 
diff --git a/holm/module_options/_actions.py b/holm/module_options/_actions.py
@@ -354,7 +354,7 @@ def _register_action(
             setattr(module, _actions_variable, module_actions)
 
         if path is None:
-            path = f"/{action_name}"
+            path = f"/{action_name.replace('_', '-')}"
 
         route_args["name"] = f"{action_module}.{action_name}"
         # Use the Action tag if no tags were set by the user.
diff --git a/test_app/api.py b/test_app/api.py
@@ -10,5 +10,5 @@ def list_urls(request: Request) -> list[str]:
         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")),
+        str(request.url_for("test_app.user._user_id_.page", user_id="1")),
     ]
diff --git a/test_app/user/_id_/layout.py b/test_app/user/_id_/layout.py
diff --git a/test_app/user/_user_id_/__init__.py b/test_app/user/_user_id_/__init__.py
diff --git a/test_app/user/_user_id_/api.py b/test_app/user/_user_id_/api.py
@@ -14,8 +14,8 @@ def api(htmy: HTMY) -> APIRouter:
         # and with the plain JSON payload to non-HTMX ones.
         user_card,
     )
-    async def get_user(id: str) -> dict[str, str]:
-        return {"id": id, "name": "John"}
+    async def get_user(user_id: str) -> dict[str, str]:
+        return {"id": user_id, "name": "John"}
 
     # Don't forget to return the API.
 
diff --git a/test_app/user/_user_id_/layout.py b/test_app/user/_user_id_/layout.py
@@ -0,0 +1,5 @@
+from htmy import ComponentType, html
+
+
+def layout(props: ComponentType, user_id: str) -> dict[str, ComponentType]:
+    return {"main": props, "footer": html.div(html.p(f"footer for user ID {user_id}, added by layout"))}
diff --git a/test_app/user/_user_id_/page.py b/test_app/user/_user_id_/page.py
@@ -3,23 +3,23 @@
 from htmy import Component, Context, html
 
 
-async def metadata(id: str) -> dict[str, str]:
+async def metadata(user_id: str) -> dict[str, str]:
     return {
-        "title": f"User {id}",
+        "title": f"User {user_id}",
     }
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
 class page:
     """The generated `__init__()` method can be used as a FastAPI dependency."""
 
-    id: str
+    user_id: str
     page_variant: str = "default"
 
     async def htmy(self, _: Context) -> Component:
         return html.div(
-            html.h1(f"User {self.id}"),
-            html.p(f"This is the user page for {self.id}."),
+            html.h1(f"User {self.user_id}"),
+            html.p(f"This is the user page for {self.user_id}."),
             html.p(f"Requested page variant is {self.page_variant}."),
         )
 
diff --git a/tests/no_metadata/test_page.py b/tests/no_metadata/test_page.py
@@ -7,7 +7,7 @@
 
 
 def test_page(client: TestClient) -> None:
-    response = client.get("/no_metadata")
+    response = client.get("/no-metadata")
     assert response.status_code == 200
     assert response.headers["Content-Type"] == "text/html; charset=utf-8"
     assert response.text == rendered_page
diff --git a/tests/plain_response/test_page.py b/tests/plain_response/test_page.py
@@ -2,7 +2,7 @@
 
 
 def test_page(client: TestClient) -> None:
-    response = client.get("/plain_response?a=4&b=6")
+    response = client.get("/plain-response?a=4&b=6")
     assert response.status_code == 200
     assert response.headers["Content-Type"] == "application/json"
     assert response.json() == {"add": {"a": 4, "b": 6}, "result": 10}
diff --git a/tests/test_url_for.py b/tests/test_url_for.py
@@ -5,7 +5,7 @@
 
 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._user_id_.page as user_by_id_page
 import test_app.user.page as user_page
 from test_app.main import app
 
@@ -19,10 +19,10 @@
         (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"}),
+        ("test_app.user._user_id_.page", "/user/1/", {"user_id": 1}),
+        (user_by_id_page.__name__, "/user/1/", {"user_id": 1}),
+        ("test_app.user._user_id_.page", "/user/C0FF33/", {"user_id": "C0FF33"}),
+        (user_by_id_page.__name__, "/user/C0FF33/", {"user_id": "C0FF33"}),
     ),
 )
 def test_app_url_path_for_page(path_name: str, url: str, path_params: dict[str, Any]) -> None:
diff --git a/tests/user/_user_id_/__init__.py b/tests/user/_user_id_/__init__.py
diff --git a/tests/user/_user_id_/test_api.py b/tests/user/_user_id_/test_api.py
diff --git a/tests/user/_user_id_/test_page.py b/tests/user/_user_id_/test_page.py
@@ -1,6 +1,6 @@
 from fastapi.testclient import TestClient
 
-from test_app.user._id_.page import rendered_page_dense_layout_grid_eric
+from test_app.user._user_id_.page import rendered_page_dense_layout_grid_eric
 
 
 def test_page(client: TestClient) -> None:
diff --git a/tests/user/test_page.py b/tests/user/test_page.py
@@ -15,12 +15,12 @@ def test_page(client: TestClient) -> None:
     ("action_path", "method", "expected"),
     [
         # -- Automatic action path generation from function name.
-        ("/list_users", "GET", RenderedAction.list_users),
-        ("/create_user", "POST", RenderedAction.create_user),
-        ("/update_user_with_put", "PUT", RenderedAction.update_user_with_put),
-        ("/update_user_with_patch", "PATCH", RenderedAction.update_user_with_patch),
-        ("/delete_user", "DELETE", RenderedAction.delete_user),
-        # -- Custom path support.
+        ("/list-users", "GET", RenderedAction.list_users),
+        ("/create-user", "POST", RenderedAction.create_user),
+        ("/update-user-with-put", "PUT", RenderedAction.update_user_with_put),
+        ("/update-user-with-patch", "PATCH", RenderedAction.update_user_with_patch),
+        ("/delete-user", "DELETE", RenderedAction.delete_user),
+        # -- Custom path support. No underscore replacement.
         ("/a/list_users", "GET", RenderedAction.list_users),
         ("/a/create_user", "POST", RenderedAction.create_user),
         ("/a/update_user_with_put", "PUT", RenderedAction.update_user_with_put),
diff --git a/tests/without_layout/test_pages.py b/tests/without_layout/test_pages.py
@@ -13,45 +13,45 @@
     (
         # -- No inner layout.
         (
-            "without_layout/inner?no_inner_layout=true",
+            "without-layout/inner?no_inner_layout=true",
             "GET",
             RenderedPage.no_inner_layout,
         ),
         (
-            "without_layout/inner?no_inner_layout=true",
+            "without-layout/inner?no_inner_layout=true",
             "POST",
             RenderedHandleSubmit.no_inner_layout,
         ),
         # -- No mix and match, only the innermost without_layout declaration counts.
         (
-            "without_layout/inner?no_middle_layout=false&no_inner_layout=true",
+            "without-layout/inner?no_middle_layout=false&no_inner_layout=true",
             "GET",
             RenderedPage.no_inner_layout,
         ),
         (
-            "without_layout/inner?no_middle_layout=false&no_inner_layout=true",
+            "without-layout/inner?no_middle_layout=false&no_inner_layout=true",
             "POST",
             RenderedHandleSubmit.no_inner_layout,
         ),
         # -- No middle layout.
         (
-            "without_layout/inner?no_middle_layout=true",
+            "without-layout/inner?no_middle_layout=true",
             "GET",
             RenderedPage.no_middle_layout,
         ),
         (
-            "without_layout/inner?no_middle_layout=true",
+            "without-layout/inner?no_middle_layout=true",
             "POST",
             RenderedHandleSubmit.no_middle_layout,
         ),
         # -- No root layout.
         (
-            "without_layout/inner?no_root_layout=true",
+            "without-layout/inner?no_root_layout=true",
             "GET",
             RenderedPage.no_root_layout,
         ),
         (
-            "without_layout/inner?no_root_layout=true",
+            "without-layout/inner?no_root_layout=true",
             "POST",
             RenderedHandleSubmit.no_root_layout,
         ),

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-__version__ = "0.6.0"`
	`1`	`+__version__ = "0.7.0"`
`2`	`2`
`3`	`3`	`from .app import App as App`
`4`	`4`	`from .fastapi import FastAPIDependency as FastAPIDependency`
Original file line number	Diff line number	Diff line change
`@@ -10,5 +10,5 @@ def list_urls(request: Request) -> list[str]:`
`10`	`10`	`str(request.url_for("test_app.page")),`
`11`	`11`	`str(request.url_for("test_app.calculator.page")),`
`12`	`12`	`str(request.url_for("test_app.user.page")),`
`13`		`- str(request.url_for("test_app.user._id_.page", id="1")),`
	`13`	`+ str(request.url_for("test_app.user._user_id_.page", user_id="1")),`
`14`	`14`	`]`