htmy 0.3.6__tar.gz → 0.4.0__tar.gz

{htmy-0.3.6 → htmy-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: htmy
-Version: 0.3.6
+Version: 0.4.0
 Summary: Async, pure-Python rendering engine.
 License: MIT
 Author: Peter Volf
@@ -170,16 +170,16 @@ user_table = html.table(
 
 ### Rendering
 
-`htmy.HTMY` is the built-in, default renderer of the library.
+`htmy.Renderer` is the built-in, default renderer of the library.
 
-If you're using the library in an async web framework like [FastAPI](https://fastapi.tiangolo.com/), then you're already in an async environment, so you can render components as simply as this: `await HTMY().render(my_root_component)`.
+If you're using the library in an async web framework like [FastAPI](https://fastapi.tiangolo.com/), then you're already in an async environment, so you can render components as simply as this: `await Renderer().render(my_root_component)`.
 
 If you're trying to run the renderer in a sync environment, like a local script or CLI, then you first need to wrap the renderer in an async task and execute that task with `asyncio.run()`:
 
 ```python
 import asyncio
 
-from htmy import HTMY, html
+from htmy import Renderer, html
 
 async def render_page() -> None:
     page = (
@@ -192,7 +192,7 @@ async def render_page() -> None:
         )
     )
 
-    result = await HTMY().render(page)
+    result = await Renderer().render(page)
     print(result)
 
 
@@ -213,7 +213,7 @@ Here's an example context provider and consumer implementation:
 ```python
 import asyncio
 
-from htmy import HTMY, Component, ComponentType, Context, component, html
+from htmy import Component, ComponentType, Context, Renderer, component, html
 
 class UserContext:
     def __init__(self, *children: ComponentType, username: str, theme: str) -> None:
@@ -259,7 +259,7 @@ async def render_welcome_page() -> None:
         theme="dark",
     )
 
-    result = await HTMY().render(page)
+    result = await Renderer().render(page)
     print(result)
 
 if __name__ == "__main__":
@@ -270,7 +270,7 @@ You can of course rely on the built-in context related utilities like the `Conte
 
 ### Formatter
 
-As mentioned before, the built-in `Formatter` class is responsible for tag attribute name and value formatting. You can completely override or extend the built-in formatting behavior simply by extending this class or adding new rules to an instance of it, and then adding the custom instance to the context, either directly in `HTMY` or `HTMY.render()`, or in a context provider component.
+As mentioned before, the built-in `Formatter` class is responsible for tag attribute name and value formatting. You can completely override or extend the built-in formatting behavior simply by extending this class or adding new rules to an instance of it, and then adding the custom instance to the context, either directly in `Renderer` or `Renderer.render()`, or in a context provider component.
 
 These are default tag attribute formatting rules:
 

{htmy-0.3.6 → htmy-0.4.0}/README.md

@@ -151,16 +151,16 @@ user_table = html.table(
 
 ### Rendering
 
-`htmy.HTMY` is the built-in, default renderer of the library.
+`htmy.Renderer` is the built-in, default renderer of the library.
 
-If you're using the library in an async web framework like [FastAPI](https://fastapi.tiangolo.com/), then you're already in an async environment, so you can render components as simply as this: `await HTMY().render(my_root_component)`.
+If you're using the library in an async web framework like [FastAPI](https://fastapi.tiangolo.com/), then you're already in an async environment, so you can render components as simply as this: `await Renderer().render(my_root_component)`.
 
 If you're trying to run the renderer in a sync environment, like a local script or CLI, then you first need to wrap the renderer in an async task and execute that task with `asyncio.run()`:
 
 ```python
 import asyncio
 
-from htmy import HTMY, html
+from htmy import Renderer, html
 
 async def render_page() -> None:
     page = (
@@ -173,7 +173,7 @@ async def render_page() -> None:
         )
     )
 
-    result = await HTMY().render(page)
+    result = await Renderer().render(page)
     print(result)
 
 
