pyjinhx 0.2.2__py3-none-any.whl

pyjinhx/__init__.py

@@ -0,0 +1,15 @@
+from .base import BaseComponent
+from .dataclasses import Tag
+from .finder import Finder
+from .parser import Parser
+from .registry import Registry
+from .renderer import Renderer
+
+__all__ = [
+    "BaseComponent",
+    "Renderer",
+    "Finder",
+    "Parser",
+    "Registry",
+    "Tag",
+]

pyjinhx/base.py

@@ -0,0 +1,184 @@
+import logging
+from typing import Any, Optional
+
+from markupsafe import Markup
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from .registry import Registry
+from .renderer import Renderer, RenderSession
+
+logger = logging.getLogger("pyjinhx")
+logger.setLevel(logging.WARNING)
+
+
+class NestedComponentWrapper(BaseModel):
+    """
+    A wrapper for nested components. Enables access to the component's properties and rendered HTML.
+
+    Attributes:
+        html: The rendered HTML string of the nested component.
+        props: The original component instance, or None for template-only components.
+    """
+
+    html: str
+    props: Optional["BaseComponent"]
+
+    def __str__(self) -> Markup:
+        return self.html
+
+
+class BaseComponent(BaseModel):
+    """
+    Base class for defining reusable UI components with Pydantic validation and Jinja2 templating.
+
+    Subclasses are automatically registered and can be rendered using their corresponding
+    HTML/Jinja templates. Components support nested composition, automatic JavaScript collection,
+    and can be used directly in Jinja templates via the `__html__` protocol.
+
+    Attributes:
+        id: Unique identifier for the component instance.
+        js: Paths to additional JavaScript files to include when rendering.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    id: str = Field(..., description="The unique ID for this component.")
+    js: list[str] = Field(
+        default_factory=list,
+        description="List of paths to extra JavaScript files to include.",
+    )
+
+    @field_validator("id", mode="before")
+    def validate_id(cls, v):
+        if not v:
+            raise ValueError("ID is required")
+        return str(v)
+
+    def __init_subclass__(cls, **kwargs):
+        """Automatically register the component class at definition time."""
+        super().__init_subclass__(**kwargs)
+        Registry.register_class(cls)
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        Registry.register_instance(self)
+
+    def __html__(self) -> Markup:
+        """
+        Render the component when used in a Jinja template context.
+
+        Enables cleaner template syntax: `{{ component }}` instead of `{{ component.render() }}`.
+
+        Returns:
+            The rendered HTML as a Markup object.
+        """
+        return self._render()
+
+    def _update_context_(
+        self,
+        context: dict[str, Any],
+        field_name: str,
+        field_value: Any,
+        *,
+        renderer: Renderer,
+        session: RenderSession,
+    ) -> dict[str, Any]:
+        """
+        Updates the context with rendered components by their ID.
+        """
+        if isinstance(field_value, BaseComponent):
+            context[field_name] = NestedComponentWrapper(
+                html=field_value._render(
+                    base_context=context,
+                    _renderer=renderer,
+                    _session=session,
+                ),
+                props=field_value,
+            )
+        elif isinstance(field_value, list):
+            processed_list = []
+            for item in field_value:
+                if isinstance(item, BaseComponent):
+                    processed_list.append(
+                        NestedComponentWrapper(
+                            html=item._render(
+                                base_context=context,
+                                _renderer=renderer,
+                                _session=session,
+                            ),
+                            props=item,
+                        )
+                    )
+                else:
+                    processed_list.append(item)
+            if processed_list:
+                context[field_name] = processed_list
+        elif isinstance(field_value, dict):
+            processed_dict = {}
+            for key, value in field_value.items():
+                if isinstance(value, BaseComponent):
+                    processed_dict[key] = NestedComponentWrapper(
+                        html=value._render(
+                            base_context=context,
+                            _renderer=renderer,
+                            _session=session,
+                        ),
+                        props=value,
+                    )
+                else:
+                    processed_dict[key] = value
+            if processed_dict:
+                context[field_name] = processed_dict
+        return context
+
+    def _render(
+        self,
+        source: str | None = None,
+        base_context: dict[str, Any] | None = None,
+        *,
+        _renderer: Renderer | None = None,
+        _session: RenderSession | None = None,
+        _template_path: str | None = None,
+    ) -> Markup:
+        renderer = _renderer or Renderer.get_default_renderer()
+
+        is_root = base_context is None and _session is None
+        session = _session or renderer.new_session()
+
+        if base_context is None:
+            context: dict[str, Any] = self.model_dump()
+        else:
+            context = {**base_context, **self.model_dump()}
+
+        for field_name in type(self).model_fields.keys():
+            field_value = getattr(self, field_name)
+            context = self._update_context_(
+                context,
+                field_name,
+                field_value,
+                renderer=renderer,
+                session=session,
+            )
+
+        return renderer.render_component_with_context(
+            self,
+            context=context,
+            template_source=source,
+            template_path=_template_path,
+            session=session,
+            is_root=is_root,
+            collect_component_js=source is None,
+        )
+
+    def render(self) -> Markup:
+        """
+        Render this component to HTML using its associated Jinja template.
+
+        The template is auto-discovered based on the component class name (e.g., `MyButton` looks
+        for `my_button.html` or `my_button.jinja`). All component fields are available in the
+        template context, and nested components are rendered recursively.
+
+        Returns:
+            The rendered HTML as a Markup object (safe for direct use in templates).
+        """
+        return self._render()

pyjinhx/dataclasses.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass, field
+
+@dataclass
+class Tag:
+    """
+    Represents a parsed HTML/component tag with its attributes and children.
+
+    Used by the Parser to build a tree structure from HTML-like markup containing
+    PascalCase component tags (e.g., `<MyButton text="OK">`).
+
+    Attributes:
+        name: The tag name (e.g., "MyButton", "div").
+        attrs: Dictionary of attribute names to values.
+        children: Nested tags or raw text content within this tag.
+    """
+
+    name: str
+    attrs: dict[str, str]
+    children: list["Tag | str"] = field(default_factory=list)

pyjinhx/finder.py

@@ -0,0 +1,257 @@
+import inspect
+import os
+from dataclasses import dataclass, field
+
+from jinja2 import FileSystemLoader
+
+from .utils import (
+    detect_root_directory,
+    normalize_path_separators,
+    pascal_case_to_snake_case,
+    tag_name_to_template_filenames,
+)
+
+
+@dataclass
+class Finder:
+    """
+    Find files under a root directory.
+
+    Centralizes template discovery logic with caching to avoid repeated directory walks.
+
+    Attributes:
+        root: The root directory to search within.
+    """
+
+    root: str
+    _index: dict[str, str] = field(default_factory=dict, init=False)
+    _is_indexed: bool = field(default=False, init=False)
+
+    # ---------
+    # Helpers
+    # ---------
+
+    def _build_index(self) -> None:
+        if self._is_indexed:
+            return
+
+        for current_root, dir_names, file_names in os.walk(self.root):
+            dir_names.sort()
+            file_names.sort()
+            for file_name in file_names:
+                self._index.setdefault(file_name, os.path.join(current_root, file_name))
+
+        self._is_indexed = True
+
+    @staticmethod
+    def get_loader_root(loader: FileSystemLoader) -> str:
+        """
+        Return the first search root from a Jinja FileSystemLoader.
+
+        Jinja allows searchpath to be a string or a list of strings; PyJinHx uses the first entry.
+
+        Args:
+            loader: The Jinja FileSystemLoader to extract the root from.
+
+        Returns:
+            The first search path directory.
+        """
+        search_path = loader.searchpath
+        if isinstance(search_path, list):
+            return search_path[0]
+        return search_path
+
+    @staticmethod
+    def detect_root_directory(
+        start_directory: str | None = None,
+        project_markers: list[str] | None = None,
+    ) -> str:
+        """
+        Find the project root by walking upward from a starting directory until a marker file is found.
+
+        Args:
+            start_directory: Directory to start searching from. Defaults to current working directory.
+            project_markers: Files/directories indicating project root (e.g., "pyproject.toml", ".git").
+
+        Returns:
+            The detected project root directory, or the start directory if no marker is found.
+        """
+        return detect_root_directory(
+            start_directory=start_directory,
+            project_markers=project_markers,
+        )
+
+    @staticmethod
+    def find_in_directory(directory: str, filename: str) -> str | None:
+        """
+        Check if a file exists directly in a directory (no recursive search).
+
+        Useful for component-adjacent assets (e.g., auto-discovered JS files).
+
+        Args:
+            directory: The directory to check.
+            filename: The filename to look for.
+
+        Returns:
+            The full path to the file if it exists, or None otherwise.
+        """
+        candidate_path = os.path.join(directory, filename)
+        if os.path.exists(candidate_path):
+            return candidate_path
+        return None
+
+    @staticmethod
+    def get_class_directory(component_class: type) -> str:
+        """
+        Return the directory containing the given class's source file.
+
+        Args:
+            component_class: The class to locate.
+
+        Returns:
+            The directory path with normalized separators.
+
+        Example:
+            >>> Finder.get_class_directory(Button)
+            '/app/components/ui'
+        """
+        return normalize_path_separators(
+            os.path.dirname(inspect.getfile(component_class))
+        )
+
+    @staticmethod
+    def get_relative_template_path(
+        component_dir: str, search_root: str, component_name: str
+    ) -> str:
+        """
+        Compute the template path relative to the Jinja loader root.
+
+        Args:
+            component_dir: Absolute path to the component's directory.
+            search_root: The Jinja loader's root directory.
+            component_name: The PascalCase component name.
+
+        Returns:
+            The relative template path (e.g., "components/ui/button.html").
+
+        Example:
+            >>> Finder.get_relative_template_path("/app/components/ui", "/app", "Button")
+            'components/ui/button.html'
+        """
+        relative_dir = normalize_path_separators(
+            os.path.relpath(component_dir, search_root)
+        )
+        filename = f"{pascal_case_to_snake_case(component_name)}.html"
+        return f"{relative_dir}/{filename}"
+
+    @staticmethod
+    def get_relative_template_paths(
+        component_dir: str,
+        search_root: str,
+        component_name: str,
+        *,
+        extensions: tuple[str, ...] = (".html", ".jinja"),
+    ) -> list[str]:
+        """
+        Compute candidate template paths relative to the Jinja loader root.
+
+        Args:
+            component_dir: Absolute path to the component's directory.
+            search_root: The Jinja loader's root directory.
+            component_name: The PascalCase component name.
+            extensions: File extensions to try, in order of preference.
+
+        Returns:
+            List of relative template paths to try during auto-lookup.
+        """
+        relative_dir = normalize_path_separators(
+            os.path.relpath(component_dir, search_root)
+        )
+        snake_name = pascal_case_to_snake_case(component_name)
+        return [f"{relative_dir}/{snake_name}{extension}" for extension in extensions]
+
+    # ------------------
+    # Public instance API
+    # ------------------
+
+    def find(self, filename: str) -> str:
+        """
+        Find a file by name under the root directory.
+
+        Args:
+            filename: The filename to search for.
+
+        Returns:
+            The full path to the first matching file.
+
+        Raises:
+            FileNotFoundError: If the file cannot be found under root.
+        """
+        self._build_index()
+        found_path = self._index.get(filename)
+        if found_path is None:
+            raise FileNotFoundError(f"Template not found: {filename} under {self.root}")
+        return found_path
+
+    def find_template_for_tag(self, tag_name: str) -> str:
+        """
+        Resolve a PascalCase component tag name to its template path.
+
+        Tries multiple extensions (.html, .jinja) in order of preference.
+
+        Args:
+            tag_name: The PascalCase component tag name (e.g., "ButtonGroup").
+
+        Returns:
+            The full path to the template file.
+
+        Raises:
+            FileNotFoundError: If no matching template is found.
+
+        Example:
+            >>> finder.find_template_for_tag("ButtonGroup")
+            '/app/components/button_group.html'
+        """
+        last_error: FileNotFoundError | None = None
+        for candidate_filename in tag_name_to_template_filenames(tag_name):
+            try:
+                return self.find(candidate_filename)
+            except FileNotFoundError as exc:
+                last_error = exc
+        if last_error is None:
+            raise FileNotFoundError(
+                f"Template not found for tag: {tag_name} under {self.root}"
+            )
+        raise last_error
+
+    def collect_javascript_files(self, relative_to_root: bool = False) -> list[str]:
+        """
+        Collect all JavaScript files under `root`.
+
+        Args:
+            relative_to_root: If True, return paths relative to `root` (useful for building static file lists).
+                              If False, return absolute paths.
+
+        Returns:
+            A deterministic, sorted list of `.js` file paths (directories and file names are walked in sorted order).
+        """
+        javascript_files: list[str] = []
+
+        if not os.path.exists(self.root):
+            return javascript_files
+
+        for current_root, dir_names, file_names in os.walk(self.root):
+            dir_names.sort()
+            file_names.sort()
+            for file_name in file_names:
+                if not file_name.lower().endswith(".js"):
+                    continue
+                full_path = os.path.join(current_root, file_name)
+                if relative_to_root:
+                    javascript_files.append(
+                        normalize_path_separators(os.path.relpath(full_path, self.root))
+                    )
+                else:
+                    javascript_files.append(normalize_path_separators(full_path))
+
+        return javascript_files

pyjinhx/parser.py

@@ -0,0 +1,70 @@
+import re
+from html.parser import HTMLParser
+
+from .dataclasses import Tag
+from .utils import extract_tag_name_from_raw
+
+RE_PASCAL_CASE_TAG_NAME = re.compile(r"^[A-Z](?:[a-z]+(?:[A-Z][a-z]+)*)?$")
+
+
+class Parser(HTMLParser):
+    """
+    HTML parser that identifies PascalCase component tags and builds a tree of Tag nodes.
+
+    Standard HTML tags are passed through as raw strings, while PascalCase tags (e.g., `<MyButton>`)
+    are parsed into Tag objects for component rendering. After calling `feed(html)`, the parsed
+    structure is available in `root_nodes`.
+
+    Attributes:
+        root_nodes: List of top-level parsed nodes (Tag objects or raw HTML strings).
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._stack: list[Tag] = []
+        self.root_nodes: list[Tag | str] = []
+
+    def _is_custom_component(self, tag_name: str) -> bool:
+        return bool(RE_PASCAL_CASE_TAG_NAME.match(tag_name))
+
+    def _attrs_to_dict(self, attrs: list[tuple[str, str | None]]) -> dict[str, str]:
+        return {attr_name: (attr_value or "") for attr_name, attr_value in attrs}
+
+    def _append_child(self, node: Tag | str) -> None:
+        if self._stack:
+            self._stack[-1].children.append(node)
+        else:
+            self.root_nodes.append(node)
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        raw = self.get_starttag_text() or f"<{tag}>"
+        original_tag_name = extract_tag_name_from_raw(raw) or tag
+
+        if self._is_custom_component(original_tag_name):
+            tag_node = Tag(name=original_tag_name, attrs=self._attrs_to_dict(attrs))
+            self._stack.append(tag_node)
+            return
+
+        self._append_child(raw)
+
+    def handle_startendtag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        raw = self.get_starttag_text() or f"<{tag} />"
+        original_tag_name = extract_tag_name_from_raw(raw) or tag
+
+        if self._is_custom_component(original_tag_name):
+            tag_node = Tag(name=original_tag_name, attrs=self._attrs_to_dict(attrs))
+            self._append_child(tag_node)
+            return
+
+        self._append_child(raw)
+
+    def handle_endtag(self, tag: str) -> None:
+        if self._stack and self._stack[-1].name.lower() == tag.lower():
+            tag_node = self._stack.pop()
+            self._append_child(tag_node)
+            return
+
+        self._append_child(f"</{tag}>")
+
+    def handle_data(self, data: str) -> None:
+        self._append_child(data)

