Unify rich help rendering and widget projection

Author: trissim

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyqt-reactive"
-version = "0.1.23"
+version = "0.1.24"
 description = "React-quality reactive form generation framework for PyQt6"
 authors = [{name = "Tristan Simas", email = "tristan.simas@mail.mcgill.ca"}]
 license = {text = "MIT"}
@@ -24,6 +24,7 @@ classifiers = [
 keywords = ["pyqt6", "forms", "reactive", "gui", "widgets", "dataclass"]
 
 dependencies = [
+    "docutils>=0.20",
     "magicgui>=0.7.0",
     "metaclass-registry>=0.1.5",
     "PyQt6>=6.4.0",

src/pyqt_reactive/__init__.py

@@ -19,7 +19,7 @@
 - Cross-window reactive updates
 """
 
-__version__ = "0.1.23"
+__version__ = "0.1.24"
 
 # Public API will be populated as modules are added
 __all__ = [

src/pyqt_reactive/services/help_document.py

@@ -0,0 +1,219 @@
+"""Generic rich help-document content shared by help surfaces."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, replace
+from enum import StrEnum
+from pathlib import PurePath
+from typing import Protocol
+
+from docutils.core import publish_parts
+
+DEFAULT_HELP_DOCUMENT_MAX_CHARS = 50_000
+
+
+class HelpDocumentFormat(StrEnum):
+    """Markup format owned by one help document."""
+
+    PLAIN_TEXT = "plain_text"
+    MARKDOWN = "markdown"
+    RESTRUCTURED_TEXT = "restructured_text"
+
+    @classmethod
+    def from_source_path(cls, source_path: str) -> HelpDocumentFormat:
+        """Resolve markup from a source document's declared filename."""
+        suffix = PurePath(source_path).suffix.casefold()
+        if suffix in {".md", ".markdown"}:
+            return cls.MARKDOWN
+        if suffix == ".rst":
+            return cls.RESTRUCTURED_TEXT
+        return cls.PLAIN_TEXT
+
+
+class DocstringInfoLike(Protocol):
+    """Structured callable/class documentation consumed by the renderer."""
+
+    summary: str | None
+    description: str | None
+    parameters: dict[str, str] | None
+    returns: str | None
+    examples: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class HelpDocument:
+    """One renderer-ready help document with explicit markup provenance."""
+
+    content: str
+    markup: HelpDocumentFormat = HelpDocumentFormat.PLAIN_TEXT
+    title: str | None = None
+    base_url: str | None = None
+
+    @classmethod
+    def from_docstring_info(
+        cls,
+        docstring_info: DocstringInfoLike,
+        *,
+        title: str | None = None,
+    ) -> HelpDocument:
+        """Project structured introspection into one Markdown document."""
+        sections: list[str] = []
+        if title:
+            sections.append(f"# {_markdown_heading(title)}")
+        if docstring_info.summary:
+            sections.append(f"**{_markdown_inline(docstring_info.summary)}**")
+        if docstring_info.description:
+            sections.append(docstring_info.description.strip())
+        if docstring_info.parameters:
+            parameter_sections = ["## Parameters"]
+            for name, description in docstring_info.parameters.items():
+                parameter_sections.append(f"### {_markdown_code_span(name)}")
+                if description:
+                    parameter_sections.append(description.strip())
+            sections.append("\n\n".join(parameter_sections))
+        if docstring_info.returns:
+            sections.append(f"## Returns\n\n{docstring_info.returns.strip()}")
+        if docstring_info.examples:
+            fence = _code_fence(docstring_info.examples)
+            sections.append(
+                f"## Examples\n\n{fence}python\n"
+                f"{docstring_info.examples.rstrip()}\n{fence}"
+            )
+        return cls(
+            content="\n\n".join(section for section in sections if section),
+            markup=HelpDocumentFormat.MARKDOWN,
+            title=title,
+        )
+
+    @classmethod
+    def from_parameter_content(
+        cls,
+        *,
+        summary: str,
+        description: str,
+        title: str | None = None,
+    ) -> HelpDocument:
+        """Project one parameter-help response into the shared document model."""
+        sections = []
+        if title:
+            sections.append(f"# {_markdown_heading(title)}")
+        if summary:
+            sections.append(f"**{_markdown_inline(summary)}**")
+        if description:
+            sections.append(description.strip())
+        return cls(
+            content="\n\n".join(sections),
+            markup=HelpDocumentFormat.MARKDOWN,
+            title=title,
+        )
+
+    def rendered_html(self) -> str:
+        """Render reStructuredText safely for Qt's rich-text engine."""
+        if self.markup is not HelpDocumentFormat.RESTRUCTURED_TEXT:
+            raise ValueError(
+                "rendered_html() is only valid for reStructuredText documents"
+            )
+        parts = publish_parts(
+            self.content,
+            writer="html5",
+            settings_overrides={
+                "raw_enabled": False,
+                "file_insertion_enabled": False,
+                "report_level": 5,
+                "halt_level": 6,
+                "output_encoding": "unicode",
+                "embed_stylesheet": False,
+            },
+        )
+        return str(parts["html_body"])
+
+    def bounded(
+        self,
+        max_chars: int = DEFAULT_HELP_DOCUMENT_MAX_CHARS,
+    ) -> HelpDocument:
+        """Return this document with a renderer-safe content bound."""
+        if max_chars < 1:
+            raise ValueError("max_chars must be at least 1")
+        if len(self.content) <= max_chars:
+            return self
+        if max_chars < 4:
+            content = f"{self.content[: max_chars - 1]}…"
+        else:
+            content = f"{self.content[: max_chars - 3].rstrip()}\n\n…"
+        return replace(self, content=content)
+
+    def without_leading_heading(self, expected_title: str) -> HelpDocument:
+        """Remove a matching source heading when chrome already displays it."""
+        lines = self.content.splitlines()
+        first_content_index = next(
+            (index for index, line in enumerate(lines) if line.strip()),
+            None,
+        )
+        if first_content_index is None:
+            return self
+        normalized_expected = _normalized_heading(expected_title)
+
+        if self.markup is HelpDocumentFormat.MARKDOWN:
+            match = re.match(r"^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$", lines[first_content_index])
+            if (
+                match is None
+                or _normalized_heading(match.group(1)) != normalized_expected
+            ):
+                return self
+            del lines[first_content_index]
+        elif self.markup is HelpDocumentFormat.RESTRUCTURED_TEXT:
+            underline_index = first_content_index + 1
+            if underline_index >= len(lines):
+                return self
+            title = lines[first_content_index].strip()
+            underline = lines[underline_index].strip()
+            if (
+                _normalized_heading(title) != normalized_expected
+                or len(set(underline)) != 1
+                or next(iter(set(underline)), "") not in "=-~^\"'`:+*#<>_"
+                or len(underline) < len(title)
+            ):
+                return self
+            del lines[first_content_index : underline_index + 1]
+        else:
+            return self
+
+        while lines and not lines[0].strip():
+            del lines[0]
+        return replace(self, content="\n".join(lines))
+
+
+def _markdown_heading(value: str) -> str:
+    return " ".join(value.split()).replace("#", r"\#")
+
+
+def _markdown_inline(value: str) -> str:
+    normalized = " ".join(value.split())
+    return re.sub(r"([\\`*_[\]<>])", r"\\\1", normalized)
+
+
+def _markdown_code_span(value: str) -> str:
+    delimiter = "`" * max(1, _longest_character_run(value, "`") + 1)
+    padding = " " if value.startswith(("`", " ")) or value.endswith(("`", " ")) else ""
+    return f"{delimiter}{padding}{value}{padding}{delimiter}"
+
+
+def _code_fence(value: str) -> str:
+    return "`" * max(3, _longest_character_run(value, "`") + 1)
+
+
+def _longest_character_run(value: str, target: str) -> int:
+    longest_run = 0
+    current_run = 0
+    for character in value:
+        if character == target:
+            current_run += 1
+            longest_run = max(longest_run, current_run)
+        else:
+            current_run = 0
+    return longest_run
+
+
+def _normalized_heading(value: str) -> str:
+    return " ".join(value.split()).casefold()

src/pyqt_reactive/services/widget_tree_projection_config.py

@@ -2,14 +2,64 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
-from typing import TypeAlias
-
+from collections.abc import Callable
+from dataclasses import dataclass, field, fields, is_dataclass
+from typing import Any, TypeAlias
 
 DEFAULT_MAXIMUM_WIDGET_TEXT_LENGTH = 4096
 DEFAULT_MAXIMUM_ITEM_MODEL_NODES = 512
 DEFAULT_TEXT_TRUNCATION_SUFFIX = "...<truncated>"
 WidgetPath: TypeAlias = tuple[int, ...]
+CompactFieldPredicate: TypeAlias = Callable[[object, object], bool]
+COMPACT_FIELD_PROJECTION_METADATA_KEY = "compact_field_projection"
+
+
+@dataclass(frozen=True, slots=True)
+class CompactFieldProjection:
+    """Declaration-owned rules for one field in a compact dataclass projection."""
+
+    includes: CompactFieldPredicate
+
+
+def always_project_compact_field(_owner: object, _value: object) -> bool:
+    """Retain a field even when its current value is otherwise empty."""
+
+    return True
+
+
+def _compact_value_carries_information(value: object) -> bool:
+    if value is None:
+        return False
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (str, bytes, tuple, list, dict, set, frozenset)):
+        return bool(value)
+    return True
+
+
+def compact_dataclass_projection(value: object) -> dict[str, Any]:
+    """Project one dataclass through its field-owned compactness declarations."""
+
+    if isinstance(value, type) or not is_dataclass(value):
+        raise TypeError(
+            f"Compact projection requires a dataclass instance, got {value!r}."
+        )
+    projected: dict[str, Any] = {}
+    for declared_field in fields(value):
+        field_value = getattr(value, declared_field.name)
+        policy = declared_field.metadata.get(COMPACT_FIELD_PROJECTION_METADATA_KEY)
+        if policy is None:
+            includes = _compact_value_carries_information(field_value)
+        elif isinstance(policy, CompactFieldProjection):
+            includes = policy.includes(value, field_value)
+        else:
+            raise TypeError(
+                f"{type(value).__name__}.{declared_field.name} declares an invalid "
+                "compact field projection."
+            )
+        if includes:
+            projected[declared_field.name] = field_value
+    return projected
 
 
 @dataclass(frozen=True, slots=True)
@@ -24,10 +74,34 @@ class WidgetTextProjection:
 class WidgetNodeIdentity:
     """Stable widget identity fields shared by projector and transport DTOs."""
 
-    path: WidgetPath
-    path_id: str
-    child_index: int | None
-    class_name: str
+    path: WidgetPath = field(
+        metadata={
+            COMPACT_FIELD_PROJECTION_METADATA_KEY: CompactFieldProjection(
+                includes=always_project_compact_field
+            )
+        }
+    )
+    path_id: str = field(
+        metadata={
+            COMPACT_FIELD_PROJECTION_METADATA_KEY: CompactFieldProjection(
+                includes=always_project_compact_field
+            )
+        }
+    )
+    child_index: int | None = field(
+        metadata={
+            COMPACT_FIELD_PROJECTION_METADATA_KEY: CompactFieldProjection(
+                includes=always_project_compact_field
+            )
+        }
+    )
+    class_name: str = field(
+        metadata={
+            COMPACT_FIELD_PROJECTION_METADATA_KEY: CompactFieldProjection(
+                includes=always_project_compact_field
+            )
+        }
+    )
     object_name: str
     accessible_name: str
     accessible_description: str