@@ -194,7 +194,7 @@ Here's an example context provider and consumer implementation:
 ```python
 import asyncio
 
-from htmy import HTMY, Component, ComponentType, Context, component, html
+from htmy import Component, ComponentType, Context, Renderer, component, html
 
 class UserContext:
     def __init__(self, *children: ComponentType, username: str, theme: str) -> None:
@@ -240,7 +240,7 @@ async def render_welcome_page() -> None:
         theme="dark",
     )
 
-    result = await HTMY().render(page)
+    result = await Renderer().render(page)
     print(result)
 
 if __name__ == "__main__":
@@ -251,7 +251,7 @@ You can of course rely on the built-in context related utilities like the `Conte
 
 ### Formatter
 
-As mentioned before, the built-in `Formatter` class is responsible for tag attribute name and value formatting. You can completely override or extend the built-in formatting behavior simply by extending this class or adding new rules to an instance of it, and then adding the custom instance to the context, either directly in `HTMY` or `HTMY.render()`, or in a context provider component.
+As mentioned before, the built-in `Formatter` class is responsible for tag attribute name and value formatting. You can completely override or extend the built-in formatting behavior simply by extending this class or adding new rules to an instance of it, and then adding the custom instance to the context, either directly in `Renderer` or `Renderer.render()`, or in a context provider component.
 
 These are default tag attribute formatting rules:
 

{htmy-0.3.6 → htmy-0.4.0}/htmy/__init__.py

@@ -15,7 +15,7 @@ from .core import WithContext as WithContext
 from .core import XBool as XBool
 from .core import component as component
 from .core import xml_format_string as xml_format_string
-from .renderer import HTMY as HTMY
+from .renderer import Renderer as Renderer
 from .typing import AsyncComponent as AsyncComponent
 from .typing import AsyncContextProvider as AsyncContextProvider
 from .typing import AsyncFunctionComponent as AsyncFunctionComponent
@@ -36,3 +36,6 @@ from .typing import SyncContextProvider as SyncContextProvider
 from .typing import SyncFunctionComponent as SyncFunctionComponent
 from .typing import is_component_sequence as is_component_sequence
 from .utils import join_components as join_components
+
+HTMY = Renderer
+"""Deprecated alias for `Renderer`."""

{htmy-0.3.6 → htmy-0.4.0}/htmy/core.py

@@ -122,7 +122,7 @@ class WithContext(Fragment):
         self._context = context
 
     def htmy_context(self) -> Context:
-        """Returns an HTMY context for child rendering."""
+        """Returns the context for child rendering."""
         return self._context
 
 
@@ -174,7 +174,7 @@ class Snippet:
     def _render_text(self, text: str, context: Context) -> Component:
         """
         Render function that takes the text that must be rendered and the current rendering context,
-        and returns the corresponding HTMY component.
+        and returns the corresponding component.
         """
         return SafeStr(text)
 
@@ -523,7 +523,7 @@ class BaseTag(abc.ABC):
 
     @abc.abstractmethod
     def htmy(self, context: Context) -> Component:
-        """Abstract base method for HTMY rendering."""
+        """Abstract base component implementation."""
         ...
 
     def _get_htmy_name(self) -> str:

{htmy-0.3.6 → htmy-0.4.0}/htmy/etree.py

@@ -17,7 +17,7 @@ from htmy.core import Fragment, SafeStr, WildcardTag
 
 class ETreeConverter:
     """
-    Utility for converting XML strings to custom HTMY components.
+    Utility for converting XML strings to custom components.
     """
 
     __slots__ = ("_rules",)
@@ -33,12 +33,12 @@ class ETreeConverter:
         Initialization.
 
         Arguments:
-            rules: Tag-name to HTMY component conversion rules.
+            rules: Tag-name to component conversion rules.
         """
         self._rules = rules
 
     def convert(self, element: str) -> ComponentType:
-        """Converts the given (possible multi-root) XML string to an HTMY component."""
+        """Converts the given (possibly multi-root) XML string to a component."""
         if len(self._rules) == 0:
             return SafeStr(element)
 
@@ -46,7 +46,7 @@ class ETreeConverter:
         return self.convert_element(ET.fromstring(element))  # noqa: S314 # Only use from XML strings from a trusted source.
 
     def convert_element(self, element: Element) -> ComponentType:
-        """Converts the given `Element` to an HTMY component."""
+        """Converts the given `Element` to a component."""
         rules = self._rules
         if len(rules) == 0:
             return SafeStr(ET.tostring(element))
@@ -67,7 +67,7 @@ class ETreeConverter:
 
     def _convert_properties(self, element: Element) -> Properties:
         """
