htmy 0.1.0__tar.gz → 0.3.0__tar.gz

htmy-0.1.0/README.md → htmy-0.3.0/PKG-INFO

@@ -1,3 +1,21 @@
+Metadata-Version: 2.1
+Name: htmy
+Version: 0.3.0
+Summary: Async, pure-Python rendering engine.
+License: MIT
+Author: Peter Volf
+Author-email: do.volfp@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: anyio (>=4.6.2.post1,<5.0.0)
+Requires-Dist: async-lru (>=2.0.4,<3.0.0)
+Requires-Dist: markdown (>=3.7,<4.0)
+Description-Content-Type: text/markdown
+
 ![Tests](https://github.com/volfpeter/htmy/actions/workflows/tests.yml/badge.svg)
 ![Linters](https://github.com/volfpeter/htmy/actions/workflows/linters.yml/badge.svg)
 ![Documentation](https://github.com/volfpeter/htmy/actions/workflows/build-docs.yml/badge.svg)
@@ -9,7 +27,7 @@
 
 # `htmy`
 
-**Async**, **zero-dependency**, **pure-Python** rendering engine.
+**Async**, **pure-Python** rendering engine.
 
 ## Key features
 
@@ -17,7 +35,10 @@
 - **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.
+- **Markdown** support with tools for customization.
+- Async, JSON based **internationalization**.
 - Built-in, easy to use `ErrorBoundary` component for graceful error handling.
+- **Unopinionated**: use the backend, CSS, and JS frameworks of your choice, the way you want to use them.
 - Everything is **easily customizable**, from the rendering engine to components, formatting and context management.
 - Automatic and customizable **property-name conversion** from snake case to kebab case.
 - **Fully-typed**.
@@ -136,11 +157,15 @@ user_table = html.table(
 
 ### Built-in components
 
-`htmy` has a rich set of built-in base and utility components for both HTML and other use-cases:
+`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).
-- `BaseTag`, `TagWithProps`, `StandaloneTag`, `Tag`: base classes for custom XML tags.
+- `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
 
@@ -283,7 +308,11 @@ The primary aim of `htmy` is to be an **async**, pure-Python rendering engine, w
 
 ## Dependencies
 
-The library has **no dependencies**.
+The library aims to minimze its dependencies. Currently the following dependencies are required:
+
+- `anyio`: for async file operations and networking.
+- `async-lru`: for async caching.
+- `markdown`: for markdown parsing.
 
 ## Development
 
@@ -298,3 +327,4 @@ All contributions are welcome, including more documentation, examples, code, and
 ## License - MIT
 
 The package is open-sourced under the conditions of the [MIT license](https://choosealicense.com/licenses/mit/).
+

htmy-0.1.0/PKG-INFO → htmy-0.3.0/README.md

@@ -1,17 +1,3 @@
-Metadata-Version: 2.1
-Name: htmy
-Version: 0.1.0
-Summary: Async, zero-dependency, pure-Python rendering engine.
-License: MIT
-Author: Peter Volf
-Author-email: do.volfp@gmail.com
-Requires-Python: >=3.11,<4.0
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Description-Content-Type: text/markdown
-
 ![Tests](https://github.com/volfpeter/htmy/actions/workflows/tests.yml/badge.svg)
 ![Linters](https://github.com/volfpeter/htmy/actions/workflows/linters.yml/badge.svg)
 ![Documentation](https://github.com/volfpeter/htmy/actions/workflows/build-docs.yml/badge.svg)
@@ -23,7 +9,7 @@ Description-Content-Type: text/markdown
 
 # `htmy`
 
-**Async**, **zero-dependency**, **pure-Python** rendering engine.
+**Async**, **pure-Python** rendering engine.
 
 ## Key features
 
@@ -31,7 +17,10 @@ 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.
+- **Markdown** support with tools for customization.
+- Async, JSON based **internationalization**.
 - Built-in, easy to use `ErrorBoundary` component for graceful error handling.
+- **Unopinionated**: use the backend, CSS, and JS frameworks of your choice, the way you want to use them.
 - Everything is **easily customizable**, from the rendering engine to components, formatting and context management.
 - Automatic and customizable **property-name conversion** from snake case to kebab case.
 - **Fully-typed**.
@@ -150,11 +139,15 @@ user_table = html.table(
 
 ### Built-in components
 
-`htmy` has a rich set of built-in base and utility components for both HTML and other use-cases:
+`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).
-- `BaseTag`, `TagWithProps`, `StandaloneTag`, `Tag`: base classes for custom XML tags.
+- `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
 
@@ -297,7 +290,11 @@ The primary aim of `htmy` is to be an **async**, pure-Python rendering engine, w
 
 ## Dependencies
 
-The library has **no dependencies**.
+The library aims to minimze its dependencies. Currently the following dependencies are required:
+
+- `anyio`: for async file operations and networking.
+- `async-lru`: for async caching.
+- `markdown`: for markdown parsing.
 
 ## Development
 
@@ -312,4 +309,3 @@ All contributions are welcome, including more documentation, examples, code, and
 ## License - MIT
 
 The package is open-sourced under the conditions of the [MIT license](https://choosealicense.com/licenses/mit/).
-

{htmy-0.1.0 → htmy-0.3.0}/htmy/__init__.py

@@ -5,10 +5,12 @@ 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 StandaloneTag as StandaloneTag
+from .core import Snippet as Snippet
 from .core import Tag as Tag
 from .core import TagConfig as TagConfig
 from .core import TagWithProps as TagWithProps
+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

{htmy-0.1.0 → htmy-0.3.0}/htmy/core.py

@@ -4,9 +4,11 @@ import abc
 import asyncio
 import enum
 from collections.abc import Callable, Container
+from pathlib import Path
 from typing import Any, ClassVar, Generic, Self, TypedDict, cast, overload
 from xml.sax.saxutils import escape as xml_escape
 
+from .io import open_file
 from .typing import (
     AsyncFunctionComponent,
     Component,
@@ -40,7 +42,8 @@ class Fragment:
         self._children = children
 
     def htmy(self, context: Context) -> Component:
-        return tuple(join_components(self._children, "\n"))
+        """Renders the component."""
+        return self._children
 
 
 class ErrorBoundary(Fragment):
@@ -112,9 +115,50 @@ class WithContext(Fragment):
         self._context = context
 
     def htmy_context(self) -> Context:
+        """Returns an HTMY context for child rendering."""
         return self._context
 
 
+class Snippet:
+    """
+    Base component that can load its content from a file.
+    """
+
+    __slots__ = ("_path_or_text",)
+
+    def __init__(self, path_or_text: Text | str | Path) -> 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.
+        """
+        self._path_or_text = path_or_text
+
+    async def htmy(self, context: Context) -> Component:
+        """Renders the component."""
+        text = await self._get_text_content()
+        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 HTMY component.
+        """
+        return SafeStr(text)
+
+
 # -- Context utilities
 
 
@@ -154,7 +198,7 @@ class ContextAware:
     ```
     """
 
-    __slot__ = ()
+    __slots__ = ()
 
     _base_context_type: ClassVar[type[ContextAware] | None] = None
 
@@ -214,6 +258,7 @@ class SyncFunctionComponentWrapper(Generic[T]):
         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)
@@ -233,6 +278,7 @@ class AsyncFunctionComponentWrapper(Generic[T]):
         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)
@@ -283,7 +329,13 @@ class SkipProperty(Exception):
     ...
 
 
-class SafeStr(str):
+class Text(str):
+    """Marker class for differentiating text content from other strings."""
+
+    ...
+
+
+class SafeStr(Text):
     """
     String subclass whose instances shouldn't get escaped during rendering.
 
@@ -422,6 +474,8 @@ _default_tag_formatter = Formatter()
 
 
 class TagConfig(TypedDict, total=False):
+    """Tag configuration."""
+
     child_separator: ComponentType | None
 
 
@@ -437,14 +491,23 @@ class BaseTag(abc.ABC):
     resolves the async content and then passes the value to the tag.
     """
 
-    __slots__ = ()
+    __slots__ = ("_htmy_name",)
+
+    def __init__(self) -> None:
+        self._htmy_name = self._get_htmy_name()
 
     @property
-    def _htmy_name(self) -> str:
-        return type(self).__name__
+    def htmy_name(self) -> str:
+        """The tag name."""
+        return self._htmy_name
 
     @abc.abstractmethod
-    def htmy(self, context: Context) -> Component: ...
+    def htmy(self, context: Context) -> Component:
+        """Abstract base method for HTMY rendering."""
+        ...
+
+    def _get_htmy_name(self) -> str:
+        return type(self).__name__
 
 
 class TagWithProps(BaseTag):
@@ -453,30 +516,27 @@ class TagWithProps(BaseTag):
     __slots__ = ("props",)
 
     def __init__(self, **props: PropertyValue) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            **props: Tag properties.
+        """
         super().__init__()
         self.props = props
 
     def htmy(self, context: Context) -> Component:
-        name = self._htmy_name
+        """Renders the component."""
+        name = self.htmy_name
         props = self._htmy_format_props(context=context)
-        return (SafeStr(f"<{name} {props}>"), SafeStr(f"</{name}>"))
+        return SafeStr(f"<{name} {props}/>")
 
     def _htmy_format_props(self, context: Context) -> str:
+        """Formats tag properties."""
         formatter = Formatter.from_context(context, _default_tag_formatter)
         return " ".join(formatter.format(name, value) for name, value in self.props.items())
 
 
-class StandaloneTag(TagWithProps):
-    """Tag that has properties and no closing elements, e.g. `<img .../>`."""
-
-    __slots__ = ()
-
-    def htmy(self, context: Context) -> Component:
-        name = self._htmy_name
-        props = self._htmy_format_props(context=context)
-        return SafeStr(f"<{name} {props}/>")
-
-
 class Tag(TagWithProps):
     """Base class for tags with both properties and children."""
 
@@ -485,12 +545,27 @@ class Tag(TagWithProps):
     tag_config: TagConfig = {"child_separator": "\n"}
 
     def __init__(self, *children: ComponentType, **props: PropertyValue) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            *children: Children components.
+            **props: Tag properties.
+        """
+        super().__init__(**props)
         self.children = children
-        self.props = props
+
+    @property
+    def child_separator(self) -> ComponentType | None:
+        """The child separator to use."""
+        return self.tag_config.get("child_separator", None)
 
     def htmy(self, context: Context) -> Component:
-        separator = self.tag_config.get("child_separator", None)
-        opening, closing = cast(tuple[ComponentType, ComponentType], super().htmy(context))
+        """Renders the component."""
+        name = self.htmy_name
+        props = self._htmy_format_props(context=context)
+        opening, closing = SafeStr(f"<{name} {props}>"), SafeStr(f"</{name}>")
+        separator = self.child_separator
         return (
             opening,
             *(
@@ -500,3 +575,33 @@ class Tag(TagWithProps):
             ),
             closing,
         )
+
+
+class WildcardTag(Tag):
+    """Tag that can have both children and properties, and whose tag name can be set."""
+
+    __slots__ = ("_child_separator",)
+
+    def __init__(
+        self,
+        *children: ComponentType,
+        htmy_name: str,
+        htmy_child_separator: ComponentType | None = None,
+        **props: PropertyValue,
+    ) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            *children: Children components.
+            htmy_name: The tag name to use for this tag.
+            htmy_child_separator: The child separator to use (if any).
+            **props: Tag properties.
+        """
+        super().__init__(*children, **props)
+        self._htmy_name = htmy_name
+        self._child_separator = htmy_child_separator
+
+    @property
+    def child_separator(self) -> ComponentType | None:
+        return self._child_separator

htmy-0.3.0/htmy/etree.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from collections.abc import Callable, Generator
+from typing import TYPE_CHECKING, ClassVar
+from xml.sax.saxutils import unescape
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from xml.etree.ElementTree import Element
+
+    from htmy.typing import ComponentType, Properties
+
+
+from htmy.core import Fragment, SafeStr, WildcardTag
+
+
+class ETreeConverter:
+    """
+    Utility for converting XML strings to custom HTMY components.
+    """
+
+    __slots__ = ("_rules",)
+
+    _htmy_fragment: ClassVar[str] = "htmy_fragment"
+    """
+    Placeholder tag name that's used to wrap possibly multi-root XML snippets into a valid
+    XML document with a single root that can be processed by standard tools.
+    """
+
+    def __init__(self, rules: Mapping[str, Callable[..., ComponentType]]) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            rules: Tag-name to HTMY component conversion rules.
+        """
+        self._rules = rules
+
+    def convert(self, element: str) -> ComponentType:
+        """Converts the given (possible multi-root) XML string to an HTMY component."""
+        if len(self._rules) == 0:
+            return SafeStr(element)
+
+        element = f"<{self._htmy_fragment}>{element}</{self._htmy_fragment}>"
+        return self.convert_element(ET.fromstring(element))  # noqa: S314 # Only use from XML strings from a trusted source.
+
+    def convert_element(self, element: Element) -> ComponentType:
+        """Converts the given `Element` to an HTMY component."""
+        rules = self._rules
+        if len(rules) == 0:
+            return SafeStr(ET.tostring(element))
+
+        tag: str = element.tag
+        component = Fragment if tag == self._htmy_fragment else rules.get(tag)
+        children = self._convert_children(element)
+        properties = self._convert_properties(element)
+
+        return (
+            WildcardTag(*children, htmy_name=tag, **properties)
+            if component is None
+            else component(
+                *children,
+                **properties,
+            )
+        )
+
+    def _convert_properties(self, element: Element) -> Properties:
+        """
+        Converts the attributes of the given `Element` to an HTMY `Properties` mapping.
+
+        This method should not alter property names in any way.
+        """
+        return {key: unescape(value) for key, value in element.items()}
+
+    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."""
+        if text := self._process_text(element.text):
+            yield text
+
+        for child in element:
+            yield self.convert_element(child)
+            if tail := self._process_text(child.tail):
+                yield tail
+
+    def _process_text(self, escaped_text: str | None) -> str | None:
+        """Processes a single XML-escaped text child."""
+        return unescape(escaped_text) if escaped_text else None

{htmy-0.1.0 → htmy-0.3.0}/htmy/html.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from .core import SafeStr, StandaloneTag, Tag, TagConfig, TagWithProps
+from .core import SafeStr, Tag, TagConfig, TagWithProps
 from .typing import PropertyValue
 
 
@@ -45,7 +45,7 @@ class body(Tag):
     __slots__ = ()
 
 
-class base(StandaloneTag):
+class base(TagWithProps):
     """
     `<base>` element.
 
@@ -70,7 +70,7 @@ class title(Tag):
         super().__init__(text, **props)
 
 
-class link(StandaloneTag):
+class link(TagWithProps):
     """
     `<link>` element.
 
@@ -84,7 +84,7 @@ class link(StandaloneTag):
         return cls(rel="stylesheet", type="text/css", href=href)
 
 
-class meta(StandaloneTag):
+class meta(TagWithProps):
     """
     `<meta>` element.
 
@@ -215,7 +215,7 @@ class div(Tag):
     __slots__ = ()
 
 
-class embed(StandaloneTag):
+class embed(TagWithProps):
     """
     `<embed>` element.
 
@@ -275,7 +275,7 @@ class hgroup(Tag):
     __slots__ = ()
 
 
-class hr(StandaloneTag):
+class hr(TagWithProps):
     """
     `<hr>` element.
 
@@ -366,6 +366,8 @@ class pre(Tag):
 
     __slots__ = ()
 
+    tag_config = _DefaultTagConfig.inline_children
+
 
 class section(Tag):
     """
@@ -457,7 +459,7 @@ class fieldset(Tag):
     __slots__ = ()
 
 
-class input_(StandaloneTag):
+class input_(TagWithProps):
     """
     `<input>` element.
 
@@ -466,8 +468,7 @@ class input_(StandaloneTag):
 
     __slots__ = ()
 
-    @property
-    def _htmy_name(self) -> str:
+    def _get_htmy_name(self) -> str:
         return "input"
 
 
@@ -611,7 +612,7 @@ class bdo(Tag):
     tag_config = _DefaultTagConfig.inline_children
 
 
-class br(StandaloneTag):
+class br(TagWithProps):
     """
     `<br>` element.
 
@@ -668,8 +669,7 @@ class del_(Tag):
 
     tag_config = _DefaultTagConfig.inline_children
 
-    @property
-    def _htmy_name(self) -> str:
+    def _get_htmy_name(self) -> str:
         return "del"
 
 
@@ -719,7 +719,7 @@ class picture(Tag):
     __slots__ = ()
 
 
-class img(StandaloneTag):
+class img(TagWithProps):
     """
     `<img>` element.
 
@@ -729,7 +729,7 @@ class img(StandaloneTag):
     __slots__ = ()
 
 
-class source(StandaloneTag):
+class source(TagWithProps):
     """
     `<source>` element.
 
@@ -1043,7 +1043,7 @@ class td(Tag):
     tag_config = _DefaultTagConfig.inline_children
 
 
-class colgroup(StandaloneTag):
+class colgroup(TagWithProps):
     """
     `<colgroup>` element.
 
@@ -1053,7 +1053,7 @@ class colgroup(StandaloneTag):
     __slots__ = ()
 
 
-class col(StandaloneTag):
+class col(TagWithProps):
     """
     `<col>` element.
 
@@ -1179,7 +1179,7 @@ class video(Tag):
     __slots__ = ()
 
 
-class track(StandaloneTag):
+class track(TagWithProps):
     """
     `<track>` element.
 
@@ -1199,7 +1199,7 @@ class canvas(Tag):
     __slots__ = ()
 
 
-class area(StandaloneTag):
+class area(TagWithProps):
     """
     `<area>` element.
 

htmy-0.3.0/htmy/i18n.py

@@ -0,0 +1,165 @@
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, ClassVar, overload
+
+from async_lru import alru_cache
+
+from .core import ContextAware
+from .io import open_file
+
+TranslationResource = Mapping[str, Any]
+"""Translation resource type."""
+
+
+class I18nError(Exception): ...
+
+
+class I18nKeyError(I18nError): ...
+
+
+class I18nValueError(I18nError): ...
+
+
+class I18n(ContextAware):
+    """
+    Context-aware async internationalization utility.
+    """
+
+    __slots__ = ("_path", "_fallback")
+
+    _root_keys: ClassVar[frozenset[str]] = frozenset(("", "."))
+    """Special keys that represent the "root" object, i.e. the entire translation resource file."""
+
+    def __init__(self, path: str | Path, fallback: str | Path | None = None) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            path: Path to the root directory that contains the translation resources.
+            fallback: Optional fallback path to use if `path` doesn't contain the required resources.
+        """
+        self._path: Path = Path(path) if isinstance(path, str) else path
+        self._fallback: Path | None = Path(fallback) if isinstance(fallback, str) else fallback
+
+    @overload
+    async def get(self, dotted_path: str, key: str) -> Any: ...
+
+    @overload
+    async def get(self, dotted_path: str, key: str, **kwargs: Any) -> str: ...
+
+    async def get(self, dotted_path: str, key: str, **kwargs: Any) -> Any:
+        """
+        Returns the translation resource at the given location.
+
+        If keyword arguments are provided, it's expected that the referenced data
+        is a [format string](https://docs.python.org/3/library/string.html#formatstrings)
+        which can be fully formatted using the given keyword arguments.
+
+        Arguments:
+            dotted_path: A package-like (dot separated) path to the file that contains
+                the required translation resource, relative to `path`.
+            key: The key in the translation resource whose value is requested. Use dots to reference
+                embedded attributes.
+
+        Returns:
+            The loaded value.
+
+        Raises:
+            I18nError: If the given translation resource is not found or invalid.
+        """
+        try:
+            return await self._resolve(self._path, dotted_path, key, **kwargs)
+        except I18nError:
+            if self._fallback is None:
+                raise
+
+            return await self._resolve(self._fallback, dotted_path, key, **kwargs)
+
+    @classmethod
+    async def _resolve(cls, root: Path, dotted_subpath: str, key: str, **kwargs: Any) -> Any:
+        """
+        Resolves the given translation resource.
+
+        Arguments:
+            root: The root path to use.
+            dotted_subpath: Subpath under `root` with dots as separators.
+            key: The key in the translation resource.
+
+        Returns:
+            The resolved translation resource.
+
+        Raises:
+            I18nKeyError: If the translation resource doesn't contain the requested key.
+            I18nValueError: If the translation resource is not found or its content is invalid.
+        """
+        result = await load_translation_resource(resolve_json_path(root, dotted_subpath))
+        if key in cls._root_keys:
+            return result
+
+        for k in key.split("."):
+            try:
+                result = result[k]
+            except KeyError as e:
+                raise I18nKeyError(f"Key not found: {key}") from e
+
+        if len(kwargs) > 0:
+            if not isinstance(result, str):
+                raise I18nValueError("Formatting is only supported for strings.")
+
+            return result.format(**kwargs)
+
+        return result
+
+
+@alru_cache(8)
+async def load_translation_resource(path: Path) -> TranslationResource:
+    """
+    Loads the translation resource from the given path.
+
+    Arguments:
+        path: The path of the translation resource to load.
+
+    Returns:
+        The loaded translation resource.
+
+    Raises:
+        I18nValueError: If the translation resource is not a JSON dict.
+    """
+
+    try:
+        async with await open_file(path, "r") as f:
+            content = await f.read()
+    except FileNotFoundError as e:
+        raise I18nValueError(f"Translation resource not found: {str(path)}") from e
+
+    try:
+        result = json.loads(content)
+    except json.JSONDecodeError as e:
+        raise I18nValueError("Translation resource decoding failed.") from e
+
+    if isinstance(result, dict):
+        return result
+
+    raise I18nValueError("Only dict translation resources are allowed.")
+
+
+def resolve_json_path(root: Path, dotted_subpath: str) -> Path:
+    """
+    Resolves the given dotted subpath relative to root.
+
+    Arguments:
+        root: The root path.
+        dotted_subpath: Subpath under `root` with dots as separators.
+
+    Returns:
+        The resolved path.
+
+    Raises:
+        I18nValueError: If the given dotted path is invalid.
+    """
+    *dirs, name = dotted_subpath.split(".")
+    if not name:
+        raise I18nValueError("Invalid path.")
+
+    return root / Path(*dirs) / f"{name}.json"

htmy-0.3.0/htmy/io.py

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

htmy-0.3.0/htmy/md/__init__.py

@@ -0,0 +1,6 @@
+from .core import MD as MD
+from .core import MarkdownParser as MarkdownParser
+from .typing import MarkdownMetadataDict as MarkdownMetadataDict
+from .typing import MarkdownParserFunction as MarkdownParserFunction
+from .typing import MarkdownRenderFunction as MarkdownRenderFunction
+from .typing import ParsedMarkdown as ParsedMarkdown

htmy-0.3.0/htmy/md/core.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+from markdown import Markdown
+
+from htmy.core import ContextAware, SafeStr, Snippet, Text
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+    from htmy.typing import Component, Context
+
+    from .typing import MarkdownParserFunction, MarkdownRenderFunction, ParsedMarkdown
+
+
+class MarkdownParser(ContextAware):
+    """
+    Context-aware markdown parser.
+
+    By default, this class uses the `markdown` library with a sensible set of
+    [extensions](https://python-markdown.github.io/extensions/) including code highlighing.
+    """
+
+    __slots__ = ("_md",)
+
+    _default: ClassVar[MarkdownParser | None] = None
+    """The default instance or `None` if one hasn't been created already."""
+
+    @classmethod
+    def default(cls) -> MarkdownParser:
+        """
+        Returns the default instance.
+        """
+        if cls._default is None:
+            cls._default = MarkdownParser()
+
+        return cls._default
+
+    def __init__(self, md: MarkdownParserFunction | None = None) -> None:
+        """
+        Initialization.
+
+        Arguments:
+            md: The parser function to use.
+        """
+        super().__init__()
+        self._md = md
+
+    def parse(self, text: str) -> ParsedMarkdown:
+        """
+        Returns the markdown data by parsing the given text.
+        """
+        md = self._md
+        if md is None:
+            md = self._default_md()
+            self._md = md
+
+        return md(text)
+
+    def _default_md(self) -> MarkdownParserFunction:
+        """
+        Function that creates the default markdown parser.
+
+        Returns:
+            The default parser function.
+        """
+        md = Markdown(extensions=("extra", "meta", "codehilite"))
+
+        def parse(text: str) -> ParsedMarkdown:
+            md.reset()
+            parsed = md.convert(text)
+            return {"content": parsed, "metadata": getattr(md, "Meta", None)}
+
+        return parse
+
+
+class MD(Snippet):
+    """Component for reading, customizing, and rendering markdown documents."""
+
+    __slots__ = (
+        "_converter",
+        "_renderer",
+    )
+
+    def __init__(
+        self,
+        path_or_text: Text | str | Path,
+        *,
+        converter: Callable[[str], Component] | None = None,
+        renderer: MarkdownRenderFunction | None = None,
+    ) -> None:
+        """
+        Initialization.
+
+        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.
+        """
+        super().__init__(path_or_text)
+        self._converter: Callable[[str], Component] = SafeStr if converter is None else converter
+        self._renderer = renderer
+
+    def _render_text(self, text: str, context: Context) -> Component:
+        md = MarkdownParser.from_context(context, MarkdownParser.default()).parse(text)
+        result = self._converter(md["content"])
+        return result if self._renderer is None else self._renderer(result, md.get("metadata", None))

htmy-0.3.0/htmy/md/typing.py

@@ -0,0 +1,20 @@
+from collections.abc import Callable
+from typing import Any, NotRequired, TypeAlias, TypedDict
+
+from htmy.typing import Component
+
+MarkdownMetadataDict: TypeAlias = dict[str, Any]
+
+
+class ParsedMarkdown(TypedDict):
+    """Type definition for parsed markdown data."""
+
+    content: str
+    metadata: NotRequired[MarkdownMetadataDict | None]
+
+
+MarkdownParserFunction: TypeAlias = Callable[[str], ParsedMarkdown]
+"""Callable that converts a markdown string into a `ParsedMarkdown` object."""
+
+MarkdownRenderFunction: TypeAlias = Callable[[Component, MarkdownMetadataDict | None], Component]
+"""Renderer function definition for markdown data."""

{htmy-0.1.0 → htmy-0.3.0}/htmy/typing.py

@@ -30,14 +30,18 @@ Context: TypeAlias = Mapping[ContextKey, ContextValue]
 class SyncComponent(Protocol):
     """Protocol definition for sync `htmy` components."""
 
-    def htmy(self, context: Context, /) -> "Component": ...
+    def htmy(self, context: Context, /) -> "Component":
+        """Renders the component."""
+        ...
 
 
 @runtime_checkable
 class AsyncComponent(Protocol):
     """Protocol definition for async `htmy` components."""
 
-    async def htmy(self, context: Context, /) -> "Component": ...
+    async def htmy(self, context: Context, /) -> "Component":
+        """Renders the component."""
+        ...
 
 
 HTMYComponentType: TypeAlias = SyncComponent | AsyncComponent
@@ -75,14 +79,18 @@ FunctionComponent: TypeAlias = SyncFunctionComponent[T] | AsyncFunctionComponent
 class SyncContextProvider(Protocol):
     """Protocol definition for sync context providers."""
 
-    def htmy_context(self) -> Context: ...
+    def htmy_context(self) -> Context:
+        """Returns an HTMY context for child rendering."""
+        ...
 
 
 @runtime_checkable
 class AsyncContextProvider(Protocol):
     """Protocol definition for async context providers."""
 
-    async def htmy_context(self) -> Context: ...
+    async def htmy_context(self) -> Context:
+        """Returns an HTMY context for child rendering."""
+        ...
 
 
 ContextProvider: TypeAlias = SyncContextProvider | AsyncContextProvider

{htmy-0.1.0 → htmy-0.3.0}/pyproject.toml

@@ -1,13 +1,16 @@
 [tool.poetry]
 name = "htmy"
-version = "0.1.0"
-description = "Async, zero-dependency, pure-Python rendering engine."
+version = "0.3.0"
+description = "Async, pure-Python rendering engine."
 authors = ["Peter Volf <do.volfp@gmail.com>"]
 license = "MIT"
 readme = "README.md"
 
 [tool.poetry.dependencies]
 python = "^3.11"
+anyio = "^4.6.2.post1"
+async-lru = "^2.0.4"
+markdown = "^3.7"
 
 [tool.poetry.group.dev.dependencies]
 mkdocs-material = "^9.5.39"
@@ -18,6 +21,7 @@ pytest = "^8.3.3"
 pytest-asyncio = "^0.24.0"
 pytest-random-order = "^1.1.1"
 ruff = "^0.6.8"
+types-markdown = "^3.7.0.20240822"
 
 [build-system]
 requires = ["poetry-core"]
@@ -27,6 +31,9 @@ build-backend = "poetry.core.masonry.api"
 strict = true
 show_error_codes = true
 
+[tool.pytest.ini_options]
+addopts = "--random-order"
+
 [tool.ruff]
 line-length = 108
 exclude = [
@@ -57,7 +64,7 @@ format = "ruff format ."
 lint = "ruff check ."
 lint-fix = "ruff . --fix"
 mypy = "mypy ."
-test = "python -m pytest tests --random-order"
+test = "python -m pytest tests"
 static-checks.sequence = ["lint", "check-format", "mypy"]
 static-checks.ignore_fail = "return_non_zero"
 serve-docs = "mkdocs serve"