htmy 0.8.2__py3-none-any.whl → 0.9.0__py3-none-any.whl

htmy/__init__.py

@@ -31,12 +31,16 @@ 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/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/renderer/baseline.py

@@ -73,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.
 
@@ -95,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/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,13 +201,16 @@ 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:
@@ -218,7 +223,7 @@ class _ComponentRenderer:
                 *(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(

htmy/snippet.py

@@ -158,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.

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.

{htmy-0.8.2.dist-info → htmy-0.9.0.dist-info}/METADATA

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: htmy
-Version: 0.8.2
+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
@@ -12,6 +13,7 @@ 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)
@@ -36,7 +38,7 @@ Unleash your creativity with the full power and Python, without the hassle of le
 
 ## 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.
@@ -47,6 +49,7 @@ 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
@@ -323,11 +326,35 @@ 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
 

{htmy-0.8.2.dist-info → htmy-0.9.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-htmy/__init__.py,sha256=h1UOBOdcmwzkelpu2uGZXkXO_XLtXYiU6pW1-3kCj7k,1929
+htmy/__init__.py,sha256=YPl0qVUFQpkISXYkXTCpnWnqnHUdfATmHPu9L3pW5FA,2037
 htmy/core.py,sha256=mvNbxTRS8HNnjMSwe4NEJdL1KF19pJImF4Ciip6837I,15484
 htmy/etree.py,sha256=3znZCYQ5xbNqyXYSYFkUh6M22QLWMYWhTNjUcgpjCLc,4051
 htmy/function_component.py,sha256=iSp5cGrErmIsc-VfNq053_J2m-Nuu_k2xK9UxvEnlw8,12431
@@ -6,16 +6,16 @@ htmy/html.py,sha256=Pw9KCSn0X01D_fwIpcckI9nsQWNJMiYbcqQH0q2ezuM,21276
 htmy/i18n.py,sha256=Kobvm9mFoNcJas52KQbheiRIzJF1Ad1azOhtfm_k0BE,5123
 htmy/io.py,sha256=oEXXVnpdbjs2NzAGi36Pept-pyvXshEGHrbBFzcHYio,344
 htmy/md/__init__.py,sha256=lxBJnYplkDuxYuiese6My9KYp1DeGdzo70iUdYTvMnE,334
-htmy/md/core.py,sha256=Xu-8xGAOGqSYLGPOib0Wn-blmyQBHl3MrAOza_w__Y8,4456
+htmy/md/core.py,sha256=jkgI78otXg7VmjmgeCpyjsNi0E-CqUnKYNVWVt3Sbcs,4729
 htmy/md/typing.py,sha256=LF-AEvo7FCW2KumyR5l55rsXizV2E4AHVLKFf6lApgM,762
 htmy/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 htmy/renderer/__init__.py,sha256=xnP_aaoK-pTok-69wi8O_xlsgjoKTzWd2lIIeHGcuaY,226
-htmy/renderer/baseline.py,sha256=1cE06kEqU_fNXWIo_3Hea88BOwL37NmfY5nnQnYEYqY,4336
-htmy/renderer/default.py,sha256=kFfgWPF7I3h7EmIDZamVeDNvI6ngnxfLIAnMUsWiMas,10917
-htmy/snippet.py,sha256=9-ltfs4rugv6kFNzAY0PYNP3YI3xvJG8lkxEnYcCYWw,10538
-htmy/typing.py,sha256=kRi_rkQQ5CNL1TyUhEVHjTh96zHpBZlNxqr2TTTfyzI,3546
+htmy/renderer/baseline.py,sha256=WrKO5cQpvF5AFUuFoEoAS8_lUqTg51m8hkolq9-Uetw,4519
+htmy/renderer/default.py,sha256=n1nAbU4cCtA26rng5D2T4oIjHVSPjRK5GCphJ8NFPmA,11076
+htmy/snippet.py,sha256=Lo99zoIzU8n-qO2-10d8tX_J8SCEmEBpQWdYR0AVsZM,10808
+htmy/typing.py,sha256=qgOj8nZmemzSEQzNRib9tT3l7LETvajOyLkxveA6nss,3671
 htmy/utils.py,sha256=Kp0j9G8CBeRiyFGmz-CoDiLtXHfpvHzlTVsWeDhIebM,1935
-htmy-0.8.2.dist-info/LICENSE,sha256=rFtoGU_3c_rlacXgOZapTHfMErN-JFPT5Bq_col4bqI,1067
-htmy-0.8.2.dist-info/METADATA,sha256=sro_ZXPlLpQbnZmDfQ-RhRwce2Gg77nrZQhNAJTUUc4,20123
-htmy-0.8.2.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-htmy-0.8.2.dist-info/RECORD,,
+htmy-0.9.0.dist-info/METADATA,sha256=aX7JtrXXJTD4bDExa3W08orerBX3J98hI7k3l0nJiMs,22267
+htmy-0.9.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+htmy-0.9.0.dist-info/licenses/LICENSE,sha256=ulLk8GOf1aK1cTSWjx5Hw1C4r_FtcgL4NSXs48zam5M,1067
+htmy-0.9.0.dist-info/RECORD,,

{htmy-0.8.2.dist-info → htmy-0.9.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.3
+Generator: poetry-core 2.2.1
 Root-Is-Purelib: true
 Tag: py3-none-any

{htmy-0.8.2.dist-info → htmy-0.9.0.dist-info/licenses}/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