pyjinhx/registry.py

@@ -0,0 +1,92 @@
+import logging
+from contextvars import ContextVar
+from typing import TYPE_CHECKING, ClassVar
+
+logger = logging.getLogger("pyjinhx")
+
+if TYPE_CHECKING:
+    from .base import BaseComponent
+
+
+_registry_context: ContextVar[dict[str, "BaseComponent"]] = ContextVar(
+    "component_registry", default={}
+)
+
+
+class Registry:
+    """
+    Central registry for component classes and instances.
+
+    Provides two registries:
+    - Class registry: Maps component class names to their types (process-wide).
+    - Instance registry: Maps component IDs to instances (context-local, thread-safe).
+
+    Component classes are auto-registered when subclassing BaseComponent. Instances are
+    registered upon instantiation, enabling cross-referencing in templates by ID.
+    """
+
+    _class_registry: ClassVar[dict[str, type["BaseComponent"]]] = {}
+
+    @classmethod
+    def register_class(cls, component_class: type["BaseComponent"]) -> None:
+        """
+        Register a component class by its name.
+
+        Called automatically when subclassing BaseComponent.
+
+        Args:
+            component_class: The component class to register.
+        """
+        class_name = component_class.__name__
+        if class_name in cls._class_registry:
+            logger.warning(
+                f"Component class {class_name} is already registered. Overwriting..."
+            )
+        cls._class_registry[class_name] = component_class
+
+    @classmethod
+    def get_classes(cls) -> dict[str, type["BaseComponent"]]:
+        """
+        Return a copy of all registered component classes.
+
+        Returns:
+            Dictionary mapping class names to component class types.
+        """
+        return cls._class_registry.copy()
+
+    @classmethod
+    def clear_classes(cls) -> None:
+        """Remove all registered component classes. Useful for testing."""
+        cls._class_registry.clear()
+
+    @classmethod
+    def register_instance(cls, component: "BaseComponent") -> None:
+        """
+        Register a component instance by its ID.
+
+        Called automatically on instantiation.
+
+        Args:
+            component: The component instance to register.
+        """
+        registry = _registry_context.get()
+        if component.id in registry:
+            logger.warning(
+                f"While registering{component.__class__.__name__}(id={component.id}) found an existing component with the same id. Overwriting..."
+            )
+        registry[component.id] = component
+
+    @classmethod
+    def get_instances(cls) -> dict[str, "BaseComponent"]:
+        """
+        Return all registered component instances in the current context.
+
+        Returns:
+            Dictionary mapping component IDs to component instances.
+        """
+        return _registry_context.get()
+
+    @classmethod
+    def clear_instances(cls) -> None:
+        """Remove all registered component instances from the current context."""
+        _registry_context.set({})