Skip to content

Migrating from v2 to v3

fasthx was first developed with Jinja templating and HTML rendering in mind. The feature set of the project grew significantly since then, for example with error rendering support and htmy integration, among other, smaller improvements.

More features and integrations are planned, and the main goal of this upgrade is to prepare the project structure for them.

Summary of major changes:

  • All Jinja-related code now lives in fasthx.jinja and can only be imported from that package.
  • *HTMLRenderer types have been renamed to *RenderFunction to prepare for rendering non-HTML content.
  • The RenderFunction type has changed: Response is no longer allowed as the return value.
  • Updated the required htmy version to >=0.8.1.

Upgrade steps (general)

These are all typing-related changes and most likely not relevant to your project unless you have created custom render functions or integrations.

  • Replace from fasthx import HTMLRenderer with from fasthx import RenderFunction.
  • Replace from fasthx.typing import HTMLRenderer with from fasthx.typing import RenderFunction.
  • Replace from fasthx.typing import SyncHTMLRenderer with from fasthx.typing import SyncRenderFunction.
  • Replace from fasthx.typing import AsyncHTMLRenderer with from fasthx.typing import AsyncRenderFunction.

Upgrade steps (Jinja)

These are mostly import changes — all the Jinja-related utilities can now only imported from fasthx.jinja — and the renaming of TemplateHeader to ComponentHeader.

  • Replace from fasthx import Jinja with from fasthx.jinja import Jinja.
  • Replace from fasthx import JinjaContext with from fasthx.jinja import JinjaContext.
  • Replace from fasthx import JinjaPath with from fasthx.jinja import JinjaPath.
  • Replace from fasthx import TemplateHeader with from fasthx.jinja import ComponentHeader.
  • Replace from fasthx.jinja import TemplateHeader with from fasthx.jinja import ComponentHeader.
  • Replace from fasthx import JinjaContextFactory with from fasthx.jinja import JinjaContextFactory.
  • Replace from fasthx.typing import JinjaContextFactory with from fasthx.jinja import JinjaContextFactory.
  • Instead of the templates argument of TemplateHeader(), you must use the components argument of ComponentHeader, if you passed templates as a keyword argument.
  • Jinja._make_response() has been removed to simplify the codebase. If you have overridden it, you must now override Jinja._make_render_function() instead.

Upgrade steps (htmy)

  • Make sure you're using htmy version >=0.8.1.
  • The HTMY instance no longer has an htmy property; it has been replaced by the renderer property.

Upgrade steps (custom rendering)

  • RenderFunction must return a str, Response is no longer allowed.