htmy 0.4.2__tar.gz → 0.6.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: htmy
-Version: 0.4.2
+Version: 0.6.0
 Summary: Async, pure-Python rendering engine.
 License: MIT
 Author: Peter Volf
@@ -30,12 +30,15 @@ Description-Content-Type: text/markdown
 
 **Async**, **pure-Python** 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).
 - **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**, **without custom syntax**.
 - **Markdown** support with tools for customization.
 - Async, JSON based **internationalization**.
 - Built-in, easy to use `ErrorBoundary` component for graceful error handling.
@@ -44,6 +47,10 @@ Description-Content-Type: text/markdown
 - Automatic and customizable **property-name conversion** from snake case to kebab case.
 - **Fully-typed**.
 
+## 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.
+
 ## Installation
 
 The package is available on PyPI and can be installed with:
@@ -60,9 +67,9 @@ Also, the library doesn't rely on advanced Python features such as metaclasses o
 
 ### Components
 
-Every class with a sync or async `htmy(context: Context) -> Component` method is an `htmy` component (technically an `HTMYComponentType`). Strings are also components, as well as lists or tuples of `HTMYComponentType` or string objects.
+Every object with a sync or async `htmy(context: Context) -> Component` method is an `htmy` component (technically an `HTMYComponentType`). Strings are also components, as well as lists or tuples of `HTMYComponentType` or string objects. In many cases though, you don't even need to create components, simple functions that return components will be sufficient -- you can find out more about this in the [Components guide](https://volfpeter.github.io/htmy/components-guide/) of the documentation.
 
-Using this method name enables the conversion of any of your business objects (from `TypedDicts`s or `pydantic` models to ORM classes) into components without the fear of name collision with other tools.
+Using the `htmy()` method name enables the conversion of any of your pre-existing business objects (from `TypedDicts`s or `pydantic` models to ORM classes) into components without the fear of name collision or compatibility issues with other tools.
 
 Async support makes it possible to load data or execute async business logic right in your components. This can reduce the amount of boilerplate you need to write in some cases, and also gives you the freedom to split the rendering and non-rendering logic in any way you see fit.
 
@@ -161,11 +168,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
@@ -204,7 +211,7 @@ if __name__ == "__main__":
 
 As you could see from the code examples above, every component has a `context: Context` argument, which we haven't used so far. Context is a way to share data with the entire subtree of a component without "prop drilling".
 
-The context (technically a `Mapping`) is entirely managed by the renderer. Context provider components (any class with a sync or async `htmy_context() -> Context` method) add new data to the context to make it available to components in their subtree, and components can simply take what they need from the context.
+The context (technically a `Mapping`) is entirely managed by the renderer. Context provider components (any class with a sync or async `htmy_context() -> Context` method) add new data to the context to make it available to components in their subtree (including themselves), and components can simply take what they need from the context.
 
 There is no restriction on what can be in the context, it can be used for anything the application needs, for example making the current user, UI preferences, themes, or formatters available to components. In fact, built-in components get their `Formatter` from the context if it contains one, to make it possible to customize tag property name and value formatting.
 