-        Converts the attributes of the given `Element` to an HTMY `Properties` mapping.
+        Converts the attributes of the given `Element` to a `Properties` mapping.
 
         This method should not alter property names in any way.
         """
@@ -75,8 +75,8 @@ class ETreeConverter:
 
     def _convert_children(self, element: Element) -> Generator[ComponentType, None, None]:
         """
-        Generator that converts all (text and `Element`) children of the given `Element`
-        into an HTMY component."""
+        Generator that converts all (text and `Element`) children of the given `Element` to a component.
+        """
         if text := self._process_text(element.text):
             yield text
 

{htmy-0.3.6 → htmy-0.4.0}/htmy/md/core.py

@@ -99,9 +99,9 @@ class MD(Snippet):
         Arguments:
             path_or_text: The path where the markdown file is located or a markdown `Text`.
             converter: Function that converts an HTML string (the parsed and processed markdown text)
-                into an HTMY component.
-            renderer: Function that get the parsed and converted content and the metadata (if it exists)
-                and turns them into an HTMY component.
+                into a component.
+            renderer: Function that gets the parsed and converted content and the metadata (if it exists)
+                and turns them into a component.
             text_processor: An optional text processors that can be used to process the text
                 content before rendering. It can be used for example for token replacement or
                 string formatting.

htmy-0.4.0/htmy/renderer/__init__.py

@@ -0,0 +1,8 @@
+from .baseline import Renderer as _BaselineRenderer
+from .default import Renderer as _DefaultRenderer
+
+Renderer = _DefaultRenderer
+"""The default renderer."""
+
+BaselineRenderer = _BaselineRenderer
+"""The baseline renderer."""

htmy-0.3.6/htmy/renderer.py → htmy-0.4.0/htmy/renderer/baseline.py

@@ -4,12 +4,21 @@ import asyncio
 from collections import ChainMap
 from collections.abc import Awaitable, Callable, Iterable
 
-from .core import ErrorBoundary, xml_format_string
-from .typing import Component, ComponentType, Context
+from htmy.core import ErrorBoundary, xml_format_string
+from htmy.typing import Component, ComponentType, Context
 
 
-class HTMY:
-    """HTMY component renderer."""
+class Renderer:
+    """
+    The baseline component renderer.
+
+    Because of the simple, recursive implementation, this renderer is the easiest to reason about.
+    Therefore it is useful for validating component correctness before bug reporting (if another
+    renderer implementation fails), testing and debugging alternative implementations, and it can
+    also serve as the baseline for benchmarking optimized renderers.
+
+    The performance of this renderer is not production quality.
+    """
 
     __slots__ = ("_default_context", "_string_formatter")
 

