htmy 0.4.2__tar.gz → 0.5.0__tar.gz

{htmy-0.4.2 → htmy-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: htmy
-Version: 0.4.2
+Version: 0.5.0
 Summary: Async, pure-Python rendering engine.
 License: MIT
 Author: Peter Volf
@@ -36,6 +36,7 @@ Description-Content-Type: text/markdown
 - **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.
+- Support for **native HTML/XML** documents with dynamic formatting and **slot rendering**.
 - **Markdown** support with tools for customization.
 - Async, JSON based **internationalization**.
 - Built-in, easy to use `ErrorBoundary` component for graceful error handling.
@@ -161,11 +162,11 @@ user_table = html.table(
 `htmy` has a rich set of built-in utilities and components for both HTML and other use-cases:
 
 - `html` module: a complete set of [baseline HTML tags](https://developer.mozilla.org/en-US/docs/Glossary/Baseline/Compatibility).
+- `Snippet` and `Slots`: utilities for creating dynamic, customizable document snippets in their native file format (HTML, XML, Markdown, etc.), with slot rendering support.
 - `md`: `MarkdownParser` utility and `MD` component for loading, parsing, converting, and rendering markdown content.
 - `i18n`: utilities for async, JSON based internationalization.
 - `BaseTag`, `TagWithProps`, `Tag`, `WildcardTag`: base classes for custom XML tags.
 - `ErrorBoundary`, `Fragment`, `SafeStr`, `WithContext`: utilities for error handling, component wrappers, context providers, and formatting.
-- `Snippet`: utility class for loading and customizing document snippets from the file system.
 - `etree.ETreeConverter`: utility that converts XML to a component tree with support for custom HTMY components.
 
 ### Rendering

{htmy-0.4.2 → htmy-0.5.0}/README.md

@@ -17,6 +17,7 @@
 - **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.
+- Support for **native HTML/XML** documents with dynamic formatting and **slot rendering**.
 - **Markdown** support with tools for customization.
 - Async, JSON based **internationalization**.
 - Built-in, easy to use `ErrorBoundary` component for graceful error handling.
@@ -142,11 +143,11 @@ user_table = html.table(
 `htmy` has a rich set of built-in utilities and components for both HTML and other use-cases:
 
 - `html` module: a complete set of [baseline HTML tags](https://developer.mozilla.org/en-US/docs/Glossary/Baseline/Compatibility).
+- `Snippet` and `Slots`: utilities for creating dynamic, customizable document snippets in their native file format (HTML, XML, Markdown, etc.), with slot rendering support.
 - `md`: `MarkdownParser` utility and `MD` component for loading, parsing, converting, and rendering markdown content.
 - `i18n`: utilities for async, JSON based internationalization.
 - `BaseTag`, `TagWithProps`, `Tag`, `WildcardTag`: base classes for custom XML tags.
 - `ErrorBoundary`, `Fragment`, `SafeStr`, `WithContext`: utilities for error handling, component wrappers, context providers, and formatting.
-- `Snippet`: utility class for loading and customizing document snippets from the file system.
 - `etree.ETreeConverter`: utility that converts XML to a component tree with support for custom HTMY components.
 
 ### Rendering

{htmy-0.4.2 → htmy-0.5.0}/htmy/__init__.py

@@ -5,7 +5,6 @@ from .core import Formatter as Formatter
 from .core import Fragment as Fragment
 from .core import SafeStr as SafeStr
 from .core import SkipProperty as SkipProperty
-from .core import Snippet as Snippet
 from .core import Tag as Tag
 from .core import TagConfig as TagConfig
 from .core import TagWithProps as TagWithProps
@@ -16,6 +15,8 @@ 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 Renderer as Renderer
+from .snippet import Slots as Slots
+from .snippet import Snippet as Snippet
 from .typing import AsyncComponent as AsyncComponent
 from .typing import AsyncContextProvider as AsyncContextProvider
 from .typing import AsyncFunctionComponent as AsyncFunctionComponent
@@ -34,7 +35,9 @@ from .typing import PropertyValue as PropertyValue
 from .typing import SyncComponent as SyncComponent
 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 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_components as join_components
 
 HTMY = Renderer

{htmy-0.4.2 → htmy-0.5.0}/htmy/core.py

@@ -3,13 +3,11 @@ from __future__ import annotations
 import abc
 import asyncio
 import enum
-from collections.abc import Awaitable, Callable, Container
-from pathlib import Path
+from collections.abc import Callable, Container
 from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypedDict, cast, overload
 from xml.sax.saxutils import escape as xml_escape
 from xml.sax.saxutils import quoteattr as xml_quoteattr
 
-from .io import open_file
 from .typing import (
     AsyncFunctionComponent,
     Component,
@@ -21,10 +19,8 @@ from .typing import (
     PropertyValue,
     SyncFunctionComponent,
     T,
-    TextProcessor,
-    is_component_sequence,
 )
-from .utils import join_components
+from .utils import as_component_type, join_components
 
 if TYPE_CHECKING:
     from typing_extensions import Never, Self
@@ -97,11 +93,7 @@ class ErrorBoundary(Fragment):
         if not (self._errors is None or any(e in self._errors for e in type(error).mro())):
             raise error
 
-        return (
-            Fragment(*self._fallback)
-            if is_component_sequence(self._fallback)
-            else cast(ComponentType, self._fallback)
-        )
+        return as_component_type(self._fallback)
 
 
 class WithContext(Fragment):
@@ -127,59 +119,6 @@ class WithContext(Fragment):
         return self._context
 
 
-class Snippet:
-    """
-    Base component that can load its content from a file.
-    """
-
-    __slots__ = ("_path_or_text", "_text_processor")
-
-    def __init__(
-        self,
-        path_or_text: Text | str | Path,
-        *,
-        text_processor: TextProcessor | None = None,
-    ) -> None:
-        """
-        Initialization.
-
-        Arguments:
-            path_or_text: The path from where the content should be loaded or a `Text`
-                instance if this value should be rendered directly.
-            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.
-        """
-        self._path_or_text = path_or_text
-        self._text_processor = text_processor
-
-    async def htmy(self, context: Context) -> Component:
-        """Renders the component."""
-        text = await self._get_text_content()
-        if self._text_processor is not None:
-            processed = self._text_processor(text, context)
-            text = (await processed) if isinstance(processed, Awaitable) else processed
-
-        return self._render_text(text, context)
-
-    async def _get_text_content(self) -> str:
-        """Returns the plain text content that should be rendered."""
-        path_or_text = self._path_or_text
-
-        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()
-
-    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 component.
-        """
-        return SafeStr(text)
-
-
 # -- Context utilities
 
 

{htmy-0.4.2 → htmy-0.5.0}/htmy/md/core.py

@@ -4,8 +4,9 @@ from typing import TYPE_CHECKING, ClassVar
 
 from markdown import Markdown
 
-from htmy.core import ContextAware, SafeStr, Snippet, Text
-from htmy.typing import TextProcessor
+from htmy.core import ContextAware, SafeStr, Text
+from htmy.snippet import Snippet
+from htmy.typing import TextProcessor, TextResolver
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -78,7 +79,17 @@ class MarkdownParser(ContextAware):
 
 
 class MD(Snippet):
-    """Component for reading, customizing, and rendering markdown documents."""
+    """
+    Component for reading, customizing, and rendering markdown documents.
+
+    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,
+    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.
+    """
 
     __slots__ = (
         "_converter",
@@ -88,6 +99,7 @@ class MD(Snippet):
     def __init__(
         self,
         path_or_text: Text | str | Path,
+        text_resolver: TextResolver | None = None,
         *,
         converter: Callable[[str], Component] | None = None,
         renderer: MarkdownRenderFunction | None = None,
@@ -98,6 +110,8 @@ class MD(Snippet):
 
         Arguments:
             path_or_text: The path where the markdown file is located or a markdown `Text`.
+            text_resolver: An optional `TextResolver` (e.g. `Slots`) that converts the processed
+                text into a component.
             converter: Function that converts an HTML string (the parsed and processed markdown text)
                 into a component.
             renderer: Function that gets the parsed and converted content and the metadata (if it exists)
@@ -106,7 +120,7 @@ class MD(Snippet):
                 content before rendering. It can be used for example for token replacement or
                 string formatting.
         """
-        super().__init__(path_or_text, text_processor=text_processor)
+        super().__init__(path_or_text, text_resolver, text_processor=text_processor)
         self._converter: Callable[[str], Component] = SafeStr if converter is None else converter
         self._renderer = renderer
 

{htmy-0.4.2 → htmy-0.5.0}/htmy/renderer/default.py

@@ -6,7 +6,8 @@ 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
+from htmy.typing import Component, ComponentType, Context, ContextProvider
+from htmy.utils import is_component_sequence
 
 
 class _Node:

htmy-0.5.0/htmy/snippet.py

@@ -0,0 +1,259 @@
+import re
+from collections.abc import Awaitable, Iterator, Mapping
+from pathlib import Path
+
+from .core import SafeStr, Text
+from .io import open_file
+from .typing import (
+    Component,
+    ComponentType,
+    Context,
+    TextProcessor,
+    TextResolver,
+)
+from .utils import as_component_sequence, as_component_type, is_component_sequence
+
+# -- Components and utilities
+
+
+class Slots:
+    """
+    Utility that resolves slots in a string input to components.
+
+    More technically, it splits a string into slot and non-slot parts, replaces the
+    slot parts with the corresponding components (which may be component sequences)
+    from the given slot mapping, and returns the resulting component sequence.
+
+    The default slot placeholder is a standard XML/HTML comment of the following form:
+    `<!-- slot[slot-key] -->`. Any number of whitespaces (including 0) are allowed in
+    the placeholder, but the slot key must not contain any whitespaces. For details, see
+    `Slots.slot_re`.
+
+    Besides the pre-defined regular expressions in `Slots.slot_re`, any other regular
+    expression can be used to identify slots as long as it meets the requirements described
+    in `Slots.slots_re`.
+
+    Implements: `htmy.typing.TextResolver`
+    """
+
+    __slots__ = ("_slot_mapping", "_slot_re", "_not_found")
+
+    class slot_re:
+        """
+        Slot regular expressions.
+
+        Requirements:
+
+        - The regular expression must have exactly one capturing group that captures the slot key.
+        """
+
+        square_bracket = re.compile(r"<!-- *slot *\[ *([^[ ]+) *\] *-->")
+        """
+        Slot regular expression that matches slots defined as follows: `<!-- slot[slot-key] -->`.
+
+        The slot key must not contain any whitespaces and there must not be any additional text
+        in the XML/HTML comment. Any number of whitespaces (including 0) are allowed around the
+        parts of the slot placeholder.
+        """
+        parentheses = re.compile(r"<!-- *slot *\( *([^( ]+) *\) *-->")
+        """
+        Slot regular expression that matches slots defined as follows: `<!-- slot(slot-key) -->`.
+
+        The slot key must not contain any whitespaces and there must not be any additional text
+        in the XML/HTML comment. Any number of whitespaces (including 0) are allowed around the
+        parts of the slot placeholder.
+        """
+
+        # There are no defaults for angle bracket and curly braces, because
+        # they may conflict with HTML and format strings.
+
+        default = square_bracket
+        """
+        The default slot regular expression. Same as `Slots.slot_re.square_bracket`.
+        """
+
+    def __init__(
+        self,
+        slot_mapping: Mapping[str, Component],
+        *,
+        slot_re: re.Pattern[str] = slot_re.default,
+        not_found: Component | None = None,
+    ) -> None:
+        """
+        Initialization.
+
+        Slot regular expressions are used to find slot keys in strings, which are then replaced
+        with the corresponding component from the slot mapping. `slot_re` must have exactly one
+        capturing group that captures the slot key. `Slots.slot_re` contains some predefined slot
+        regular expressions, but any other regular expression can be used as long as it matches
+        the capturing group requirement above.
+
+        Arguments:
+            slot_mapping: Slot mapping the maps slot keys to the corresponding component.
+            slot_re: The slot regular expression that is used to find slot keys in strings.
+            not_found: The component that is used to replace slot keys that are not found in
+                `slot_mapping`. If `None` and the slot key is not found in `slot_mapping`,
+                then a `KeyError` will be raised by `resolve()`.
+        """
+        self._slot_mapping = slot_mapping
+        self._slot_re = slot_re
+        self._not_found = not_found
+
+    def resolve_text(self, text: str) -> Component:
+        """
+        Resolves the given string into components using the instance's slot regular expression
+        and slot mapping.
+
+        Arguments:
+            text: The text to resolve.
+
+        Returns:
+           The component sequence the text resolves to.
+
+        Raises:
+            KeyError: If a slot key is not found in the slot mapping and `not_found` is `None`.
+        """
+        return tuple(self._resolve_text(text))
+
+    def _resolve_text(self, text: str) -> Iterator[ComponentType]:
+        """
+        Generator that yields the slot and non-slot parts of the given string in order.
+
+        Arguments:
+            text: The text to resolve.
+
+        Yields:
+            The slot and non-slot parts of the given string.
+
+        Raises:
+            KeyError: If a slot key is not found in the slot mapping and `not_found` is `None`.
+        """
+        is_slot = False
+        # The implementation requires that the slot regular expression has exactly one capturing group.
+        for part in self._slot_re.split(text):
+            if is_slot:
+                resolved = self._slot_mapping.get(part, self._not_found)
+                if resolved is None:
+                    raise KeyError(f"Component not found for slot: {part}")
+
+                if is_component_sequence(resolved):
+                    yield from resolved
+                else:
+                    # mypy complains that resolved may be a sequence, but that's not the case.
+                    yield resolved  # type: ignore[misc]
+            else:
+                yield part
+
+            is_slot = not is_slot
+
+
+class Snippet:
+    """
+    Component that renders text, which may be asynchronously loaded from a file.
+
+    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.
+    2. The text content is processed by a `TextProcessor` if provided.
+    3. The processed text is converted into a component (may be component sequence)
+       by a `TextResolver`, for example `Slots`.
+    4. Every `str` children (produced by the steps above) is converted into a `SafeStr` for
+       rendering.
+
+    The pipeline above is a bit abstract, so here are some usage notes:
+
+    - The text content of a snippet can be a Python format string template, in which case the
+      `TextProcessor` can be a simple method that calls `str.format()` with the correct arguments.
+    - Alternatively, a text processor can also be used to get only a substring -- commonly referred
+      to as fragment in frameworks like Jinja -- of the original text.
+    - The text processor is applied before the text resolver, which makes it possible to insert
+      placeholders into the text (for example slots, like in this case:
+      `..."{toolbar}...".format(toolbar="<!-- slot[toolbar] -->")`) that are then replaced with any
+      `htmy.Component` by the `TextResolver` (for example `Slots`).
+    - `TextResolver` can return plain `str` values, it is not necessary for it to convert strings
+      to `SafeStr` to prevent unwanted escaping.
+
+    Example:
+
+    ```python
+    from datetime import date
+    from htmy import Snippet, Slots
+
+    def text_processor(text: str, context: Context) -> str:
+       return text.format(today=date.today())
+
+    snippet = Snippet(
+        "my-page.html",
+        text_processor=text_processor,
+        text_resolver=Slots(
+            {
+                "date-picker": MyDatePicker(class_="text-primary"),
+                "Toolbar": MyPageToolbar(active_page="home"),
+                ...
+            }
+        ),
+    )
+    ```
+
+    In the above example, if `my-page.html` contains a `{today}` placeholder, it will be replaced
+    with the current date. If it contains a `<!-- slot[toolbar] -->}` slot, then the `MyPageToolbar`
+    `htmy` component instance will be rendered in its place, and the `<!-- slot[date-picker] -->` slot
+    will be replaced with the `MyDatePicker` component instance.
+    """
+
+    __slots__ = ("_path_or_text", "_text_processor", "_text_resolver")
+
+    def __init__(
+        self,
+        path_or_text: Text | str | Path,
+        text_resolver: TextResolver | None = None,
+        *,
+        text_processor: TextProcessor | None = None,
+    ) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            path_or_text: The path from where the content should be loaded or a `Text`
+                instance if this value should be rendered directly.
+            text_resolver: An optional `TextResolver` (e.g. `Slots`) that converts the processed
+                text into a component. If not provided, the text will be rendered as a `SafeStr`.
+            text_processor: An optional `TextProcessor` that can be used to process the text
+                content before rendering. It can be used for example for token replacement or
+                string formatting.
+        """
+        self._path_or_text = path_or_text
+        self._text_processor = text_processor
+        self._text_resolver = text_resolver
+
+    async def htmy(self, context: Context) -> Component:
+        """Renders the component."""
+        text = await self._get_text_content()
+        if self._text_processor is not None:
+            processed = self._text_processor(text, context)
+            text = (await processed) if isinstance(processed, Awaitable) else processed
+
+        if self._text_resolver is None:
+            return self._render_text(text, context)
+
+        comps = as_component_sequence(self._text_resolver.resolve_text(text))
+        return tuple(
+            as_component_type(self._render_text(c, context)) if isinstance(c, str) else c for c in comps
+        )
+
+    async def _get_text_content(self) -> str:
+        """Returns the plain text content that should be rendered."""
+        path_or_text = self._path_or_text
+
+        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()
+
+    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 component.
+        """
+        return SafeStr(text)

{htmy-0.4.2 → htmy-0.5.0}/htmy/typing.py

@@ -1,5 +1,5 @@
 from collections.abc import Callable, Coroutine, Mapping, MutableMapping
-from typing import Any, Protocol, TypeAlias, TypeGuard, TypeVar, runtime_checkable
+from typing import Any, Protocol, TypeAlias, TypeVar, runtime_checkable
 
 T = TypeVar("T")
 U = TypeVar("U")
@@ -66,11 +66,6 @@ Component: TypeAlias = ComponentType | ComponentSequence
 """Component type: a single component or a sequence of components."""
 
 
-def is_component_sequence(obj: Any) -> TypeGuard[ComponentSequence]:
-    """Returns whether the given object is a component sequence."""
-    return isinstance(obj, (list, tuple))
-
-
 SyncFunctionComponent: TypeAlias = Callable[[T, Context], Component]
 """Protocol definition for sync function components."""
 
@@ -104,8 +99,25 @@ class AsyncContextProvider(Protocol):
 ContextProvider: TypeAlias = SyncContextProvider | AsyncContextProvider
 """Context provider type."""
 
-
 # -- Text processors
 
 TextProcessor: TypeAlias = Callable[[str, Context], str | Coroutine[Any, Any, str]]
 """Callable type that expects a string and a context, and returns a processed string."""
+
+
+class TextResolver(Protocol):
+    """
+    Protocol definition for resolvers that convert a string to a component.
+    """
+
+    def resolve_text(self, text: str) -> Component:
+        """
+        Returns the resolved component for the given text.
+
+        Arguments:
+            text: The text to resolve.
+
+        Raises:
+            KeyError: If the text cannot be resolved to a component.
+        """
+        ...

{htmy-0.4.2 → htmy-0.5.0}/htmy/utils.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 from collections.abc import Generator
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, TypeGuard
 
 if TYPE_CHECKING:
-    from .typing import ComponentSequence, ComponentType
+    from .typing import Component, ComponentSequence, ComponentType
 
 
 def join_components(
@@ -42,3 +42,22 @@ def join(*items: str | None, separator: str = " ") -> str:
     Joins the given strings with the given separator, skipping `None` values.
     """
     return separator.join(i for i in items if i)
+
+
+def is_component_sequence(comp: Component) -> TypeGuard[ComponentSequence]:
+    """Returns whether the given component is a component sequence."""
+    return isinstance(comp, (list, tuple))
+
+
+def as_component_sequence(comp: Component) -> ComponentSequence:
+    """Returns the given component as a component sequence."""
+    # mypy doesn't understand the `is_component_sequence` type guard.
+    return comp if is_component_sequence(comp) else (comp,)  # type: ignore[return-value]
+
+
+def as_component_type(comp: Component) -> ComponentType:
+    """Returns the given component as a `ComponentType` (not sequence)."""
+    from .core import Fragment
+
+    # mypy doesn't understand the `is_component_sequence` type guard.
+    return comp if not is_component_sequence(comp) else Fragment(*comp)  # type: ignore[return-value]

{htmy-0.4.2 → htmy-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "htmy"
-version = "0.4.2"
+version = "0.5.0"
 description = "Async, pure-Python rendering engine."
 authors = ["Peter Volf <do.volfp@gmail.com>"]
 license = "MIT"
@@ -15,7 +15,7 @@ markdown = "^3.7"
 [tool.poetry.group.dev.dependencies]
 mkdocs-material = "^9.5.39"
 mkdocstrings = {extras = ["python"], version = "^0.26.1"}
-mypy = "^1.11.2"
+mypy = "^1.14.1"
 poethepoet = "^0.29.0"
 pytest = "^8.3.3"
 pytest-asyncio = "^0.24.0"