@@ -305,13 +312,13 @@ FastAPI:
 
 At one end of the spectrum, there are the complete application frameworks that combine the server (Python) and client (JavaScript) applications with the entire state management and synchronization into a single Python (an in some cases an additional JavaScript) package. Some of the most popular examples are: [Reflex](https://github.com/reflex-dev/reflex), [NiceGUI](https://github.com/zauberzeug/nicegui/), [ReactPy](https://github.com/reactive-python/reactpy), and [FastUI](https://github.com/pydantic/FastUI).
 
-The main benefit of these frameworks is rapid application prototyping and a very convenient developer experience (at least as long as you stay within the built-in feature set of the framework). In exchange for that, they are very opinionated (from components to frontend tooling and state management), the underlying engineering is very complex, deployment and scaling can be hard or costly, and they can be hard to migrate away from. Even with these caveats, they can be a very good choice for internal tools and application prototyping.
+The main benefit of these frameworks is rapid application prototyping and a very convenient developer experience, at least as long as you stay within the built-in feature set of the framework. In exchange for that, they are very opinionated (from components to frontend tooling and state management), the underlying engineering is very complex, deployment and scaling can be hard or costly, and they can be hard to migrate away from. Even with these caveats, they can be a very good choice for internal tools and application prototyping.
 
-The other end of spectrum -- plain rendering engines -- is dominated by the [Jinja](https://jinja.palletsprojects.com) templating engine, which is a safe choice as it has been and will be around for a long time. The main drawbacks with Jinja are the lack of good IDE support, the complete lack of static code analysis support, and the (subjectively) ugly syntax.
+The other end of spectrum -- plain rendering engines -- is dominated by the [Jinja](https://jinja.palletsprojects.com) templating engine, which is a safe choice as it has been and will be around for a long time. The main drawbacks with Jinja are the lack of good IDE support, the complete lack of static code analysis support, and the (subjectively) ugly custom template syntax.
 
 Then there are tools that aim for the middleground, usually by providing most of the benefits and drawbacks of complete application frameworks while leaving state management, client-server communication, and dynamic UI updates for the user to solve, often with some level of [HTMX](https://htmx.org/) support. This group includes libraries like [FastHTML](https://github.com/answerdotai/fasthtml) and [Ludic](https://github.com/getludic/ludic).
 
-The primary aim of `htmy` is to be an **async**, pure-Python rendering engine, which is as **simple**, **maintainable**, and **customizable** as possible, while still providing all the building blocks for (conveniently) creating complex and maintainable applications.
+The primary aim of `htmy` is to be a `Jinja` alternative that is similarly powerful and flexible, while also providing the benefits of full IDE support, static code analysis, and native Python (and HTML, XML, markdown) syntax. Additionally, `htmy` is **async-first**, so it works great with modern async Python frameworks such as [FastAPI](https://fastapi.tiangolo.com). The library was designed to be as **simple**, **maintainable**, and **customizable** as possible, while still providing all the building blocks for creating complex web applications.
 
 ## Dependencies
 
@@ -329,7 +336,13 @@ The documentation is built with `mkdocs-material` and `mkdocstrings`.
 
 ## Contributing
 
-All contributions are welcome, including more documentation, examples, code, and tests. Even questions.
+We welcome contributions from the community to help improve the project! Whether you're an experienced developer or just starting out, there are many ways you can contribute:
+
+- **Discuss**: Join our [Discussion Board](https://github.com/volfpeter/htmy/discussions) to ask questions, share ideas, provide feedback, and engage with the community.
+- **Document**: Help improve the documentation by fixing typos, adding examples, and updating guides to make it easier for others to use the project.
+- **Develop**: Prototype requested features or pick up issues from the issue tracker.
+- **Share**: Share your own project by adding a link to it in the documentation, helping others discover and benefit from your work.
+- **Test**: Write tests to improve coverage and enhance reliability.
 
 ## License - MIT
 

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

@@ -11,12 +11,15 @@
 
 **Async**, **pure-Python** 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).
 - **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**, **without custom syntax**.
 - **Markdown** support with tools for customization.
 - Async, JSON based **internationalization**.
 - Built-in, easy to use `ErrorBoundary` component for graceful error handling.
@@ -25,6 +28,10 @@
 - Automatic and customizable **property-name conversion** from snake case to kebab case.
 - **Fully-typed**.
 
+## 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.
+
 ## Installation
 
 The package is available on PyPI and can be installed with:
@@ -41,9 +48,9 @@ Also, the library doesn't rely on advanced Python features such as metaclasses o
 
 ### Components
 
-Every class with a sync or async `htmy(context: Context) -> Component` method is an `htmy` component (technically an `HTMYComponentType`). Strings are also components, as well as lists or tuples of `HTMYComponentType` or string objects.
+Every object with a sync or async `htmy(context: Context) -> Component` method is an `htmy` component (technically an `HTMYComponentType`). Strings are also components, as well as lists or tuples of `HTMYComponentType` or string objects. In many cases though, you don't even need to create components, simple functions that return components will be sufficient -- you can find out more about this in the [Components guide](https://volfpeter.github.io/htmy/components-guide/) of the documentation.
 
-Using this method name enables the conversion of any of your business objects (from `TypedDicts`s or `pydantic` models to ORM classes) into components without the fear of name collision with other tools.
+Using the `htmy()` method name enables the conversion of any of your pre-existing business objects (from `TypedDicts`s or `pydantic` models to ORM classes) into components without the fear of name collision or compatibility issues with other tools.
 
 Async support makes it possible to load data or execute async business logic right in your components. This can reduce the amount of boilerplate you need to write in some cases, and also gives you the freedom to split the rendering and non-rendering logic in any way you see fit.
 
@@ -142,11 +149,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
@@ -185,7 +192,7 @@ if __name__ == "__main__":
 
 As you could see from the code examples above, every component has a `context: Context` argument, which we haven't used so far. Context is a way to share data with the entire subtree of a component without "prop drilling".
 
-The context (technically a `Mapping`) is entirely managed by the renderer. Context provider components (any class with a sync or async `htmy_context() -> Context` method) add new data to the context to make it available to components in their subtree, and components can simply take what they need from the context.
+The context (technically a `Mapping`) is entirely managed by the renderer. Context provider components (any class with a sync or async `htmy_context() -> Context` method) add new data to the context to make it available to components in their subtree (including themselves), and components can simply take what they need from the context.
 
 There is no restriction on what can be in the context, it can be used for anything the application needs, for example making the current user, UI preferences, themes, or formatters available to components. In fact, built-in components get their `Formatter` from the context if it contains one, to make it possible to customize tag property name and value formatting.
 
@@ -286,13 +293,13 @@ FastAPI:
 
 At one end of the spectrum, there are the complete application frameworks that combine the server (Python) and client (JavaScript) applications with the entire state management and synchronization into a single Python (an in some cases an additional JavaScript) package. Some of the most popular examples are: [Reflex](https://github.com/reflex-dev/reflex), [NiceGUI](https://github.com/zauberzeug/nicegui/), [ReactPy](https://github.com/reactive-python/reactpy), and [FastUI](https://github.com/pydantic/FastUI).
 
-The main benefit of these frameworks is rapid application prototyping and a very convenient developer experience (at least as long as you stay within the built-in feature set of the framework). In exchange for that, they are very opinionated (from components to frontend tooling and state management), the underlying engineering is very complex, deployment and scaling can be hard or costly, and they can be hard to migrate away from. Even with these caveats, they can be a very good choice for internal tools and application prototyping.
+The main benefit of these frameworks is rapid application prototyping and a very convenient developer experience, at least as long as you stay within the built-in feature set of the framework. In exchange for that, they are very opinionated (from components to frontend tooling and state management), the underlying engineering is very complex, deployment and scaling can be hard or costly, and they can be hard to migrate away from. Even with these caveats, they can be a very good choice for internal tools and application prototyping.
 
-The other end of spectrum -- plain rendering engines -- is dominated by the [Jinja](https://jinja.palletsprojects.com) templating engine, which is a safe choice as it has been and will be around for a long time. The main drawbacks with Jinja are the lack of good IDE support, the complete lack of static code analysis support, and the (subjectively) ugly syntax.
+The other end of spectrum -- plain rendering engines -- is dominated by the [Jinja](https://jinja.palletsprojects.com) templating engine, which is a safe choice as it has been and will be around for a long time. The main drawbacks with Jinja are the lack of good IDE support, the complete lack of static code analysis support, and the (subjectively) ugly custom template syntax.
 
 Then there are tools that aim for the middleground, usually by providing most of the benefits and drawbacks of complete application frameworks while leaving state management, client-server communication, and dynamic UI updates for the user to solve, often with some level of [HTMX](https://htmx.org/) support. This group includes libraries like [FastHTML](https://github.com/answerdotai/fasthtml) and [Ludic](https://github.com/getludic/ludic).
 
-The primary aim of `htmy` is to be an **async**, pure-Python rendering engine, which is as **simple**, **maintainable**, and **customizable** as possible, while still providing all the building blocks for (conveniently) creating complex and maintainable applications.
+The primary aim of `htmy` is to be a `Jinja` alternative that is similarly powerful and flexible, while also providing the benefits of full IDE support, static code analysis, and native Python (and HTML, XML, markdown) syntax. Additionally, `htmy` is **async-first**, so it works great with modern async Python frameworks such as [FastAPI](https://fastapi.tiangolo.com). The library was designed to be as **simple**, **maintainable**, and **customizable** as possible, while still providing all the building blocks for creating complex web applications.
 
 ## Dependencies
 
@@ -310,7 +317,13 @@ The documentation is built with `mkdocs-material` and `mkdocstrings`.
 
 ## Contributing
 
-All contributions are welcome, including more documentation, examples, code, and tests. Even questions.
+We welcome contributions from the community to help improve the project! Whether you're an experienced developer or just starting out, there are many ways you can contribute:
+
+- **Discuss**: Join our [Discussion Board](https://github.com/volfpeter/htmy/discussions) to ask questions, share ideas, provide feedback, and engage with the community.
+- **Document**: Help improve the documentation by fixing typos, adding examples, and updating guides to make it easier for others to use the project.
+- **Develop**: Prototype requested features or pick up issues from the issue tracker.
+- **Share**: Share your own project by adding a link to it in the documentation, helping others discover and benefit from your work.
+- **Test**: Write tests to improve coverage and enhance reliability.
 
 ## License - MIT
 

{htmy-0.4.2 → htmy-0.6.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
@@ -13,12 +12,13 @@ from .core import Text as Text
 from .core import WildcardTag as WildcardTag
 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 .function_component import component as component
 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
 from .typing import Component as Component
 from .typing import ComponentSequence as ComponentSequence
 from .typing import ComponentType as ComponentType
@@ -26,15 +26,15 @@ from .typing import Context as Context
 from .typing import ContextKey as ContextKey
 from .typing import ContextProvider as ContextProvider
 from .typing import ContextValue as ContextValue
-from .typing import FunctionComponent as FunctionComponent
 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 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.6.0}/htmy/core.py

@@ -1,30 +1,14 @@
 from __future__ import annotations
 
 import abc
-import asyncio
 import enum
-from collections.abc import Awaitable, Callable, Container
-from pathlib import Path
-from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypedDict, cast, overload
+from collections.abc import Callable, Container
+from typing import TYPE_CHECKING, Any, ClassVar, TypedDict, cast
 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,
-    ComponentType,
-    Context,
-    ContextKey,
-    ContextValue,
-    FunctionComponent,
-    PropertyValue,
-    SyncFunctionComponent,
-    T,
-    TextProcessor,
-    is_component_sequence,
-)
-from .utils import join_components
+from .typing import Component, ComponentType, Context, ContextKey, ContextValue, PropertyValue, T
+from .utils import as_component_type, join_components
 
 if TYPE_CHECKING:
     from typing_extensions import Never, Self
@@ -97,11 +81,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 +107,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
 
 
@@ -262,85 +189,6 @@ class ContextAware:
         raise TypeError(f"Invalid context data type for {cls.__name__}.")
 
 
-# -- Function components
-
-
-class SyncFunctionComponentWrapper(Generic[T]):
-    """Base class `FunctionComponent` wrappers."""
-
-    __slots__ = ("_props",)
-
-    _wrapped_function: SyncFunctionComponent[T]
-
-    def __init__(self, props: T) -> None:
-        self._props = props
-
-    def __init_subclass__(cls, *, func: SyncFunctionComponent[T]) -> None:
-        cls._wrapped_function = func
-
-    def htmy(self, context: Context) -> Component:
-        """Renders the component."""
-        # type(self) is necessary, otherwise the wrapped function would be called
-        # with an extra self argument...
-        return type(self)._wrapped_function(self._props, context)
-
-
-class AsyncFunctionComponentWrapper(Generic[T]):
-    """Base class `FunctionComponent` wrappers."""
-
-    __slots__ = ("_props",)
-
-    _wrapped_function: AsyncFunctionComponent[T]
-
-    def __init__(self, props: T) -> None:
-        self._props = props
-
-    def __init_subclass__(cls, *, func: AsyncFunctionComponent[T]) -> None:
-        cls._wrapped_function = func
-
-    async def htmy(self, context: Context) -> Component:
-        """Renders the component."""
-        # type(self) is necessary, otherwise the wrapped function would be called
-        # with an extra self argument...
-        return await type(self)._wrapped_function(self._props, context)
-
-
-@overload
-def component(func: SyncFunctionComponent[T]) -> type[SyncFunctionComponentWrapper[T]]: ...
-
-
-@overload
-def component(func: AsyncFunctionComponent[T]) -> type[AsyncFunctionComponentWrapper[T]]: ...
-
-
-def component(
-    func: FunctionComponent[T],
-) -> type[SyncFunctionComponentWrapper[T]] | type[AsyncFunctionComponentWrapper[T]]:
-    """
-    Decorator that converts the given function into a component.
-
-    Internally this is achieved by wrapping the function in a pre-configured
-    `FunctionComponentWrapper` subclass.
-
-    Arguments:
-        func: The decorated function component.
-
-    Returns:
-        A pre-configured `FunctionComponentWrapper` subclass.
-    """
-
-    if asyncio.iscoroutinefunction(func):
-
-        class AsyncFCW(AsyncFunctionComponentWrapper[T], func=func): ...
-
-        return AsyncFCW
-    else:
-
-        class SyncFCW(SyncFunctionComponentWrapper[T], func=func): ...  # type: ignore[arg-type]
-
-        return SyncFCW
-
-
 # -- Formatting
 
 

htmy-0.6.0/htmy/function_component.py

@@ -0,0 +1,243 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Coroutine
+from typing import Any, Protocol, TypeAlias, overload
+
+from .typing import AsyncComponent, Component, Context, SyncComponent, T
+
+# -- Typing for "full" function components.
+
+_SyncFunctionComponent: TypeAlias = Callable[[T, Context], Component]
+"""
+Protocol definition for sync function components that have both a properties and a context argument.
+"""
+
+_AsyncFunctionComponent: TypeAlias = Callable[[T, Context], Coroutine[Any, Any, Component]]
+"""
+Protocol definition for async function components that have both a properties and a context argument.
+"""
+
+_FunctionComponent: TypeAlias = _SyncFunctionComponent[T] | _AsyncFunctionComponent[T]
+"""
+Function component type that has both a properties and a context argument.
+"""
+
+# -- Typing for context-only function components.
+
+_ContextOnlySyncFunctionComponent: TypeAlias = Callable[[Context], Component]
+"""
+Protocol definition for sync function components that only have a context argument.
+"""
+
+
+class _DecoratedContextOnlySyncFunctionComponent(SyncComponent, Protocol):
+    """
+    Protocol definition for sync components that are also callable, and return a sync
+    component when called.
+    """
+
+    def __call__(self) -> SyncComponent: ...
+
+
+_ContextOnlyAsyncFunctionComponent: TypeAlias = Callable[[Context], Coroutine[Any, Any, Component]]
+"""
+Protocol definition for async function components that only have a context argument.
+"""
+
+
+class _DecoratedContextOnlyAsyncFunctionComponent(SyncComponent, Protocol):
+    """
+    Protocol definition for async components that are also callable, and return an async
+    component when called.
+    """
+
+    def __call__(self) -> SyncComponent: ...
+
+
+_ContextOnlyFunctionComponent: TypeAlias = (
+    _ContextOnlySyncFunctionComponent | _ContextOnlyAsyncFunctionComponent
+)
+"""
+Function component type that only accepts a context argument.
+"""
+
+_DecoratedContextOnlyFunction: TypeAlias = (
+    _DecoratedContextOnlySyncFunctionComponent | _DecoratedContextOnlyAsyncFunctionComponent
+)
+"""
+Protocol definition for sync or async components that are also callable, and return a sync
+or async component when called.
+"""
+
+
+class ComponentDecorators:
+    """
+    Function component decorators.
+    """
+
+    __slots__ = ()
+
+    # -- FunctionComponent decorator.
+
+    @overload
+    def __call__(self, func: _SyncFunctionComponent[T]) -> Callable[[T], SyncComponent]: ...
+
+    @overload
+    def __call__(self, func: _AsyncFunctionComponent[T]) -> Callable[[T], AsyncComponent]: ...
+
+    def __call__(
+        self,
+        func: _FunctionComponent[T],
+    ) -> Callable[[T], SyncComponent] | Callable[[T], AsyncComponent]:
+        """
+        Decorator that converts the decorated function into one that must be called with
+        the function component's properties and returns a component instance.
+
+        If used on an async function, the resulting component will also be async;
+        otherwise it will be sync.
+
+        Example:
+
+        ```python
+        @component
+        def my_component(props: int, context: Context) -> Component:
+            return html.p(f"Value: {props}")
+
+        async def render():
+           return await Renderer().render(
+               my_component(42)
+           )
+        ```
+
+        Arguments:
+            func: The decorated function.
+
+        Returns:
+            A function that must be called with the function component's properties and
+            returns a component instance. (Or loosly speaking, an `HTMYComponentType` which
+            can be "instantiated" with the function component's properties.)
+        """
+
+        if asyncio.iscoroutinefunction(func):
+
+            def async_wrapper(props: T) -> AsyncComponent:
+                # This function must be async, in case the renderer inspects it to decide how to handle it.
+                async def component(context: Context) -> Component:
+                    return await func(props, context)  # type: ignore[no-any-return]
+
+                component.htmy = component  # type: ignore[attr-defined]
+                return component  # type: ignore[return-value]
+
+            return async_wrapper
+        else:
+
+            def sync_wrapper(props: T) -> SyncComponent:
+                def component(context: Context) -> Component:
+                    return func(props, context)  # type: ignore[return-value]
+
+                component.htmy = component  # type: ignore[attr-defined]
+                return component  # type: ignore[return-value]
+
+            return sync_wrapper
+
+    @overload
+    def function(self, func: _SyncFunctionComponent[T]) -> Callable[[T], SyncComponent]: ...
+
+    @overload
+    def function(self, func: _AsyncFunctionComponent[T]) -> Callable[[T], AsyncComponent]: ...
+
+    def function(
+        self,
+        func: _FunctionComponent[T],
+    ) -> Callable[[T], SyncComponent] | Callable[[T], AsyncComponent]:
+        """
+        Decorator that converts the decorated function into one that must be called with
+        the function component's properties and returns a component instance.
+
+        If used on an async function, the resulting component will also be async;
+        otherwise it will be sync.
+
+        This function is just an alias for `__call__()`.
+
+        Example:
+
+        ```python
+        @component.function
+        def my_component(props: int, context: Context) -> Component:
+            return html.p(f"Value: {props}")
+
+        async def render():
+           return await Renderer().render(
+               my_component(42)
+           )
+
+        Arguments:
+            func: The decorated function.
+
+        Returns:
+            A function that must be called with the function component's properties and
+            returns a component instance. (Or loosly speaking, an `HTMYComponentType` which
+            can be "instantiated" with the function component's properties.)
+        """
+        return self(func)
+
+    # -- ContextOnlyFunctionComponent decorator.
+
+    @overload
+    def context_only(
+        self, func: _ContextOnlySyncFunctionComponent
+    ) -> _DecoratedContextOnlySyncFunctionComponent: ...
+
+    @overload
+    def context_only(
+        self, func: _ContextOnlyAsyncFunctionComponent
+    ) -> _DecoratedContextOnlyAsyncFunctionComponent: ...
+
+    def context_only(
+        self,
+        func: _ContextOnlyFunctionComponent,
+    ) -> _DecoratedContextOnlySyncFunctionComponent | _DecoratedContextOnlyAsyncFunctionComponent:
+        """
+        Decorator that converts the decorated function into a component.
+
+        If used on an async function, the resulting component will also be async;
+        otherwise it will be sync.
+
+        The decorated function will be both a component object and a callable that returns a
+        component object, so it can be used in the component tree both with and without the
+        call signature:
+
+        ```python
+        @component.context_only
+        def my_component(ctx):
+            return "Context only function component."
+
+        async def render():
+           return await Renderer().render(
+               my_component(),  # With call signature.
+               my_component,  # Without call signature.
+           )
+        ```
+
+        Arguments:
+            func: The decorated function.
+
+        Returns:
+            The created component.
+        """
+
+        def wrapper() -> SyncComponent | AsyncComponent:
+            func.htmy = func  # type: ignore[union-attr]
+            return func  # type: ignore[return-value]
+
+        wrapper.htmy = func  # type: ignore[attr-defined]
+        return wrapper  # type: ignore[return-value]
+
+
+component = ComponentDecorators()
+"""
+Decorators for converting functions into components
+
+This is an instance of `ComponentDecorators`.
+"""

{htmy-0.4.2 → htmy-0.6.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.6.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.6.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.6.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")
@@ -65,21 +65,6 @@ ComponentSequence: TypeAlias = list[ComponentType] | tuple[ComponentType, ...]
 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."""
-
-AsyncFunctionComponent: TypeAlias = Callable[[T, Context], Coroutine[Any, Any, Component]]
-"""Protocol definition for async function components."""
-
-FunctionComponent: TypeAlias = SyncFunctionComponent[T] | AsyncFunctionComponent[T]
-"""Function component type."""
-
 # -- Context providers
 
 
@@ -102,10 +87,32 @@ class AsyncContextProvider(Protocol):
 
 
 ContextProvider: TypeAlias = SyncContextProvider | AsyncContextProvider
-"""Context provider type."""
+"""
+Sync or async context provider type.
 
+Components can implement this protocol to add extra data to the rendering context
+of their entire component subtree (including themselves).
+"""
 
 # -- 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.6.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.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "htmy"
-version = "0.4.2"
+version = "0.6.0"
 description = "Async, pure-Python rendering engine."
 authors = ["Peter Volf <do.volfp@gmail.com>"]
 license = "MIT"
@@ -15,14 +15,16 @@ 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.15.0"
 poethepoet = "^0.29.0"
 pytest = "^8.3.3"
 pytest-asyncio = "^0.24.0"
 pytest-random-order = "^1.1.1"
-ruff = "^0.6.8"
+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"]