htmy-0.4.0/htmy/renderer/default.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+import asyncio
+from collections import ChainMap, deque
+from collections.abc import Awaitable, Callable, Iterator
+from typing import TypeAlias
+
+from htmy.core import ErrorBoundary, xml_format_string
+from htmy.typing import Component, ComponentType, Context, ContextProvider, is_component_sequence
+
+
+class _Node:
+    """A single node in the linked list the renderer constructs to resolve a component tree."""
+
+    __slots__ = ("component", "next")
+
+    def __init__(self, component: ComponentType, next: _Node | None = None) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            component: The component in this node.
+            next: The next component in the list, if there is one.
+        """
+        self.component = component
+        self.next = next
+
+    def iter_nodes(self, *, include_self: bool = True) -> Iterator[_Node]:
+        """
+        Iterates over all following nodes.
+
+        Arguments:
+            include_self: Whether the node on which this method is called should also
+                be included in the iterator.
+        """
+        current = self if include_self else self.next
+        while current is not None:
+            yield current
+            current = current.next
+
+
+_NodeAndChildContext: TypeAlias = tuple[_Node, Context]
+
+
+class _ComponentRenderer:
+    """
+    `ComponentType` renderer that converts a component tree into a linked list of resolved (`str`) nodes.
+    """
+
+    __slots__ = ("_async_todos", "_error_boundary_todos", "_sync_todos", "_root", "_string_formatter")
+
+    def __init__(
+        self,
+        component: ComponentType,
+        context: Context,
+        *,
+        string_formatter: Callable[[str], str],
+    ) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            component: The component to render.
+            context: The base context to use for rendering the component.
+            string_formatter: The string formatter to use.
+        """
+        self._async_todos: deque[_NodeAndChildContext] = deque()
+        """Async node - context tuples that need to be rendered."""
+        self._error_boundary_todos: deque[_NodeAndChildContext] = deque()
+        """Node context tuples where `node.component` is an `ErrorBoundary`."""
+        self._sync_todos: deque[_NodeAndChildContext] = deque()
+        """
+        Sync node - context tuples that need to be rendered (`node.component` is an `HTMYComponentType`).
+        """
+        self._string_formatter = string_formatter
+        """The string formatter to use."""
+
+        if isinstance(component, str):
+            root = _Node(string_formatter(component), None)
+        else:
+            root = _Node(component, None)
+            self._schedule_node(root, context)
+        self._root = root
+        """The root node in the linked list the renderer constructs."""
+
+    async def _extend_context(self, component: ContextProvider, context: Context) -> Context:
+        """
+        Returns a new context from the given component and context.
+
+        Arguments:
+            component: A `ContextProvider` component.
+            context: The current rendering context.
+        """
+        extra_context: Context | Awaitable[Context] = component.htmy_context()
+        if isinstance(extra_context, Awaitable):
+            extra_context = await extra_context
+
+        return (
+            # Context must not be mutated. We can ignore that ChainMap expects mutable mappings.
+            ChainMap(extra_context, context)  # type: ignore[arg-type]
+            if extra_context
+            else context
+        )
+
+    async def _process_error_boundary(self, node: _Node, context: Context) -> None:
+        """
+        Processes a single node whose component is an `ErrorBoundary`.
+        """
+        component: ErrorBoundary = node.component  # type: ignore[assignment]
+        if hasattr(component, "htmy_context"):  # isinstance() is too expensive.
+            context = await self._extend_context(component, context)
+
+        try:
+            result = await _render_component(
+                component.htmy(context),
+                context=context,
+                string_formatter=self._string_formatter,
+            )
+        except Exception as e:
+            renderer = _ComponentRenderer(
+                component.fallback_component(e),
+                context,
+                string_formatter=self._string_formatter,
+            )
+            result = await renderer.run()
+
+        node.component = result  # No string formatting.
+
+    def _process_node_result(self, parent_node: _Node, component: Component, context: Context) -> None:
+        """
+        Processes the result of a single node.
+
+        Arguments:
+            parent_node: The node that was resolved.
+            component: The (awaited if async) result of `parent_node.component.htmy()`.
+            context: The context that was used for rendering `parent_node.component`.
+        """
+        schedule_node = self._schedule_node
+        string_formatter = self._string_formatter
+        if is_component_sequence(component):
+            if len(component) == 0:
+                parent_node.component = ""
+                return
+
+            first_comp, *rest_comps = component
+            if isinstance(first_comp, str):
+                parent_node.component = string_formatter(first_comp)
+            else:
+                parent_node.component = first_comp
+                schedule_node(parent_node, context)
+
+            old_next = parent_node.next
+            last: _Node = parent_node
+            for c in rest_comps:
+                if isinstance(c, str):
+                    node = _Node(string_formatter(c), old_next)
+                else:
+                    node = _Node(c, old_next)
+                    schedule_node(node, context)
+
+                last.next = node
+                last = node
+        elif isinstance(component, str):
+            parent_node.component = string_formatter(component)
+        else:
+            parent_node.component = component  # type: ignore[assignment]
+            schedule_node(parent_node, context)
+
+    async def _process_async_node(self, node: _Node, context: Context) -> None:
+        """
+        Processes the given node. `node.component` must be an async component.
+        """
+        result = await node.component.htmy(context)  # type: ignore[misc,union-attr]
+        self._process_node_result(node, result, context)
+
+    def _schedule_node(self, node: _Node, child_context: Context) -> None:
+        """
+        Schedules the given node for rendering with the given child context.
+
+        `node.component` must be an `HTMYComponentType` (single component and not `str`).
+        """
+        component = node.component
+        if 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))
+        else:
+            self._sync_todos.append((node, child_context))
+
+    async def run(self) -> str:
+        """Runs the component renderer."""
+        async_todos = self._async_todos
+        sync_todos = self._sync_todos
+        process_node_result = self._process_node_result
+        process_async_node = self._process_async_node
+
+        while sync_todos or async_todos:
+            while sync_todos:
+                node, child_context = sync_todos.pop()
+                component = node.component
+                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]
+                    async_todos.append((node, child_context))
+                else:
+                    result: Component = node.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()
+
+        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]
+
+
+async def _render_component(
+    component: Component,
+    *,
+    context: Context,
+    string_formatter: Callable[[str], str],
+) -> str:
+    """Renders the given component with the given settings."""
+    if is_component_sequence(component):
+        if len(component) == 0:
+            return ""
+
+        renderers = (_ComponentRenderer(c, context, string_formatter=string_formatter) for c in component)
+        return "".join(await asyncio.gather(*(r.run() for r in renderers)))
+    else:
+        return await _ComponentRenderer(component, context, string_formatter=string_formatter).run()  # type: ignore[arg-type]
+
+
+class Renderer:
+    """
+    The default renderer.
+
+    It resolves component trees by converting them to a linked list of resolved component parts
+    before combining them to the final string.
+    """
+
+    __slots__ = ("_default_context", "_string_formatter")
+
+    def __init__(
+        self,
+        default_context: Context | None = None,
+        *,
+        string_formatter: Callable[[str], str] = xml_format_string,
+    ) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            default_context: The default context to use for rendering if `render()` doesn't
+                receive a context.
+            string_formatter: Callable that should be used to format plain strings. By default
+                an XML-safe string formatter will be used.
+        """
+        self._default_context: Context = {} if default_context is None else default_context
+        self._string_formatter = string_formatter
+
+    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.
+        """
+        # Type ignore: ChainMap expects mutable mappings, but context mutation is not allowed so don't care.
+        context = (
+            self._default_context if context is None else ChainMap(context, self._default_context)  # type: ignore[arg-type]
+        )
+        return await _render_component(component, context=context, string_formatter=self._string_formatter)

