feat!: template exception

[Murtagy]

Description

Added a wrapper around exceptions coming from templates.
The exceptions can be rather cryptic, so having a little more context around them is helpful.

E.g. I have an endpoint which uses SQLAlchemy to get some data and then passes it into template context to render.
The SQLAlchemy models have relations, which I have to load using selectinload for optimization and proper use of async.
So an untimely access to model.<relationship_name> caused an unwanted sync call to db from template context and raised an exception with little context around it. It has the endpoint name, but it takes some time to judge wether the error comes from endpoint code or template code, and doesn't help to debug template itself. See full stacktrace https://gist.github.com/Murtagy/9808d91ff497d37f40673516d2a8a373

So the core benefit of this PR is the change of

2024-06-11T09:21:45.120672Z [error    ] Uncaught Exception             connection_type=http path=/c/icard/abaf1066-cecb-424d-b7bf-07313e075608 traceback=  File "<string>", line 2, in _connection_for_bind
  File "/Users/murtagy/Dev/digital_card/.venv/lib/python3.12/site-packages/sqlalchemy/orm/state_changes.py", line 139, in _go
    ret_value = fn(self, *arg, **kw)

into

Traceback (most recent call last):
  File "/Users/murtagy/Dev/project/.venv/lib/python3.12/site-packages/litestar/response/template.py", line 150, in to_asgi_response
    body = template.render(**context).encode(self.encoding)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/murtagy/Dev/project/.venv/lib/python3.12/site-packages/jinja2/environment.py", line 1301, in render
    self.environment.handle_exception()
  File "/Users/murtagy/Dev/project/.venv/lib/python3.12/site-packages/jinja2/environment.py", line 936, in handle_exception
    raise rewrite_traceback_stack(source=source)
  File "/Users/murtagy/Dev/project/src/templates/card.html.jinja2", line 1, in top-level template code
    {% extends "base.html.jinja2" %}
    ^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/murtagy/Dev/project/src/templates/base.html.jinja2", line 143, in top-level template code
    {% block content %}
  File "/Users/murtagy/Dev/project/src/templates/card.html.jinja2", line 28, in block 'content'
    {% set interactions = card.interactions %}
    ^^^^^^^^^^^^^^^^^^^^^^^^^ 

Which now points to exact template location. Woohoo!

I did not add any tests for these 🤷

[codecov]

Codecov Report

Attention: Patch coverage is 71.42857% with 4 lines in your changes missing coverage. Please review.

Project coverage is 98.23%. Comparing base (883ca0a) to head (bab28ab).
Report is 55 commits behind head on main.

Files with missing lines	Patch %	Lines
litestar/exceptions/http_exceptions.py	60.00%	1 Missing and 1 partial ⚠️
litestar/response/template.py	77.77%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3561      +/-   ##
==========================================
- Coverage   98.25%   98.23%   -0.03%     
==========================================
  Files         328      328              
  Lines       14870    14882      +12     
  Branches     2366     2367       +1     
==========================================
+ Hits        14611    14619       +8     
- Misses        117      120       +3     
- Partials      142      143       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Murtagy]

@JacobCoffee how could I ask for a review? I can not click and change "Reviewers"

[provinzkraut]

Thanks for the PR @Murtagy!

I'm afraid this will have to wait until 3.0, as it is a breaking change because it changes the exception type, which some users might rely on.

If you want, you can retarget this at the v3.0 branch

[Murtagy]

Thanks for the PR @Murtagy!

I'm afraid this will have to wait until 3.0, as it is a breaking change because it changes the exception type, which some users might rely on.

If you want, you can retarget this at the v3.0 branch

What is the exception that users could already handle?
In my understanding, this was a completely unhandled exception. Could this be a minor version change? I would be surprised that adding a handled exception is major version change

[github-actions]

Documentation preview will be available shortly at https://litestar-org.github.io/litestar-docs-preview/3561

[Murtagy]

@provinzkraut , I see that 2.9.1 is on the way de8f4a7 . What would it take to put this into 3.0 ?

[provinzkraut]

What is the exception that users could already handle? In my understanding, this was a completely unhandled exception. Could this be a minor version change? I would be surprised that adding a handled exception is major version change

You are adding blanket exception handling here:

litestar/litestar/response/template.py

Lines 146 to 149 in bab28ab

	try:
	body = template_engine.render_string(self.template_str, context)
	except Exception as e:
	raise TemplateRenderingException from e

If a user had previously implemented a subclass of Template in which they've overridden to_asgi_response and are catching a specific exception thrown by render_string, their code for that would no longer work correctly.

Another scenario would be top-level exception handling for a specific exception thrown by the templating engine, for the same reasons.

What would it take to put this into 3.0?

Just rebase from the v3.0 branch and change your PR to target that branch

[provinzkraut]

Closing this for now. @Murtagy if you're still interested in this feature, you can reopen a new PR against the v3.0 branch as I explained in my comment above.