htmy 0.7.0__tar.gz → 0.9.0__tar.gz

{htmy-0.7.0 → htmy-0.9.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Peter Volf
+Copyright (c) 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

htmy-0.7.0/README.md → htmy-0.9.0/PKG-INFO

@@ -1,3 +1,26 @@
+Metadata-Version: 2.4
+Name: htmy
+Version: 0.9.0
+Summary: Async, pure-Python server-side rendering engine.
+License: MIT
+License-File: LICENSE
+Author: Peter Volf
+Author-email: do.volfp@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: lxml
+Requires-Dist: anyio (>=4.6.2.post1,<5.0.0)
+Requires-Dist: async-lru (>=2.0.4,<3.0.0)
+Requires-Dist: lxml (>=6.0.0) ; extra == "lxml"
+Requires-Dist: markdown (>=3.8,<4.0)
+Description-Content-Type: text/markdown
+
 ![Tests](https://github.com/volfpeter/htmy/actions/workflows/tests.yml/badge.svg)
 ![Linters](https://github.com/volfpeter/htmy/actions/workflows/linters.yml/badge.svg)
 ![Documentation](https://github.com/volfpeter/htmy/actions/workflows/build-docs.yml/badge.svg)
@@ -9,13 +32,13 @@
 
 # `htmy`
 
-**Async**, **pure-Python** rendering engine.
+**Async**, **pure-Python** server-side rendering engine.
 
 Unleash your creativity with the full power and Python, without the hassle of learning a new templating language or dealing with its limitations!
 
 ## Key features
 
-- **Async**-first, to let you make the best use of [modern async tools](https://github.com/timofurrer/awesome-asyncio).
+- **Async**-first, to let you make the best use of modern async tools.
 - **Powerful**, React-like **context support**, so you can avoid prop-drilling.
 - Sync and async **function components** with **decorator syntax**.
 - All baseline **HTML** tags built-in.
@@ -26,8 +49,23 @@ Unleash your creativity with the full power and Python, without the hassle of le
 - **Unopinionated**: use the backend, CSS, and JS frameworks of your choice, the way you want to use them.
 - Everything is **easily customizable**, from the rendering engine to components, formatting and context management.
 - Automatic and customizable **property-name conversion** from snake case to kebab case.
+- **Compatible** with any other templating library through wrappers.
 - **Fully-typed**.
 
+## 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))
+
+"I love that the language-embedded HTML generation library approach is becoming more popular." ([ref](https://www.reddit.com/r/programming/comments/1h1a0dx/comment/lzd3phw))
+
+"Neat approach and it naturally solves the partial templates problem 👍" ([ref](https://www.reddit.com/r/Python/comments/1gp3mww/comment/lwqj4fc))
+
+"Great API design!" ([ref](https://www.reddit.com/r/Python/comments/1gp3mww/comment/lwpdyq9))
+
 ## 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-%20HTMY) so you can get the most out of the library.
@@ -40,6 +78,10 @@ The package is available on PyPI and can be installed with:
 $ pip install htmy
 ```
 
+The package has the following optional dependencies:
+
+- `lxml` *(recommended)*: When installed, it is prioritized over `xml.etree.ElementTree` and provides more secure, faster, and more flexible HTML and XML processing. It is used, for example, for Markdown processing. Install with: `pip install "htmy[lxml]"`.
+
 ## Concepts
 
 The entire library -- from the rendering engine itself to the built-in components -- is built around a few simple protocols and a handful of simple utility classes. This means that you can easily customize, extend, or replace basically everything in the library. Yes, even the rendering engine. The remaining parts will keep working as expected.
@@ -97,7 +139,7 @@ user_table = html.table(
 )
 ```
 
-`htmy` also provides a `@component` decorator that can be used on sync or async `my_component(props: MyProps, context: Context) -> Component` functions to convert them into components (preserving the `props` typing).
+`htmy` also provides a powerful `@component` decorator that can be used on sync or async `my_component(props: MyProps, context: Context) -> Component` functions and methods to convert them into components (preserving the `props` typing). You can find out more about this feature in the [Function components](https://volfpeter.github.io/htmy/function-components/) guide.
 
 Here is the same example as above, but with function components:
 
@@ -266,6 +308,7 @@ These are default tag attribute formatting rules:
 - `bool` attribute values are converted to strings (`"true"` and `"false"`).
 - `XBool.true` attributes values are converted to an empty string, and `XBool.false` values are skipped (only the attribute name is rendered).
 - `date` and `datetime` attribute values are converted to ISO strings.
+- Complex values such as lists, dictionaries, tuples, and sets are JSON serialized.
 
 ### Error boundary
 
@@ -283,11 +326,39 @@ If a component executes a potentially "long-running" synchronous call, it is str
 
 In all other cases, it's best to use sync components.
 
+## XSS prevention
+
+`htmy` does XML/HTML escaping by default. This means user input is normally sanitized and rendered safely.
+
+There are a couple of notable exceptions to this, where components by design allow XML/HTML inputs and assume they are safe:
+
+- `Snippet`: The primary use-case is to efficiently render XML/HTML templates, filling in placeholders with dynamic content. In this case you must ensure that the input template itself is safe!
+- `MD`: This component builds on `Snippet` to support markdown inputs and performs automatic markdown to HTML conversion. You must ensure the input text is safe!
+
+## AI assistance
+
+The library is registered at [Context7](https://context7.com/volfpeter).
+
+To get good AI assistance, all you need to do is register the Context7 MCP server in your coding tool and tell the agent to use it.
+
+Because of the similarity with native HTML, JSX, and React, you can expect good results, both for vibe coding or inline completion.
+
+## Compatibility and performance
+
+By design, `htmy` is compatible with any other Python templating library, for example Jinja, through wrappers. A wrapper is simply a custom `htmy` component that internally offloads rendering to another templating framework. This makes it possible to easily combine `htmy` with other libraries, to gradually adopt it, and even to enjoy the benefits of multiple frameworks.
+
+Performance strongly depends on how you use `htmy`. The `Snippet` component for example makes it possible to reach almost Python string formatting performance, while rendering large, deep component trees is noticeably slower than Jinja for example. Wrapping another templating library for certain use-cases, or pre-rendering components and later using `Snippet` to fill in the dynamic content can be beneficial for performance.
+
 ## Framework integrations
 
 FastAPI:
 
-- [FastHX](https://github.com/volfpeter/fasthx)
+- [holm](https://github.com/volfpeter/holm): Web development framework that brings the Next.js developer experience to Python, built on FastAPI, htmy, and FastHX.
+- [FastHX](https://github.com/volfpeter/fasthx): Declarative server-side rendering utility for FastAPI with built-in HTMX support.
+
+## External examples
+
+- [lipsum-chat](https://github.com/volfpeter/lipsum-chat): A simple chat application using `FastAPI`, `htmx`, and `fasthx`.
 
 ## Why
 
@@ -328,3 +399,4 @@ We welcome contributions from the community to help improve the project! Whether
 ## License - MIT
 
 The package is open-sourced under the conditions of the [MIT license](https://choosealicense.com/licenses/mit/).
+

htmy-0.7.0/PKG-INFO → htmy-0.9.0/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.3
-Name: htmy
-Version: 0.7.0
-Summary: Async, pure-Python rendering engine.
-License: MIT
-Author: Peter Volf
-Author-email: do.volfp@gmail.com
-Requires-Python: >=3.10,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: anyio (>=4.6.2.post1,<5.0.0)
-Requires-Dist: async-lru (>=2.0.4,<3.0.0)
-Requires-Dist: markdown (>=3.7,<4.0)
-Description-Content-Type: text/markdown
-
 ![Tests](https://github.com/volfpeter/htmy/actions/workflows/tests.yml/badge.svg)
 ![Linters](https://github.com/volfpeter/htmy/actions/workflows/linters.yml/badge.svg)
 ![Documentation](https://github.com/volfpeter/htmy/actions/workflows/build-docs.yml/badge.svg)
@@ -28,13 +9,13 @@ Description-Content-Type: text/markdown
 
 # `htmy`
 
-**Async**, **pure-Python** rendering engine.
+**Async**, **pure-Python** server-side rendering engine.
 
 Unleash your creativity with the full power and Python, without the hassle of learning a new templating language or dealing with its limitations!
 
 ## Key features
 
-- **Async**-first, to let you make the best use of [modern async tools](https://github.com/timofurrer/awesome-asyncio).
+- **Async**-first, to let you make the best use of modern async tools.
 - **Powerful**, React-like **context support**, so you can avoid prop-drilling.
 - Sync and async **function components** with **decorator syntax**.
 - All baseline **HTML** tags built-in.
@@ -45,8 +26,23 @@ Unleash your creativity with the full power and Python, without the hassle of le
 - **Unopinionated**: use the backend, CSS, and JS frameworks of your choice, the way you want to use them.
 - Everything is **easily customizable**, from the rendering engine to components, formatting and context management.
 - Automatic and customizable **property-name conversion** from snake case to kebab case.
+- **Compatible** with any other templating library through wrappers.
 - **Fully-typed**.
 
+## 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))
+
+"I love that the language-embedded HTML generation library approach is becoming more popular." ([ref](https://www.reddit.com/r/programming/comments/1h1a0dx/comment/lzd3phw))
+
+"Neat approach and it naturally solves the partial templates problem 👍" ([ref](https://www.reddit.com/r/Python/comments/1gp3mww/comment/lwqj4fc))
+
+"Great API design!" ([ref](https://www.reddit.com/r/Python/comments/1gp3mww/comment/lwpdyq9))
+
 ## 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-%20HTMY) so you can get the most out of the library.
@@ -59,6 +55,10 @@ The package is available on PyPI and can be installed with:
 $ pip install htmy
 ```
 
+The package has the following optional dependencies:
+
+- `lxml` *(recommended)*: When installed, it is prioritized over `xml.etree.ElementTree` and provides more secure, faster, and more flexible HTML and XML processing. It is used, for example, for Markdown processing. Install with: `pip install "htmy[lxml]"`.
+
 ## Concepts
 
 The entire library -- from the rendering engine itself to the built-in components -- is built around a few simple protocols and a handful of simple utility classes. This means that you can easily customize, extend, or replace basically everything in the library. Yes, even the rendering engine. The remaining parts will keep working as expected.
@@ -116,7 +116,7 @@ user_table = html.table(
 )
 ```
 
-`htmy` also provides a `@component` decorator that can be used on sync or async `my_component(props: MyProps, context: Context) -> Component` functions to convert them into components (preserving the `props` typing).
+`htmy` also provides a powerful `@component` decorator that can be used on sync or async `my_component(props: MyProps, context: Context) -> Component` functions and methods to convert them into components (preserving the `props` typing). You can find out more about this feature in the [Function components](https://volfpeter.github.io/htmy/function-components/) guide.
 
 Here is the same example as above, but with function components:
 
@@ -285,6 +285,7 @@ These are default tag attribute formatting rules:
 - `bool` attribute values are converted to strings (`"true"` and `"false"`).
 - `XBool.true` attributes values are converted to an empty string, and `XBool.false` values are skipped (only the attribute name is rendered).
 - `date` and `datetime` attribute values are converted to ISO strings.
+- Complex values such as lists, dictionaries, tuples, and sets are JSON serialized.
 
 ### Error boundary
 
@@ -302,11 +303,39 @@ If a component executes a potentially "long-running" synchronous call, it is str
 
 In all other cases, it's best to use sync components.
 
+## XSS prevention
+
+`htmy` does XML/HTML escaping by default. This means user input is normally sanitized and rendered safely.
+
+There are a couple of notable exceptions to this, where components by design allow XML/HTML inputs and assume they are safe:
+
+- `Snippet`: The primary use-case is to efficiently render XML/HTML templates, filling in placeholders with dynamic content. In this case you must ensure that the input template itself is safe!
+- `MD`: This component builds on `Snippet` to support markdown inputs and performs automatic markdown to HTML conversion. You must ensure the input text is safe!
+
+## AI assistance
+
+The library is registered at [Context7](https://context7.com/volfpeter).
+
+To get good AI assistance, all you need to do is register the Context7 MCP server in your coding tool and tell the agent to use it.
+
+Because of the similarity with native HTML, JSX, and React, you can expect good results, both for vibe coding or inline completion.
+
+## Compatibility and performance
+
+By design, `htmy` is compatible with any other Python templating library, for example Jinja, through wrappers. A wrapper is simply a custom `htmy` component that internally offloads rendering to another templating framework. This makes it possible to easily combine `htmy` with other libraries, to gradually adopt it, and even to enjoy the benefits of multiple frameworks.
+
+Performance strongly depends on how you use `htmy`. The `Snippet` component for example makes it possible to reach almost Python string formatting performance, while rendering large, deep component trees is noticeably slower than Jinja for example. Wrapping another templating library for certain use-cases, or pre-rendering components and later using `Snippet` to fill in the dynamic content can be beneficial for performance.
+
 ## Framework integrations
 
 FastAPI:
 
-- [FastHX](https://github.com/volfpeter/fasthx)
+- [holm](https://github.com/volfpeter/holm): Web development framework that brings the Next.js developer experience to Python, built on FastAPI, htmy, and FastHX.
+- [FastHX](https://github.com/volfpeter/fasthx): Declarative server-side rendering utility for FastAPI with built-in HTMX support.
+
+## External examples
+
+- [lipsum-chat](https://github.com/volfpeter/lipsum-chat): A simple chat application using `FastAPI`, `htmx`, and `fasthx`.
 
 ## Why
 
@@ -347,4 +376,3 @@ We welcome contributions from the community to help improve the project! Whether
 ## License - MIT
 
 The package is open-sourced under the conditions of the [MIT license](https://choosealicense.com/licenses/mit/).
-

{htmy-0.7.0 → htmy-0.9.0}/htmy/__init__.py

@@ -30,12 +30,17 @@ from .typing import HTMYComponentType as HTMYComponentType
 from .typing import MutableContext as MutableContext
 from .typing import Properties as Properties
 from .typing import PropertyValue as PropertyValue
+from .typing import RendererType as RendererType
+from .typing import StrictComponentType as StrictComponentType
 from .typing import SyncComponent as SyncComponent
 from .typing import SyncContextProvider as SyncContextProvider
 from .utils import as_component_sequence as as_component_sequence
 from .utils import as_component_type as as_component_type
 from .utils import is_component_sequence as is_component_sequence
+from .utils import join
 from .utils import join_components as join_components
 
+join_classes = join
+
 HTMY = Renderer
 """Deprecated alias for `Renderer`."""

{htmy-0.7.0 → htmy-0.9.0}/htmy/core.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import abc
 import enum
+import json
 from collections.abc import Callable, Container
 from typing import TYPE_CHECKING, Any, ClassVar, TypedDict, cast
 from xml.sax.saxutils import escape as xml_escape
@@ -251,6 +252,9 @@ class Formatter(ContextAware):
     """
     The default, context-aware property name and value formatter.
 
+    The formatter supports both primitive and (many) complex values, such as lists,
+    dictionaries, tuples, and sets. Complex values are JSON-serialized by default.
+
     Important: the default implementation looks up the formatter for a given value by checking
     its type, but it doesn't do this check with the base classes of the encountered type. For
     example the formatter will know how to format `datetime` object, but it won't know how to
@@ -258,7 +262,7 @@ class Formatter(ContextAware):
 
     One reason for this is efficiency: always checking the base classes of every single value is a
     lot of unnecessary calculation. The other reason is customizability: this way you could use
-    subclassing for fomatter selection, e.g. with `LocaleDatetime(datetime)`-like classes.
+    subclassing for formatter selection, e.g. with `LocaleDatetime(datetime)`-like classes.
 
     Property name and value formatters may raise a `SkipProperty` error if a property should be skipped.
     """
@@ -337,6 +341,10 @@ class Formatter(ContextAware):
             bool: lambda v: "true" if v else "false",
             date: lambda d: cast(date, d).isoformat(),
             datetime: lambda d: cast(datetime, d).isoformat(),
+            dict: lambda v: json.dumps(v),
+            list: lambda v: json.dumps(v),
+            tuple: lambda v: json.dumps(v),
+            set: lambda v: json.dumps(tuple(v)),
             XBool: lambda v: cast(XBool, v).format(),
             type(None): SkipProperty.format_property,
         }

{htmy-0.7.0 → htmy-0.9.0}/htmy/etree.py

@@ -1,23 +1,37 @@
 from __future__ import annotations
 
-import xml.etree.ElementTree as ET
-from collections.abc import Callable, Generator
 from typing import TYPE_CHECKING, ClassVar
 from xml.sax.saxutils import unescape
 
-if TYPE_CHECKING:
-    from collections.abc import Mapping
-    from xml.etree.ElementTree import Element
-
-    from htmy.typing import ComponentType, Properties
-
+try:
+    from lxml.etree import _Element as Element
+    from lxml.etree import tostring as etree_to_string
+    from lxml.html import fragment_fromstring as etree_from_string
+except ImportError:
+    from xml.etree.ElementTree import Element  # type: ignore[assignment]
+    from xml.etree.ElementTree import fromstring as etree_from_string  # type: ignore[assignment]
+    from xml.etree.ElementTree import tostring as etree_to_string  # type: ignore[no-redef]
 
+from htmy import ComponentType, Properties
 from htmy.core import Fragment, SafeStr, WildcardTag
 
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator, Mapping
+
 
 class ETreeConverter:
     """
     Utility for converting XML strings to custom components.
+
+    By default the converter uses the standard library's `xml.etree.ElementTree`
+    module for string to element tree, and element tree to string conversion,
+    but if `lxml` is installed, it will be used instead.
+
+    Installing `lxml` is recommended for better performance and additional features,
+    like performance and support for broken HTML fragments. **Important:** `lxml` is
+    far more lenient and flexible than the standard library, so having it installed is
+    not only a performance boost, but it may also slightly change the element conversion
+    behavior in certain edge-cases!
     """
 
     __slots__ = ("_rules",)
@@ -43,15 +57,15 @@ class ETreeConverter:
             return SafeStr(element)
 
         element = f"<{self._htmy_fragment}>{element}</{self._htmy_fragment}>"
-        return self.convert_element(ET.fromstring(element))  # noqa: S314 # Only use from XML strings from a trusted source.
+        return self.convert_element(etree_from_string(element))  # noqa: S314 # Only use XML strings from a trusted source.
 
     def convert_element(self, element: Element) -> ComponentType:
         """Converts the given `Element` to a component."""
         rules = self._rules
         if len(rules) == 0:
-            return SafeStr(ET.tostring(element))
+            return SafeStr(etree_to_string(element, encoding="unicode"))
 
-        tag: str = element.tag
+        tag: str = element.tag  # type: ignore[assignment]
         component = Fragment if tag == self._htmy_fragment else rules.get(tag)
         children = self._convert_children(element)
         properties = self._convert_properties(element)

{htmy-0.7.0 → htmy-0.9.0}/htmy/html.py

@@ -285,7 +285,7 @@ class hr(TagWithProps):
     __slots__ = ()
 
 
-class iframe(TagWithProps):
+class iframe(Tag):
     """
     `<iframe>` element.
 
@@ -709,6 +709,18 @@ class i(Tag):
     tag_config = _DefaultTagConfig.inline_children
 
 
+class kbd(Tag):
+    """
+    `<kbd>` element.
+
+    See https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd.
+    """
+
+    __slots__ = ()
+
+    tag_config = _DefaultTagConfig.inline_children
+
+
 class picture(Tag):
     """
     `<picture>` element.

{htmy-0.7.0 → htmy-0.9.0}/htmy/i18n.py

@@ -112,7 +112,7 @@ class I18n(ContextAware):
         return result
 
 
-@alru_cache(8)
+@alru_cache()
 async def load_translation_resource(path: Path) -> TranslationResource:
     """
     Loads the translation resource from the given path.

htmy-0.9.0/htmy/io.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from anyio import open_file as open_file
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+async def load_text_file(path: str | Path) -> str:
+    """Loads the text content from the given path."""
+    async with await open_file(path, "r") as f:
+        return await f.read()

{htmy-0.7.0 → htmy-0.9.0}/htmy/md/core.py

@@ -22,7 +22,7 @@ class MarkdownParser(ContextAware):
     Context-aware markdown parser.
 
     By default, this class uses the `markdown` library with a sensible set of
-    [extensions](https://python-markdown.github.io/extensions/) including code highlighing.
+    [extensions](https://python-markdown.github.io/extensions/) including code highlighting.
     """
 
     __slots__ = ("_md",)
@@ -85,10 +85,14 @@ class MD(Snippet):
     It supports all the processing utilities of `Snippet`, including `text_resolver` and
     `text_processor` for formatting, token replacement, and slot conversion to components.
 
-    One note regaring slot convesion (`text_resolver`): it is executed before markdown parsing,
+    One note regarding slot conversion (`text_resolver`): it is executed before markdown parsing,
     and all string segments of the resulting component sequence are parsed individually by the
     markdown parser. As a consequence, you should only use slots in places where the preceding
     and following texts individually result in valid markdown.
+
+    **Warning:** The component treats its input as trusted. If any part of the input comes from
+    untrusted sources, ensure it is safely escaped (using for example `htmy.xml_format_string`)!
+    Passing untrusted input to this component leads to XSS vulnerabilities.
     """
 
     __slots__ = (

{htmy-0.7.0 → htmy-0.9.0}/htmy/renderer/baseline.py

@@ -44,6 +44,8 @@ class Renderer:
         """
         Renders the given component.
 
+        Implements `htmy.typing.RendererType`.
+
         Arguments:
             component: The component to render.
             context: An optional rendering context.
@@ -71,16 +73,18 @@ class Renderer:
         """
         if isinstance(component, str):
             return self._string_formatter(component)
+        elif component is None:
+            return ""
         elif isinstance(component, Iterable):
             rendered_children = await asyncio.gather(
-                *(self._render_one(comp, context) for comp in component)
+                *(self._render_one(comp, context) for comp in component if comp is not None)
             )
 
-            return "".join(rendered_children)
+            return "".join(child for child in rendered_children if child is not None)
         else:
-            return await self._render_one(component, context)
+            return await self._render_one(component, context) or ""
 
-    async def _render_one(self, component: ComponentType, context: Context) -> str:
+    async def _render_one(self, component: ComponentType, context: Context) -> str | None:
         """
         Renders a single component.
 
@@ -93,6 +97,8 @@ class Renderer:
         """
         if isinstance(component, str):
             return self._string_formatter(component)
+        elif component is None:
+            return None
         else:
             child_context: Context = context
             if hasattr(component, "htmy_context"):  # isinstance() is too expensive.

{htmy-0.7.0 → htmy-0.9.0}/htmy/renderer/default.py

@@ -181,7 +181,9 @@ class _ComponentRenderer:
         `node.component` must be an `HTMYComponentType` (single component and not `str`).
         """
         component = node.component
-        if asyncio.iscoroutinefunction(component.htmy):  # type: ignore[union-attr]
+        if component is None:
+            pass  # Just skip the node
+        elif asyncio.iscoroutinefunction(component.htmy):  # type: ignore[union-attr]
             self._async_todos.append((node, child_context))
         elif isinstance(component, ErrorBoundary):
             self._error_boundary_todos.append((node, child_context))
@@ -199,25 +201,29 @@ class _ComponentRenderer:
             while sync_todos:
                 node, child_context = sync_todos.pop()
                 component = node.component
+                if component is None:
+                    continue
+
                 if hasattr(component, "htmy_context"):  # isinstance() is too expensive.
                     child_context = await self._extend_context(component, child_context)  # type: ignore[arg-type]
 
-                if asyncio.iscoroutinefunction(node.component.htmy):  # type: ignore[union-attr]
+                if asyncio.iscoroutinefunction(component.htmy):  # type: ignore[union-attr]
                     async_todos.append((node, child_context))
                 else:
-                    result: Component = node.component.htmy(child_context)  # type: ignore[assignment,union-attr]
+                    result: Component = component.htmy(child_context)  # type: ignore[assignment,union-attr]
                     process_node_result(node, result, child_context)
 
             if async_todos:
-                await asyncio.gather(*(process_async_node(n, ctx) for n, ctx in async_todos))
-                async_todos.clear()
+                current_async_todos = async_todos
+                self._async_todos = async_todos = deque()
+                await asyncio.gather(*(process_async_node(n, ctx) for n, ctx in current_async_todos))
 
         if self._error_boundary_todos:
             await asyncio.gather(
                 *(self._process_error_boundary(n, ctx) for n, ctx in self._error_boundary_todos)
             )
 
-        return "".join(node.component for node in self._root.iter_nodes())  # type: ignore[misc]
+        return "".join(node.component for node in self._root.iter_nodes() if node.component is not None)  # type: ignore[misc]
 
 
 async def _render_component(
@@ -269,6 +275,8 @@ class Renderer:
         """
         Renders the given component.
 
+        Implements `htmy.typing.RendererType`.
+
         Arguments:
             component: The component to render.
             context: An optional rendering context.

{htmy-0.7.0 → htmy-0.9.0}/htmy/snippet.py

@@ -1,9 +1,13 @@
+from __future__ import annotations
+
 import re
 from collections.abc import Awaitable, Iterator, Mapping
-from pathlib import Path
+from typing import TYPE_CHECKING
+
+from async_lru import alru_cache
 
 from .core import SafeStr, Text
-from .io import open_file
+from .io import load_text_file
 from .typing import (
     Component,
     ComponentType,
@@ -13,6 +17,9 @@ from .typing import (
 )
 from .utils import as_component_sequence, as_component_type, is_component_sequence
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
 # -- Components and utilities
 
 
@@ -151,6 +158,10 @@ class Snippet:
     """
     Component that renders text, which may be asynchronously loaded from a file.
 
+    **Warning:** The component treats its input as trusted. If any part of the input comes from
+    untrusted sources, ensure it is safely escaped (using for example `htmy.xml_format_string`)!
+    Passing untrusted input to this component leads to XSS vulnerabilities.
+
     The entire snippet processing pipeline consists of the following steps:
 
     1. The text content is loaded from a file or passed directly as a `Text` instance.
@@ -248,8 +259,7 @@ class Snippet:
         if isinstance(path_or_text, Text):
             return path_or_text
         else:
-            async with await open_file(path_or_text, "r") as f:
-                return await f.read()
+            return await Snippet._load_text_file(path_or_text)
 
     def _render_text(self, text: str, context: Context) -> Component:
         """
@@ -257,3 +267,9 @@ class Snippet:
         and returns the corresponding component.
         """
         return SafeStr(text)
+
+    @staticmethod
+    @alru_cache()
+    async def _load_text_file(path: str | Path) -> str:
+        """Async text loader with an LRU cache."""
+        return await load_text_file(path)

{htmy-0.7.0 → htmy-0.9.0}/htmy/typing.py

@@ -55,7 +55,10 @@ class AsyncComponent(Protocol):
 HTMYComponentType: TypeAlias = SyncComponent | AsyncComponent
 """Sync or async `htmy` component type."""
 
-ComponentType: TypeAlias = HTMYComponentType | str
+StrictComponentType: TypeAlias = HTMYComponentType | str
+"""Type definition for a single component that's not `None`."""
+
+ComponentType: TypeAlias = StrictComponentType | None
 """Type definition for a single component."""
 
 # Omit strings from this type to simplify checks.
@@ -65,6 +68,27 @@ ComponentSequence: TypeAlias = list[ComponentType] | tuple[ComponentType, ...]
 Component: TypeAlias = ComponentType | ComponentSequence
 """Component type: a single component or a sequence of components."""
 
+
+# -- Renderer
+
+
+class RendererType(Protocol):
+    """Protocol definition for `htmy` renderers."""
+
+    async def render(self, component: Component, context: Context | None = None) -> str:
+        """
+        Renders the given component.
+
+        Arguments:
+            component: The component to render.
+            context: An optional rendering context.
+
+        Returns:
+            The rendered string.
+        """
+        ...
+
+
 # -- Context providers
 
 

htmy-0.9.0/pyproject.toml

@@ -0,0 +1,87 @@
+[tool.poetry]
+name = "htmy"
+version = "0.9.0"
+description = "Async, pure-Python server-side rendering engine."
+authors = ["Peter Volf <do.volfp@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+anyio = "^4.6.2.post1"
+async-lru = "^2.0.4"
+markdown = "^3.8"
+lxml = { version = ">=6.0.0", optional = true }
+
+[tool.poetry.extras]
+lxml = ["lxml"]
+
+[tool.poetry.group.dev.dependencies]
+fastapi = "^0.116.0"
+fasthx = "^2.3.3"
+mkdocs-material = "^9.6.16"
+mkdocstrings = { extras = ["python"], version = "^0.30.0" }
+mypy = "^1.18.2"
+poethepoet = "^0.37.0"
+pytest = "^8.3.3"
+pytest-asyncio = "^0.24.0"
+pytest-random-order = "^1.1.1"
+ruff = "^0.14.4"
+types-markdown = "^3.8.0.20250809"
+typing-extensions = "^4.12.2"
+types-lxml = "^2025.3.30"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.mypy]
+strict = true
+show_error_codes = true
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+addopts = "--random-order"
+
+[tool.ruff]
+line-length = 108
+exclude = [
+    ".git",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".venv",
+    "dist",
+    "docs",
+]
+lint.select = [
+    "B", # flake8-bugbear
+    "C", # flake8-comprehensions
+    "E", # pycodestyle errors
+    "F", # pyflakes
+    "I", # isort
+    "S", # flake8-bandit - we must ignore these rules in tests
+    "W", # pycodestyle warnings
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*" = ["S101"] # S101: use of assert detected
+
+[tool.poe.tasks]
+format = "ruff format --check ."
+format-fix = "ruff format ."
+
+lint = "ruff check ."
+lint-fix = "ruff . --fix"
+
+mypy = "mypy ."
+
+check.sequence = ["format", "lint", "mypy"]
+check.ignore_fail = "return_non_zero"
+
+test = "python -m pytest tests"
+
+serve-docs = "mkdocs serve"

htmy-0.7.0/htmy/io.py

@@ -1 +0,0 @@
-from anyio import open_file as open_file

htmy-0.7.0/pyproject.toml

@@ -1,73 +0,0 @@
-[tool.poetry]
-name = "htmy"
-version = "0.7.0"
-description = "Async, pure-Python rendering engine."
-authors = ["Peter Volf <do.volfp@gmail.com>"]
-license = "MIT"
-readme = "README.md"
-
-[tool.poetry.dependencies]
-python = "^3.10"
-anyio = "^4.6.2.post1"
-async-lru = "^2.0.4"
-markdown = "^3.7"
-
-[tool.poetry.group.dev.dependencies]
-mkdocs-material = "^9.5.39"
-mkdocstrings = {extras = ["python"], version = "^0.26.1"}
-mypy = "^1.15.0"
-poethepoet = "^0.29.0"
-pytest = "^8.3.3"
-pytest-asyncio = "^0.24.0"
-pytest-random-order = "^1.1.1"
-ruff = "^0.9.0"
-types-markdown = "^3.7.0.20240822"
-typing-extensions = "^4.12.2"
-fastapi = "^0.115.8"
-fasthx = "^2.2.1"
-
-[build-system]
-requires = ["poetry-core"]
-build-backend = "poetry.core.masonry.api"
-
-[tool.mypy]
-strict = true
-show_error_codes = true
-
-[tool.pytest.ini_options]
-addopts = "--random-order"
-
-[tool.ruff]
-line-length = 108
-exclude = [
-    ".git",
-    ".mypy_cache",
-    ".pytest_cache",
-    ".ruff_cache",
-    ".venv",
-    "dist",
-    "docs",
-]
-lint.select = [
-    "B",  # flake8-bugbear
-    "C",  # flake8-comprehensions
-    "E",  # pycodestyle errors
-    "F",  # pyflakes
-    "I",  # isort
-    "S",  # flake8-bandit - we must ignore these rules in tests
-    "W",  # pycodestyle warnings
-]
-
-[tool.ruff.lint.per-file-ignores]
-"tests/**/*" = ["S101"]  # S101: use of assert detected
-
-[tool.poe.tasks]
-check-format = "ruff format --check ."
-format = "ruff format ."
-lint = "ruff check ."
-lint-fix = "ruff . --fix"
-mypy = "mypy ."
-test = "python -m pytest tests"
-static-checks.sequence = ["lint", "check-format", "mypy"]
-static-checks.ignore_fail = "return_non_zero"
-serve-docs = "mkdocs serve"