htmy 0.2.0__tar.gz → 0.3.0__tar.gz

{htmy-0.2.0 → htmy-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: htmy
-Version: 0.2.0
+Version: 0.3.0
 Summary: Async, pure-Python rendering engine.
 License: MIT
 Author: Peter Volf
@@ -12,6 +12,7 @@ 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
 
@@ -34,6 +35,8 @@ 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.
@@ -157,10 +160,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).
+- `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.
-- `md`: `MarkdownParser` utility and `MD` component for loading, parsing, converting, and rendering markdown content.
 - `etree.ETreeConverter`: utility that converts XML to a component tree with support for custom HTMY components.
 
 ### Rendering
@@ -307,6 +311,7 @@ The primary aim of `htmy` is to be an **async**, pure-Python rendering engine, w
 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

{htmy-0.2.0 → htmy-0.3.0}/README.md

@@ -17,6 +17,8 @@
 - **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.
@@ -140,10 +142,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).
+- `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.
-- `md`: `MarkdownParser` utility and `MD` component for loading, parsing, converting, and rendering markdown content.
 - `etree.ETreeConverter`: utility that converts XML to a component tree with support for custom HTMY components.
 
 ### Rendering
@@ -290,6 +293,7 @@ The primary aim of `htmy` is to be an **async**, pure-Python rendering engine, w
 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

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.2.0 → htmy-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "htmy"
-version = "0.2.0"
+version = "0.3.0"
 description = "Async, pure-Python rendering engine."
 authors = ["Peter Volf <do.volfp@gmail.com>"]
 license = "MIT"
@@ -9,6 +9,7 @@ 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]
@@ -30,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 = [
@@ -60,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"