fasthx 2.3.2__tar.gz → 3.0.0__tar.gz

{fasthx-2.3.2 → fasthx-3.0.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Peter Volf
+Copyright (c) 2024-2025 Peter Volf
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{fasthx-2.3.2 → fasthx-3.0.0}/PKG-INFO

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: fasthx
-Version: 2.3.2
+Version: 3.0.0
 Summary: FastAPI server-side rendering with built-in HTMX support.
 License: MIT
+License-File: LICENSE
 Author: Peter Volf
 Author-email: do.volfp@gmail.com
 Requires-Python: >=3.10,<4.0
@@ -12,10 +13,11 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: htmy
 Provides-Extra: jinja
 Requires-Dist: fastapi (>=0.100.0)
-Requires-Dist: htmy (>=0.5.0) ; extra == "htmy"
+Requires-Dist: htmy[lxml] (>=0.8.1) ; extra == "htmy"
 Requires-Dist: jinja2 (>=3.0.0,<4.0.0) ; extra == "jinja"
 Description-Content-Type: text/markdown
 
@@ -43,6 +45,14 @@ FastAPI server-side rendering with built-in HTMX support.
 - **Correct typing** makes it possible to apply other (typed) decorators to your routes.
 - Works with both **sync** and **async routes**.
 
+## Testimonials
+
+"Thank you for your work on `fasthx`, as well as `htmy`! I've never had an easier time developing with another stack." ([ref](https://github.com/volfpeter/fasthx/discussions/77))
+
+"One of the main parts of the `FastAPI` -> `fasthx` -> `htmy` integration I'm falling in love with is its explicitness, and not too much magic happening." ([ref](https://github.com/volfpeter/fasthx/issues/54))
+
+"Thank you for your work on `htmy` and `fasthx`, both have been very pleasant to use, and the APIs are both intuitive and simple. Great work." ([ref](https://github.com/volfpeter/fasthx/issues/54))
+
 ## Support
 
 Consider supporting the development and maintenance of the project through [sponsoring](https://buymeacoffee.com/volfpeter), or reach out for [consulting](https://www.volfp.com/contact?subject=Consulting%20-%20FastHX) so you can get the most out of the library.
@@ -62,10 +72,9 @@ The package has optional dependencies for the following **official integrations*
 
 ## Core concepts
 
-The core concept of FastHX is to let FastAPI routes do their usual job of handling the business logic and returning the result, while the FastHX decorators take care
-of the entire rendering / presentation layer using a declarative, decorator-based approach.
+The core concept of FastHX is to let FastAPI routes do their usual job of handling the business logic and returning the result, while the FastHX decorators take care of the entire rendering and presentation layer using a declarative, decorator-based approach.
 
-Interally, FastHX decorators always have access to the decorated route's result, all of its arguments (sometimes called the request context), and the current request. Integrations convert these values into data that can be consumed by the used rendering engine (for example `htmy` or `jinja`), run the rendering engine with the selected component (more on this below) and the created data, and return the result to the client. For more details on how data conversion works and how it can be customized, please see the API documentation of the rendering engine integration of your choice.
+Internally, FastHX decorators always have access to the decorated route's result, all of its arguments (sometimes called the request context), and the current request. Integrations convert these values into data that can be consumed by the used rendering engine (for example `htmy` or `jinja`), run the rendering engine with the selected component (more on this below) and the created data, and return the result to the client. For more details on how data conversion works and how it can be customized, please see the API documentation of the rendering engine integration of your choice.
 
 The `ComponentSelector` abstraction makes it possible to declaratively specify and dynamically select the component that should be used to render the response to a given request. It is also possible to define an "error" `ComponentSelector` that is used if the decorated route raises an exception -- a typical use-case being error rendering for incorrect user input.
 
@@ -119,12 +128,12 @@ def index() -> None: ...
 
 Requires: `pip install fasthx[jinja]`.
 
-To start serving HTML and HTMX requests, all you need to do is create an instance of `fasthx.Jinja` and use its `hx()` or `page()` methods as decorators on your routes. `hx()` only triggers HTML rendering for HTMX requests, while `page()` unconditionally renders HTML. See the example code below:
+To start serving HTML and HTMX requests, all you need to do is create an instance of `fasthx.jinja.Jinja` and use its `hx()` or `page()` methods as decorators on your routes. `hx()` only triggers HTML rendering for HTMX requests, while `page()` unconditionally renders HTML. See the example code below:
 
 ```python
 from fastapi import FastAPI
 from fastapi.templating import Jinja2Templates
-from fasthx import Jinja
+from fasthx.jinja import Jinja
 from pydantic import BaseModel
 
 # Pydantic model of the data the example API is using.
@@ -166,7 +175,7 @@ See the full working example [here](https://github.com/volfpeter/fasthx/tree/mai
 
 Requires: `pip install fasthx`.
 
-If you would like to use a rendering engine without FastHX integration, you can easily build on the `hx()` and `page()` decorators which give you all the functionality you will need. All you need to do is implement the `HTMLRenderer` protocol.
+If you would like to use a rendering engine without FastHX integration, you can easily build on the `hx()` and `page()` decorators which give you all the functionality you will need. All you need to do is implement the `RenderFunction` protocol.
 
 Similarly to the Jinja case, `hx()` only triggers HTML rendering for HTMX requests, while `page()` unconditionally renders HTML. See the example code below:
 
@@ -179,7 +188,7 @@ from fasthx import hx, page
 # Create the app.
 app = FastAPI()
 
-# Create a dependecy to see that its return value is available in the render function.
+# Create a dependency to see that its return value is available in the render function.
 def get_random_number() -> int:
     return 4  # Chosen by fair dice roll.
 

{fasthx-2.3.2 → fasthx-3.0.0}/README.md

@@ -22,6 +22,14 @@ FastAPI server-side rendering with built-in HTMX support.
 - **Correct typing** makes it possible to apply other (typed) decorators to your routes.
 - Works with both **sync** and **async routes**.
 
+## Testimonials
+
+"Thank you for your work on `fasthx`, as well as `htmy`! I've never had an easier time developing with another stack." ([ref](https://github.com/volfpeter/fasthx/discussions/77))
+
+"One of the main parts of the `FastAPI` -> `fasthx` -> `htmy` integration I'm falling in love with is its explicitness, and not too much magic happening." ([ref](https://github.com/volfpeter/fasthx/issues/54))
+
+"Thank you for your work on `htmy` and `fasthx`, both have been very pleasant to use, and the APIs are both intuitive and simple. Great work." ([ref](https://github.com/volfpeter/fasthx/issues/54))
+
 ## Support
 
 Consider supporting the development and maintenance of the project through [sponsoring](https://buymeacoffee.com/volfpeter), or reach out for [consulting](https://www.volfp.com/contact?subject=Consulting%20-%20FastHX) so you can get the most out of the library.
@@ -41,10 +49,9 @@ The package has optional dependencies for the following **official integrations*
 
 ## Core concepts
 
-The core concept of FastHX is to let FastAPI routes do their usual job of handling the business logic and returning the result, while the FastHX decorators take care
-of the entire rendering / presentation layer using a declarative, decorator-based approach.
+The core concept of FastHX is to let FastAPI routes do their usual job of handling the business logic and returning the result, while the FastHX decorators take care of the entire rendering and presentation layer using a declarative, decorator-based approach.
 
-Interally, FastHX decorators always have access to the decorated route's result, all of its arguments (sometimes called the request context), and the current request. Integrations convert these values into data that can be consumed by the used rendering engine (for example `htmy` or `jinja`), run the rendering engine with the selected component (more on this below) and the created data, and return the result to the client. For more details on how data conversion works and how it can be customized, please see the API documentation of the rendering engine integration of your choice.
+Internally, FastHX decorators always have access to the decorated route's result, all of its arguments (sometimes called the request context), and the current request. Integrations convert these values into data that can be consumed by the used rendering engine (for example `htmy` or `jinja`), run the rendering engine with the selected component (more on this below) and the created data, and return the result to the client. For more details on how data conversion works and how it can be customized, please see the API documentation of the rendering engine integration of your choice.
 
 The `ComponentSelector` abstraction makes it possible to declaratively specify and dynamically select the component that should be used to render the response to a given request. It is also possible to define an "error" `ComponentSelector` that is used if the decorated route raises an exception -- a typical use-case being error rendering for incorrect user input.
 
@@ -98,12 +105,12 @@ def index() -> None: ...
 
 Requires: `pip install fasthx[jinja]`.
 
-To start serving HTML and HTMX requests, all you need to do is create an instance of `fasthx.Jinja` and use its `hx()` or `page()` methods as decorators on your routes. `hx()` only triggers HTML rendering for HTMX requests, while `page()` unconditionally renders HTML. See the example code below:
+To start serving HTML and HTMX requests, all you need to do is create an instance of `fasthx.jinja.Jinja` and use its `hx()` or `page()` methods as decorators on your routes. `hx()` only triggers HTML rendering for HTMX requests, while `page()` unconditionally renders HTML. See the example code below:
 
 ```python
 from fastapi import FastAPI
 from fastapi.templating import Jinja2Templates
-from fasthx import Jinja
+from fasthx.jinja import Jinja
 from pydantic import BaseModel
 
 # Pydantic model of the data the example API is using.
@@ -145,7 +152,7 @@ See the full working example [here](https://github.com/volfpeter/fasthx/tree/mai
 
 Requires: `pip install fasthx`.
 
-If you would like to use a rendering engine without FastHX integration, you can easily build on the `hx()` and `page()` decorators which give you all the functionality you will need. All you need to do is implement the `HTMLRenderer` protocol.
+If you would like to use a rendering engine without FastHX integration, you can easily build on the `hx()` and `page()` decorators which give you all the functionality you will need. All you need to do is implement the `RenderFunction` protocol.
 
 Similarly to the Jinja case, `hx()` only triggers HTML rendering for HTMX requests, while `page()` unconditionally renders HTML. See the example code below:
 
@@ -158,7 +165,7 @@ from fasthx import hx, page
 # Create the app.
 app = FastAPI()
 
-# Create a dependecy to see that its return value is available in the render function.
+# Create a dependency to see that its return value is available in the render function.
 def get_random_number() -> int:
     return 4  # Chosen by fair dice roll.
 

{fasthx-2.3.2 → fasthx-3.0.0}/fasthx/__init__.py

@@ -3,10 +3,6 @@ from .core_decorators import hx as hx
 from .core_decorators import page as page
 from .dependencies import DependsHXRequest as DependsHXRequest
 from .dependencies import get_hx_request as get_hx_request
-from .jinja import Jinja as Jinja
-from .jinja import JinjaContext as JinjaContext
-from .jinja import JinjaPath as JinjaPath
-from .jinja import TemplateHeader as TemplateHeader
 from .typing import ComponentSelector as ComponentSelector
-from .typing import HTMLRenderer as HTMLRenderer
-from .typing import JinjaContextFactory as JinjaContextFactory
+from .typing import RenderFunction as RenderFunction
+from .typing import RequestComponentSelector as RequestComponentSelector

{fasthx-2.3.2 → fasthx-3.0.0}/fasthx/core_decorators.py

@@ -7,15 +7,15 @@ from fastapi import HTTPException, Response, status
 from fastapi.responses import HTMLResponse
 
 from .dependencies import DependsHXRequest, DependsPageRequest
-from .typing import HTMLRenderer, MaybeAsyncFunc, P, T
+from .typing import MaybeAsyncFunc, P, RenderFunction, T
 from .utils import append_to_signature, execute_maybe_sync_func, get_response
 
 
 def hx(
-    render: HTMLRenderer[T],
+    render: RenderFunction[T],
     *,
     no_data: bool = False,
-    render_error: HTMLRenderer[Exception] | None = None,
+    render_error: RenderFunction[Exception] | None = None,
 ) -> Callable[[MaybeAsyncFunc[P, T]], Callable[P, Coroutine[None, None, T | Response]]]:
     """
     Decorator that converts a FastAPI route's return value into HTML if the request was
@@ -59,17 +59,13 @@ def hx(
             response = get_response(kwargs)
             rendered = await execute_maybe_sync_func(renderer, result, context=kwargs, request=__hx_request)
 
-            return (
-                HTMLResponse(
-                    rendered,
-                    # The default status code of the FastAPI Response dependency is None
-                    # (not allowed by the typing but required for FastAPI).
-                    status_code=getattr(response, "status_code", 200) or 200,
-                    headers=getattr(response, "headers", None),
-                    background=getattr(response, "background", None),
-                )
-                if isinstance(rendered, str)
-                else rendered
+            return HTMLResponse(
+                rendered,
+                # The default status code of the FastAPI Response dependency is None
+                # (not allowed by the typing but required for FastAPI).
+                status_code=getattr(response, "status_code", 200) or 200,
+                headers=getattr(response, "headers", None),
+                background=getattr(response, "background", None),
             )
 
         return append_to_signature(
@@ -85,9 +81,9 @@ def hx(
 
 
 def page(
-    render: HTMLRenderer[T],
+    render: RenderFunction[T],
     *,
-    render_error: HTMLRenderer[Exception] | None = None,
+    render_error: RenderFunction[Exception] | None = None,
 ) -> Callable[[MaybeAsyncFunc[P, T]], Callable[P, Coroutine[None, None, Response]]]:
     """
     Decorator that converts a FastAPI route's return value into HTML.
@@ -102,7 +98,7 @@ def page(
         @wraps(func)
         async def wrapper(
             __page_request: DependsPageRequest, *args: P.args, **kwargs: P.kwargs
-        ) -> T | Response:
+        ) -> Response:
             try:
                 result = await execute_maybe_sync_func(func, *args, **kwargs)
                 renderer = render
@@ -120,17 +116,14 @@ def page(
             rendered = await execute_maybe_sync_func(
                 renderer, result, context=kwargs, request=__page_request
             )
-            return (
-                HTMLResponse(
-                    rendered,
-                    # The default status code of the FastAPI Response dependency is None
-                    # (not allowed by the typing but required for FastAPI).
-                    status_code=getattr(response, "status_code", 200) or 200,
-                    headers=getattr(response, "headers", None),
-                    background=getattr(response, "background", None),
-                )
-                if isinstance(rendered, str)
-                else rendered
+
+            return HTMLResponse(
+                rendered,
+                # The default status code of the FastAPI Response dependency is None
+                # (not allowed by the typing but required for FastAPI).
+                status_code=getattr(response, "status_code", 200) or 200,
+                headers=getattr(response, "headers", None),
+                background=getattr(response, "background", None),
             )
 
         return append_to_signature(

{fasthx-2.3.2 → fasthx-3.0.0}/fasthx/htmy.py

@@ -9,7 +9,7 @@ from fastapi import Request, Response
 
 from .component_selectors import ComponentHeader as _ComponentHeader
 from .core_decorators import hx, page
-from .typing import ComponentSelector, HTMLRenderer, MaybeAsyncFunc, P, RequestComponentSelector, T
+from .typing import ComponentSelector, MaybeAsyncFunc, P, RenderFunction, RequestComponentSelector, T
 
 if TYPE_CHECKING:
     from typing_extensions import Self
@@ -23,7 +23,7 @@ HTMYComponentSelector: TypeAlias = ComponentSelector[HTMYComponentFactory[T]]
 
 class ComponentHeader(_ComponentHeader[HTMYComponentFactory[T]]):
     """
-    `RequestComponentSelector` for HTMY components that takes selects the rendered component
+    `RequestComponentSelector` for HTMY components that selects the rendered component
     based on a request header.
     """
 
@@ -46,7 +46,7 @@ class CurrentRequest:
         Loads the current `Request` instance from the given context.
 
         Raises:
-            KeyError: If the there's no `Request` in the context.
+            KeyError: If there is no `Request` in the context.
             TypeError: If invalid data is stored for `Request`.
         """
         result = context[Request]
@@ -112,10 +112,10 @@ class HTMY:
     - All route parameters (as a `RouteParams` instance) that can be retrieved with
       `RouteParams.from_context()` in components.
     - Everything added through `self.request_processors`.
-    - The default context of `self.htmy`.
+    - The default context of `self.renderer`.
     """
 
-    htmy: h.Renderer = field(default_factory=h.Renderer)
+    renderer: h.RendererType = field(default_factory=h.Renderer)
     """The HTMY renderer to use."""
 
     no_data: bool = field(default=False, kw_only=True)
@@ -129,12 +129,12 @@ class HTMY:
     request_processors: list[RequestProcessor] = field(default_factory=list, kw_only=True)
     """
     A list of functions that expect the current request and return an `htmy` `Context` that should
-    be used during rendering in addition to the default context of `self.htmy`.
+    be used during rendering in addition to the default context of `self.renderer`.
     """
 
     def hx(
         self,
-        component_selector: HTMYComponentSelector[T],
+        component_selector: HTMYComponentSelector[T] | None = None,
         *,
         error_component_selector: HTMYComponentSelector[Exception] | None = None,
         no_data: bool = False,
@@ -143,12 +143,15 @@ class HTMY:
         Decorator for rendering the route's result if the request was an HTMX one.
 
         Arguments:
-            component_selector: The component selector to use.
+            component_selector: An optional component selector to use. If not provided, it is
+                assumed the route returns a component that should be rendered as is.
             error_component_selector: The component selector to use for route error rendering.
             no_data: If set, the route will only accept HTMX requests.
         """
         return hx(
-            self._make_render_function(component_selector),
+            self._make_render_function(
+                _default_component_selector if component_selector is None else component_selector
+            ),
             render_error=None
             if error_component_selector is None
             else self._make_error_render_function(error_component_selector),
@@ -157,7 +160,7 @@ class HTMY:
 
     def page(
         self,
-        component_selector: HTMYComponentSelector[T],
+        component_selector: HTMYComponentSelector[T] | None = None,
         *,
         error_component_selector: HTMYComponentSelector[Exception] | None = None,
     ) -> Callable[[MaybeAsyncFunc[P, T]], Callable[P, Coroutine[None, None, T | Response]]]:
@@ -167,11 +170,14 @@ class HTMY:
         This decorator triggers HTML rendering regardless of whether the request was HTMX or not.
 
         Arguments:
-            component_selector: The component selector to use.
+            component_selector: An optional component selector to use. If not provided, it is
+                assumed the route returns a component that should be rendered as is.
             error_component_selector: The component selector to use for route error rendering.
         """
         return page(
-            self._make_render_function(component_selector),
+            self._make_render_function(
+                _default_component_selector if component_selector is None else component_selector
+            ),
             render_error=None
             if error_component_selector is None
             else self._make_error_render_function(error_component_selector),
@@ -195,9 +201,9 @@ class HTMY:
         Returns:
             The rendered component.
         """
-        return await self.htmy.render(component, self._make_render_context(request, {}))
+        return await self.renderer.render(component, self._make_render_context(request, {}))
 
-    def _make_render_function(self, component_selector: HTMYComponentSelector[T]) -> HTMLRenderer[T]:
+    def _make_render_function(self, component_selector: HTMYComponentSelector[T]) -> RenderFunction[T]:
         """
         Creates a render function that uses the given component selector.
         """
@@ -208,13 +214,15 @@ class HTMY:
                 if isinstance(component_selector, RequestComponentSelector)
                 else component_selector
             )
-            return await self.htmy.render(component(result), self._make_render_context(request, context))
+            return await self.renderer.render(
+                component(result), self._make_render_context(request, context)
+            )
 
         return render
 
     def _make_error_render_function(
         self, component_selector: HTMYComponentSelector[Exception]
-    ) -> HTMLRenderer[Exception]:
+    ) -> RenderFunction[Exception]:
         """
         Creates an error renderer function that uses the given component selector.
         """
@@ -225,7 +233,9 @@ class HTMY:
                 if isinstance(component_selector, RequestComponentSelector)
                 else component_selector
             )
-            return await self.htmy.render(component(result), self._make_render_context(request, context))
+            return await self.renderer.render(
+                component(result), self._make_render_context(request, context)
+            )
 
         return render
 
@@ -251,3 +261,13 @@ class HTMY:
             result.update(cp(request))
 
         return result
+
+
+def _default_component_selector(route_result: Any) -> h.Component:
+    """
+    Default component selector that returns the route result as is.
+
+    It is assumed (and not validated) that the route result is a `htmy.Component` when
+    this component selector is used. Otherwise rendering will fail.
+    """
+    return route_result  # type: ignore[no-any-return]

{fasthx-2.3.2 → fasthx-3.0.0}/fasthx/jinja.py

@@ -1,20 +1,35 @@
-from collections.abc import Callable, Collection, Iterable
+from collections.abc import Callable, Collection, Coroutine, Iterable
 from dataclasses import dataclass, field
 from functools import lru_cache
-from typing import Any, Coroutine
+from typing import Any, Protocol
 
 from fastapi import Request, Response
 from fastapi.templating import Jinja2Templates
 
+from .component_selectors import ComponentHeader as _ComponentHeader
 from .core_decorators import hx, page
-from .typing import (
-    ComponentSelector,
-    HTMLRenderer,
-    JinjaContextFactory,
-    MaybeAsyncFunc,
-    P,
-    RequestComponentSelector,
-)
+from .typing import ComponentSelector, MaybeAsyncFunc, P, RenderFunction, RequestComponentSelector
+
+
+class JinjaContextFactory(Protocol):
+    """
+    Protocol definition for methods that convert a FastAPI route's result and route context
+    (i.e. the route's arguments) into a Jinja context (`dict`).
+    """
+
+    def __call__(self, *, route_result: Any, route_context: dict[str, Any]) -> dict[str, Any]:
+        """
+        Arguments:
+            route_result: The result of the route.
+            route_context: Every keyword argument the route received.
+
+        Returns:
+            The Jinja context dictionary.
+
+        Raises:
+            ValueError: If converting the arguments to a Jinja context fails.
+        """
+        ...
 
 
 class JinjaPath(str):
@@ -176,7 +191,7 @@ class JinjaContext:
         Arguments:
             result_key: The key by which the `route_result` should be accessible in templates.
                 See `JinjaContextFactory` for `route_result` details.
-            context_key: The key by whih the `route_context` should be accessible in templates.
+            context_key: The key by which the `route_context` should be accessible in templates.
                 If `None` (the default), then the `route_context` will not be accessible.
                 See `JinjaContextFactory` for `route_context` details.
 
@@ -200,71 +215,13 @@ class JinjaContext:
         return wrap
 
 
-@dataclass(frozen=True, slots=True)
-class TemplateHeader:
+class ComponentHeader(_ComponentHeader[str]):
     """
-    Template selector that takes the Jinja template name from a request header.
-
-    This class makes it possible for the client to submit the *key/ID* of the required template
-    to the server in a header. The Jinja decorators will then look up and render the requested
-    template if it exists. If the client doesn't request a specific template, then `default`
-    will be used if it was set, otherwise an exception will be raised.
-
-    By default this class treats template keys as case-insensitive. If you'd like to disable
-    this behavior, set `case_sensitive` to `True`.
-
-    This class can also handle route errors if the `error` property is set.
-
-    Implements:
-        - `RequestComponentSelector[str]`.
+    `RequestComponentSelector` for Jinja templates that selects the rendered template
+    based on a request header.
     """
 
-    header: str
-    """The header which is used by the client to communicate the *key* of the requested template."""
-
-    templates: dict[str, str]
-    """Dictionary that maps template keys to template (file) names."""
-
-    error: type[Exception] | tuple[type[Exception], ...] | None = field(default=None, kw_only=True)
-    """The accepted error or errors."""
-
-    default: str | None = field(default=None, kw_only=True)
-    """The template to use when the client didn't request a specific one."""
-
-    case_sensitive: bool = field(default=False, kw_only=True)
-    """Whether the keys of `templates` are case-sensitive or not (default is `False`)."""
-
-    def __post_init__(self) -> None:
-        if not self.case_sensitive:
-            object.__setattr__(
-                self,
-                "templates",
-                {k.lower(): v for k, v in self.templates.items()},
-            )
-
-    def get_component(self, request: Request, error: Exception | None) -> str:
-        """
-        Returns the name of the template that was requested by the client.
-
-        If the request doesn't contain a header (with the name `self.header`),
-        then `self.default` will be returned if it's not `None`.
-
-        Raises:
-            KeyError: If the client requested a specific template but it's unknown, or
-                if no template was requested and there's no default either.
-        """
-        if error is not None and (self.error is None or not isinstance(error, self.error)):
-            raise error
-
-        if (key := request.headers.get(self.header, None)) is not None:
-            if not self.case_sensitive:
-                key = key.lower()
-
-            return self.templates[key]
-        elif self.default is None:
-            raise KeyError("Default template was not set and header was not found.")
-        else:
-            return self.default
+    ...
 
 
 @dataclass(frozen=True, slots=True)
@@ -363,9 +320,9 @@ class Jinja:
         make_context: JinjaContextFactory,
         prefix: str | None,
         error_renderer: bool = False,
-    ) -> HTMLRenderer[Any]:
+    ) -> RenderFunction[Any]:
         """
-        Creates an `HTMLRenderer` with the given configuration.
+        Creates a `RenderFunction` with the given configuration.
 
         Arguments:
             template: The template the renderer function should use.
@@ -374,51 +331,22 @@ class Jinja:
             error_renderer: Whether this is an error renderer creation.
         """
 
-        def render(result: Any, *, context: dict[str, Any], request: Request) -> str | Response:
+        def render(result: Any, *, context: dict[str, Any], request: Request) -> str:
             template_name = self._resolve_template_name(
                 template,
                 error=result if error_renderer else None,
                 prefix=prefix,
                 request=request,
             )
-            return self._make_response(
-                template_name,
-                jinja_context=make_context(route_result=result, route_context=context),
+            result = self.templates.TemplateResponse(
+                name=template_name,
+                context=make_context(route_result=result, route_context=context),
                 request=request,
             )
+            return bytes(result.body).decode(result.charset)
 
         return render
 
-    def _make_response(
-        self,
-        template: str,
-        *,
-        jinja_context: dict[str, Any],
-        request: Request,
-    ) -> str | Response:
-        """
-        Creates the HTML response using the given Jinja template name and context.
-
-        Arguments:
-            template: The Jinja2 template selector to use.
-            jinja_context: The Jinj2 rendering context.
-            prefix: Optional template name prefix.
-            request: The current request.
-        """
-        # The reason for returning string from this method is to let `hx()` or `page()` create
-        # the HTML response - that way they can copy response headers and do other convenience
-        # conversions.
-        # The drawback is that users lose some of the baked-in debug utilities of TemplateResponse.
-        # This can be worked around by using a rendering context factory that includes the route's
-        # dependencies in the Jinja context. Then this method can be overridden to take the Response
-        # object from the context and copy the header from it into TemplateResponse.
-        result = self.templates.TemplateResponse(
-            name=template,
-            context=jinja_context,
-            request=request,
-        )
-        return bytes(result.body).decode(result.charset)
-
     def _resolve_template_name(
         self,
         template: ComponentSelector[str],

{fasthx-2.3.2 → fasthx-3.0.0}/fasthx/typing.py

@@ -1,20 +1,20 @@
 from collections.abc import Callable, Coroutine
 from typing import Any, ParamSpec, Protocol, TypeAlias, TypeVar, runtime_checkable
 
-from fastapi import Request, Response
+from fastapi import Request
 
 P = ParamSpec("P")
 T = TypeVar("T")
 Tco = TypeVar("Tco", covariant=True)
 Tcontra = TypeVar("Tcontra", contravariant=True)
 
-MaybeAsyncFunc = Callable[P, T] | Callable[P, Coroutine[Any, Any, T]]
+MaybeAsyncFunc: TypeAlias = Callable[P, T] | Callable[P, Coroutine[Any, Any, T]]
 
 
-class SyncHTMLRenderer(Protocol[Tcontra]):
-    """Sync HTML renderer definition."""
+class SyncRenderFunction(Protocol[Tcontra]):
+    """Sync render function definition."""
 
-    def __call__(self, result: Tcontra, *, context: dict[str, Any], request: Request) -> str | Response:
+    def __call__(self, result: Tcontra, *, context: dict[str, Any], request: Request) -> str:
         """
         Arguments:
             result: The result of the route the renderer is used on.
@@ -22,17 +22,15 @@ class SyncHTMLRenderer(Protocol[Tcontra]):
             request: The request being served.
 
         Returns:
-            HTML string (it will be automatically converted to `HTMLResponse`) or a `Response` object.
+            The rendered string.
         """
         ...
 
 
-class AsyncHTMLRenderer(Protocol[Tcontra]):
-    """Async HTML renderer definition."""
+class AsyncRenderFunction(Protocol[Tcontra]):
+    """Async render function definition."""
 
-    async def __call__(
-        self, result: Tcontra, *, context: dict[str, Any], request: Request
-    ) -> str | Response:
+    async def __call__(self, result: Tcontra, *, context: dict[str, Any], request: Request) -> str:
         """
         Arguments:
             result: The result of the route the renderer is used on.
@@ -40,34 +38,13 @@ class AsyncHTMLRenderer(Protocol[Tcontra]):
             request: The request being served.
 
         Returns:
-            HTML string (it will be automatically converted to `HTMLResponse`) or a `Response` object.
+            The rendered string.
         """
         ...
 
 
-HTMLRenderer = SyncHTMLRenderer[Tcontra] | AsyncHTMLRenderer[Tcontra]
-"""Sync or async HTML renderer type."""
-
-
-class JinjaContextFactory(Protocol):
-    """
-    Protocol definition for methods that convert a FastAPI route's result and route context
-    (i.e. the route's arguments) into a Jinja context (`dict`).
-    """
-
-    def __call__(self, *, route_result: Any, route_context: dict[str, Any]) -> dict[str, Any]:
-        """
-        Arguments:
-            route_result: The result of the route.
-            route_context: Every keyword argument the route received.
-
-        Returns:
-            The Jinja context dictionary.
-
-        Raises:
-            ValueError: If converting the arguments to a Jinja context fails.
-        """
-        ...
+RenderFunction: TypeAlias = SyncRenderFunction[Tcontra] | AsyncRenderFunction[Tcontra]
+"""Sync or async render function type."""
 
 
 @runtime_checkable
@@ -106,4 +83,4 @@ class RequestComponentSelector(Protocol[Tco]):
 
 
 ComponentSelector: TypeAlias = T | RequestComponentSelector[T]
-"""Type alias for known component selectors."""
+"""Type alias for all types of component selectors."""

{fasthx-2.3.2 → fasthx-3.0.0}/fasthx/utils.py

@@ -27,7 +27,7 @@ def append_to_signature(func: Callable[P, T], *params: inspect.Parameter) -> Cal
     Returns:
         The received function with an extended `__signature__`.
     """
-    signature = inspect.signature(func)
+    signature = inspect.signature(func, eval_str=True)
     func.__signature__ = signature.replace(parameters=(*signature.parameters.values(), *params))  # type: ignore[attr-defined]
     return func
 

{fasthx-2.3.2 → fasthx-3.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "fasthx"
-version = "2.3.2"
+version = "3.0.0"
 description = "FastAPI server-side rendering with built-in HTMX support."
 authors = ["Peter Volf <do.volfp@gmail.com>"]
 readme = "README.md"
@@ -9,7 +9,7 @@ license = "MIT"
 [tool.poetry.dependencies]
 python = "^3.10"
 fastapi = ">=0.100.0"
-htmy = { version = ">=0.5.0", optional = true }
+htmy = { extras = ["lxml"], version = ">=0.8.1", optional = true }
 jinja2 = { version = "^3.0.0", optional = true }
 
 [tool.poetry.extras]
@@ -17,18 +17,18 @@ htmy = ["htmy"]
 jinja = ["jinja2"]
 
 [tool.poetry.group.dev.dependencies]
-htmy = ">=0.5.0"
+htmy = { extras = ["lxml"], version = ">=0.8.1"}
 httpx = "^0.26.0"
 jinja2 = "^3.0.0"
-mkdocs-material = "^9.5.32"
-mkdocstrings = { extras = ["python"], version = "^0.25.2" }
-mypy = "^1.15.0"
-poethepoet = "^0.30.0"
-pytest = "^8.3.3"
-pytest-random-order = "^1.1.1"
-ruff = "^0.11.2"
+mkdocs-material = "^9.6.15"
+mkdocstrings = {extras = ["python"], version = "^0.30.0"}
+mypy = "^1.17.0"
+poethepoet = "^0.36.0"
+pytest = "^8.4.1"
+pytest-random-order = "^1.2.0"
+ruff = "^0.12.4"
 typing-extensions = ">=4.5.0"
-uvicorn = "^0.32.0"
+uvicorn = "^0.35.0"
 
 [build-system]
 requires = ["poetry-core"]
@@ -38,6 +38,13 @@ build-backend = "poetry.core.masonry.api"
 strict = true
 show_error_codes = true
 
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+addopts = "--random-order"
+
 [tool.ruff]
 line-length = 108
 exclude = [
@@ -63,12 +70,17 @@ lint.select = [
 "tests/**/*" = ["S101"] # S101: use of assert detected
 
 [tool.poe.tasks]
-check-format = "ruff format --check ."
-format = "ruff format ."
+format = "ruff format --check ."
+format-fix = "ruff format ."
+
 lint = "ruff check ."
 lint-fix = "ruff . --fix"
+
 mypy = "mypy ."
-test = "python -m pytest tests --random-order"
-static-checks.sequence = ["lint", "check-format", "mypy"]
-static-checks.ignore_fail = "return_non_zero"
+
+check.sequence = ["format", "lint", "mypy"]
+check.ignore_fail = "return_non_zero"
+
+test = "python -m pytest tests"
+
 serve-docs = "mkdocs serve"