{htmy-0.3.6 → htmy-0.4.0}/htmy/typing.py

@@ -88,7 +88,7 @@ class SyncContextProvider(Protocol):
     """Protocol definition for sync context providers."""
 
     def htmy_context(self) -> Context:
-        """Returns an HTMY context for child rendering."""
+        """Returns a context for child rendering."""
         ...
 
 
@@ -97,7 +97,7 @@ class AsyncContextProvider(Protocol):
     """Protocol definition for async context providers."""
 
     async def htmy_context(self) -> Context:
-        """Returns an HTMY context for child rendering."""
+        """Returns a context for child rendering."""
         ...
 
 

{htmy-0.3.6 → htmy-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "htmy"
-version = "0.3.6"
+version = "0.4.0"
 description = "Async, pure-Python rendering engine."
 authors = ["Peter Volf <do.volfp@gmail.com>"]
 license = "MIT"
@@ -47,13 +47,13 @@ exclude = [
     "docs",
 ]
 lint.select = [
+    "B",  # flake8-bugbear
+    "C",  # flake8-comprehensions
     "E",  # pycodestyle errors
-    "W",  # pycodestyle warnings
     "F",  # pyflakes
     "I",  # isort
     "S",  # flake8-bandit - we must ignore these rules in tests
-    "C",  # flake8-comprehensions
-    "B",  # flake8-bugbear
+    "W",  # pycodestyle warnings
 ]
 
 [tool.ruff.lint.per-file-ignores]