feature request: Support rendering for exception handlers

[JacobHayes]

I've been using a 404 exception handler like below:

    @app.exception_handler(status.HTTP_404_NOT_FOUND)
    async def _(request: Request, exc: HTTPException) -> HTMLResponse:
        return templates.TemplateResponse(
            request=request, name="404.html", context={"...": ...}
        )

It'd be helpful if there was a way to use fasthx with exception handlers too, for example an exception: bool flag to .hx and .page. When converting my other routes to use fasthx, I would otherwise not reference fastapi's TemplateResponse anymore.

---

If you try to use fasthx for this now:

    @app.exception_handler(status.HTTP_404_NOT_FOUND)
    @jinja.page("404.html")
    async def _(request: Request, exc: HTTPException) -> HTMLResponse:
        return {"...": ...}

it raises an error like below:

File "<...>/.venv/lib/python3.13/site-packages/fasthx/utils.py", line 46, in execute_maybe_sync_func
    return await func(*args, **kwargs)  # type: ignore[no-any-return]
                 ~~~~^^^^^^^^^^^^^^^^^
TypeError: create_app.<locals>._() missing 1 required positional argument: 'exc'

[volfpeter]

Hi,

The @hx and @page decorators are designed to work on FastAPI routes (with FastAPI's dependency resolution mechanism), not exception handlers. Both of these decorators have an error_template argument (which should be a template or template selector) that you can use to render errors that are raised within the decorated route. This is handy for example for form validation, and it can also be useful if different routes need to return different HTML snippets for the same errors.

I agree that a @jinja.exception(...) decorator would look nicer (declarative syntax is usually better), but it would also add complexity, and I'm not fully convinced that it is a worthy trade-off, especially not for a trivial case. And of course such a decorator would need to handle more complex use-cases, like rendering different templates based on the exception's type, its details, or some data (e.g. path) from the request.

Please feel free to add counter arguments. In the meantime, here's the pseudo-code for such a decorator in a Jinja subclass (it combines rendering with the exception handler registration, so only 1 decorator would be required):

class JinjaWithExceptionHandler(Jinja):
    def exception_handler(app: FastAPI, exception: type[Exception], template: str):
        def decorator(handler: Callable):
            def wrapper(request: Request, exc: Exception):
                result = handler(request, exc)
                return self._make_response(template, jinja_context=result, request=request)

            app.exception_handler(exception)(wrapper)

            return wrapper

        return decorator

[JacobHayes]

Thanks for the detailed comment and pseudo code!

Yes, that makes sense; I was looking forward to using the error_template param. Perhaps an .exception_handler method is mostly helpful when there's no associated route (eg: 404) or it is not called (eg: form and other validation errors, as you mention in #16 (comment)) since otherwise the error_template param to page and hx is clearer.

I agree on this adding some complexity, but as far as determining what template to use, can most of that fall to the RequestComponentSelector.get_component implementations? Conveniently (or intentionally 😁), those already take (request: Request, error: Exception | None), ~matching the FastAPI exception handlers.

[volfpeter]

... or it is not called (eg: form and other validation errors, as you mention in #16 (comment)) since otherwise the error_template param to page and hx is clearer.

Well, that's a pretty outdated issues/answer (from version 0., now we're at 2.), the error_template argument didn't exist back then. The best way to do form validation (now) is to accept even invalid data in the route (easiest way is data: MyModel | dict[str, Any] for example), raise an exception if the data is not an instance of MyModel, and use the error template to render the exception. This way you can add all the necessary extra data to the exception, maybe do DB operations, and even use a non-200 status code with the response-targets HTMX extension (because for form validation errors you normally want different HTMX targets and swap rules than for the success case).

I agree on this adding some complexity, but as far as determining what template to use, can most of that fall to the RequestComponentSelector.get_component implementations? Conveniently (or intentionally 😁), those already take (request: Request, error: Exception | None), ~matching the FastAPI exception handlers.

RequestComponentSelector.get_component() needs at least these arguments to be able to function, so it's a matter of necessity and minimalism. It never occurred to me that it's basically the same API as FastAPI exception handlers 😄 (Back then I even thought about splitting up the interface for success and error selectors, but it would just have complicated things, but that way the API would be exactly the same).

If you have decide to implement this decorator (for your use-case at least), please share it in the discussions. Others may find it helpful. Also, I could then fully evaluate it and see if it should be added to the library (for that it obviously also needs docs, maybe examples, and it should work not only with Jinja but also with HTMY).