dataops-sdk 0.3.0__py3-none-any.whl

dataops_sdk/tiptap/renderers.py

@@ -0,0 +1,51 @@
+"""Renderer interfaces for TipTap nodes and marks.
+
+Defines protocols for node renderers and mark renderers that convert
+TipTap JSON nodes to Markdown format.
+"""
+
+from collections.abc import Callable
+from typing import Protocol
+
+# Type alias for node renderer functions
+# Args: tool, node, content, parent_type, index
+NodeRendererFn = Callable[["TipTapTool", dict, str, str | None, int], str]
+
+# Type alias for mark renderer (returns tuple of opening and closing strings)
+MarkRendererFn = Callable[[], tuple[str, str]]
+
+
+class NodeRenderer(Protocol):
+    """Protocol for node renderers.
+
+    Renders a TipTap node to Markdown format.
+
+    Args:
+        tool: TipTapTool instance
+        node: The node to render
+        content: Rendered child content
+        parent_type: Parent node type
+        index: Index of this node in parent
+
+    Returns:
+        Markdown formatted string
+    """
+
+    def __call__(
+        self,
+        tool: "TipTapTool",
+        node: dict,
+        content: str,
+        parent_type: str | None,
+        index: int,
+    ) -> str: ...
+
+
+class MarkRenderer(Protocol):
+    """Protocol for mark renderers.
+
+    Provides opening and closing syntax for inline marks.
+    """
+
+    opening: str
+    closing: str

dataops_sdk/tiptap/tool.py

@@ -0,0 +1,629 @@
+"""Core TipTap tool for JSON <-> Markdown conversion."""
+
+import logging
+from collections.abc import Callable
+
+from dataops_sdk.tiptap import constants, parse_utils, render_utils
+from dataops_sdk.tiptap.markdown_parser import MarkdownToTipTapParser
+
+logger = logging.getLogger(__package__)
+
+
+class TipTapTool:
+    """Main class for TipTap JSON <-> Markdown conversion.
+
+    Supports:
+    - serialize(): Convert TipTap JSON to Markdown
+    - parse(): Convert Markdown to TipTap JSON
+
+    Attributes:
+        indent_style: Indent style (space or tab)
+        indent_size: Number of indent characters
+        table_style: Table rendering style (markdown or html)
+    """
+
+    def __init__(
+        self,
+        indent_style: str = constants.Style.INDENT_STYLE_SPACE,
+        indent_size: int = constants.Style.DEFAULT_INDENT_SIZE,
+        table_style: str = constants.Style.DEFAULT_TABLE_STYLE,
+    ) -> None:
+        self.indent_style = indent_style
+        self.indent_size = indent_size
+        self.table_style = table_style
+        self._node_renderers: dict[str, Callable] = {}
+        self._mark_renderers: dict[str, tuple[str, str]] = {}
+        self._register_default_renderers()
+
+    @property
+    def indent_character(self) -> str:
+        """Get the indent character."""
+        return "\t" if self.indent_style == constants.IndentStyle.TAB else " "
+
+    @property
+    def indent_string(self) -> str:
+        """Get the indent string."""
+        return self.indent_character * self.indent_size
+
+    # ==========================================================================
+    # Renderer Registration
+    # ==========================================================================
+
+    def register_node_renderer(
+        self,
+        node_type: str,
+        renderer: Callable,
+    ) -> "TipTapTool":
+        """Register a node renderer.
+
+        Args:
+            node_type: Node type to register
+            renderer: Renderer function
+
+        Returns:
+            self for chaining
+        """
+        self._node_renderers[node_type] = renderer
+        return self
+
+    def register_mark_renderer(
+        self,
+        mark_type: str,
+        opening: str,
+        closing: str,
+    ) -> "TipTapTool":
+        """Register a mark renderer.
+
+        Args:
+            mark_type: Mark type to register
+            opening: Opening syntax
+            closing: Closing syntax
+
+        Returns:
+            self for chaining
+        """
+        self._mark_renderers[mark_type] = (opening, closing)
+        return self
+
+    def get_node_renderer(self, node_type: str) -> Callable | None:
+        """Get a registered node renderer.
+
+        Args:
+            node_type: Node type
+
+        Returns:
+            Renderer function or None
+        """
+        return self._node_renderers.get(node_type)
+
+    def get_mark_renderer(self, mark_type: str) -> tuple[str, str] | None:
+        """Get a registered mark renderer.
+
+        Args:
+            mark_type: Mark type
+
+        Returns:
+            Tuple of (opening, closing) or None
+        """
+        return self._mark_renderers.get(mark_type)
+
+    # ==========================================================================
+    # Serialization (TipTap JSON -> Markdown)
+    # ==========================================================================
+
+    def serialize(self, doc: dict) -> str:
+        """Serialize TipTap JSON document to Markdown.
+
+        Args:
+            doc: TipTap JSON document (dict with 'type' and 'content')
+
+        Returns:
+            Markdown formatted string
+        """
+        if doc is None:
+            return ""
+
+        doc_type = doc.get("type")
+        if doc_type == constants.NodeTypes.DOC:
+            content = doc.get("content", [])
+            return "\n".join(self._serialize_nodes(content))
+        else:
+            return self._render_node(doc, None, 0)
+
+    def _serialize_nodes(self, nodes: list[dict]) -> list[str]:
+        """Serialize a list of nodes.
+
+        Args:
+            nodes: List of TipTap nodes
+
+        Returns:
+            List of rendered strings
+        """
+        output = []
+        for i, node in enumerate(nodes):
+            if node is None:
+                continue
+            output.append(self._render_node(node, None, i))
+        return output
+
+    def _render_node(
+        self,
+        node: dict,
+        parent_node: dict | None,
+        index: int,
+    ) -> str:
+        """Render a single node to Markdown.
+
+        Args:
+            node: Node to render
+            parent_node: Parent node
+            index: Index in parent
+
+        Returns:
+            Rendered Markdown string
+        """
+        node_type = node.get("type")
+        if node_type is None:
+            return ""
+
+        if node_type == constants.NodeTypes.TEXT:
+            return node.get("text", "")
+
+        renderer = self.get_node_renderer(node_type)
+        if renderer is None:
+            logger.warning("No renderer found for node type: %s", node_type)
+            return ""
+
+        parent_type = parent_node.get("type") if parent_node else None
+
+        content = node.get("content", [])
+        rendered_content = self._render_nodes(content, node)
+
+        return renderer(self, node, rendered_content, parent_type, index)
+
+    def _render_nodes(
+        self,
+        nodes: list[dict],
+        parent_node: dict,
+    ) -> str:
+        """Render nodes with mark state management.
+
+        Args:
+            nodes: Nodes to render
+            parent_node: Parent node
+
+        Returns:
+            Rendered string with marks properly applied
+        """
+        result: list[str] = []
+        active_marks: dict[str, dict] = {}
+
+        for i, node in enumerate(nodes):
+            if node is None:
+                continue
+
+            node_type = node.get("type")
+            if node_type is None:
+                continue
+
+            if node_type == constants.NodeTypes.TEXT:
+                text = node.get("text", "") or ""
+
+                current_marks = self._extract_marks(node)
+
+                marks_to_close = self._find_marks_to_close(active_marks, current_marks)
+                marks_to_open = self._find_marks_to_open(active_marks, current_marks)
+
+                for mark_type in marks_to_close:
+                    opening, closing = self.get_mark_renderer(mark_type) or ("", "")
+                    text += closing
+                    del active_marks[mark_type]
+
+                for mark_type in marks_to_open:
+                    opening, closing = self.get_mark_renderer(mark_type) or ("", "")
+                    text = opening + text
+                    active_marks[mark_type] = current_marks[mark_type]
+
+                next_node = nodes[i + 1] if i < len(nodes) - 1 else None
+                if next_node is not None:
+                    next_node_type = next_node.get("type")
+                    if next_node_type != constants.NodeTypes.TEXT:
+                        for mark_type in list(active_marks.keys()):
+                            opening, closing = self.get_mark_renderer(mark_type) or ("", "")
+                            text += closing
+                            del active_marks[mark_type]
+                    else:
+                        next_marks = self._extract_marks(next_node)
+                        if not self._marks_equal(active_marks, next_marks):
+                            for mark_type in list(active_marks.keys()):
+                                opening, closing = self.get_mark_renderer(mark_type) or ("", "")
+                                text += closing
+                                del active_marks[mark_type]
+
+                result.append(text)
+            else:
+                marks_to_reopen = dict(active_marks)
+                active_marks.clear()
+
+                rendered = self._render_node(node, parent_node, i)
+
+                if node_type != constants.NodeTypes.HARD_BREAK:
+                    for mark_type, mark in marks_to_reopen.items():
+                        opening, closing = self.get_mark_renderer(mark_type) or ("", "")
+                        rendered = opening + rendered
+                        active_marks[mark_type] = mark
+
+                result.append(rendered)
+
+        for mark_type in list(active_marks.keys()):
+            opening, closing = self.get_mark_renderer(mark_type) or ("", "")
+            if result:
+                result[-1] += closing
+
+        return "".join(result)
+
+    # ==========================================================================
+    # Parsing (Markdown -> TipTap JSON)
+    # ==========================================================================
+
+    def parse(self, markdown: str) -> dict:
+        """Parse Markdown text to TipTap JSON.
+
+        Args:
+            markdown: Markdown text string
+
+        Returns:
+            TipTap JSON document
+        """
+        if not markdown:
+            return parse_utils.create_doc([])
+
+        return MarkdownToTipTapParser().parse(markdown)
+
+    # ==========================================================================
+    # Mark State Management
+    # ==========================================================================
+
+    def _extract_marks(self, node: dict) -> dict[str, dict]:
+        """Extract marks from a node.
+
+        Args:
+            node: Node to extract marks from
+
+        Returns:
+            Dict mapping mark type to mark
+        """
+        marks: dict[str, dict] = {}
+        marks_array = node.get("marks")
+        if marks_array:
+            for mark in marks_array:
+                if mark and mark.get("type"):
+                    marks[mark["type"]] = mark
+        return marks
+
+    def _find_marks_to_close(
+        self,
+        active_marks: dict[str, dict],
+        current_marks: dict[str, dict],
+    ) -> list[str]:
+        """Find marks that need to be closed.
+
+        Args:
+            active_marks: Currently active marks
+            current_marks: Marks in current node
+
+        Returns:
+            List of mark types to close
+        """
+        return [mt for mt in active_marks if mt not in current_marks]
+
+    def _find_marks_to_open(
+        self,
+        active_marks: dict[str, dict],
+        current_marks: dict[str, dict],
+    ) -> list[str]:
+        """Find marks that need to be opened.
+
+        Args:
+            active_marks: Currently active marks
+            current_marks: Marks in current node
+
+        Returns:
+            List of mark types to open
+        """
+        return [mt for mt in current_marks if mt not in active_marks]
+
+    def _marks_equal(
+        self,
+        marks1: dict[str, dict],
+        marks2: dict[str, dict],
+    ) -> bool:
+        """Compare two mark sets for equality.
+
+        Only compares format marks (bold, italic, etc.), not link marks.
+
+        Args:
+            marks1: First mark set
+            marks2: Second mark set
+
+        Returns:
+            True if marks are equal
+        """
+        format_marks = [
+            constants.MarkTypes.BOLD,
+            constants.MarkTypes.ITALIC,
+            constants.MarkTypes.STRIKE,
+            constants.MarkTypes.CODE,
+            constants.MarkTypes.HIGHLIGHT,
+            constants.MarkTypes.UNDERLINE,
+        ]
+
+        format_marks1 = {mt: marks1[mt] for mt in format_marks if mt in marks1}
+        format_marks2 = {mt: marks2[mt] for mt in format_marks if mt in marks2}
+
+        if len(format_marks1) != len(format_marks2):
+            return False
+
+        for mark_type in format_marks1:
+            if mark_type not in format_marks2:
+                return False
+
+            attrs1 = format_marks1[mark_type].get("attrs")
+            attrs2 = format_marks2[mark_type].get("attrs")
+
+            if attrs1 is None and attrs2 is None:
+                continue
+            elif attrs1 is None or attrs2 is None or attrs1 != attrs2:
+                return False
+
+        return True
+
+    # ==========================================================================
+    # Default Renderers
+    # ==========================================================================
+
+    def _register_default_renderers(self) -> None:
+        """Register all default node and mark renderers."""
+        self.register_node_renderer(
+            constants.NodeTypes.PARAGRAPH,
+            lambda t, n, c, p, i: render_utils.render_paragraph(n, c, p),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.HEADING,
+            lambda t, n, c, p, i: render_utils.render_heading(
+                n, int(n.get("attrs", {}).get("level", 1)), c
+            ),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.CODE_BLOCK,
+            lambda t, n, c, p, i: render_utils.render_code_block(n, c),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.BLOCKQUOTE,
+            lambda t, n, c, p, i: render_utils.render_blockquote(c),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.BULLET_LIST,
+            lambda t, n, c, p, i: render_utils.render_bullet_list(c),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.ORDERED_LIST,
+            lambda t, n, c, p, i: render_utils.render_ordered_list(c),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.LIST_ITEM,
+            lambda t, n, c, p, i: render_utils.render_list_item(n, c, p, i),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.HORIZONTAL_RULE,
+            lambda t, n, c, p, i: render_utils.render_horizontal_rule(),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.HARD_BREAK,
+            lambda t, n, c, p, i: render_utils.render_hard_break(),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.IMAGE,
+            lambda t, n, c, p, i: render_utils.render_image(n),
+        )
+
+        if self.table_style == constants.TableStyle.MARKDOWN:
+            self.register_node_renderer(
+                constants.NodeTypes.TABLE,
+                lambda t, n, c, p, i: render_utils.render_table_to_md_format(n),
+            )
+        else:
+            self.register_node_renderer(
+                constants.NodeTypes.TABLE,
+                lambda t, n, c, p, i: render_utils.render_table_to_html_format(t, n),
+            )
+
+        self.register_node_renderer(
+            constants.NodeTypes.TABLE_ROW,
+            lambda t, n, c, p, i: render_utils.render_table_row(),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.TABLE_CELL,
+            lambda t, n, c, p, i: render_utils.render_table_cell(),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.TABLE_HEADER,
+            lambda t, n, c, p, i: render_utils.render_table_header(),
+        )
+
+        self.register_node_renderer(
+            constants.NodeTypes.FIXED_TITLE,
+            lambda t, n, c, p, i: render_utils.render_fixed_title(c),
+        )
+
+        self.register_node_renderer(
+            constants.NodeTypes.CALLOUT,
+            lambda t, n, c, p, i: render_utils.render_callout(n, c),
+        )
+
+        self.register_node_renderer(
+            constants.NodeTypes.MENTION,
+            lambda t, n, c, p, i: render_utils.render_mention(n),
+        )
+
+        self.register_node_renderer(
+            constants.NodeTypes.MERMAID,
+            lambda t, n, c, p, i: render_utils.render_mermaid(n),
+        )
+
+        self.register_node_renderer(
+            constants.NodeTypes.COLUMNS,
+            lambda t, n, c, p, i: self._render_columns(n),
+        )
+
+        self.register_node_renderer(
+            constants.NodeTypes.AI_SKILL,
+            lambda t, n, c, p, i: self._render_ai_skill(n),
+        )
+
+        self.register_node_renderer(
+            constants.NodeTypes.INSIGHT_BLOCK,
+            lambda t, n, c, p, i: self._render_insight_block(n),
+        )
+
+        self.register_node_renderer(
+            constants.NodeTypes.WIDGET_VIEW,
+            lambda t, n, c, p, i: render_utils.render_single_item_custom(
+                n, constants.NodeTypes.WIDGET_VIEW
+            ),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.WIDGET_NUM,
+            lambda t, n, c, p, i: render_utils.render_single_item_custom(
+                n, constants.NodeTypes.WIDGET_NUM, True
+            ),
+        )
+        self.register_node_renderer(
+            constants.NodeTypes.DATASET_DATA,
+            lambda t, n, c, p, i: render_utils.render_single_item_custom(
+                n, constants.NodeTypes.DATASET_DATA
+            ),
+        )
+
+        self.register_mark_renderer(
+            constants.MarkTypes.BOLD,
+            constants.Markdown.BOLD_MARKER,
+            constants.Markdown.BOLD_MARKER,
+        )
+        self.register_mark_renderer(
+            constants.MarkTypes.ITALIC,
+            constants.Markdown.ITALIC_MARKER,
+            constants.Markdown.ITALIC_MARKER,
+        )
+        self.register_mark_renderer(
+            constants.MarkTypes.STRIKE,
+            constants.Markdown.STRIKE_MARKER,
+            constants.Markdown.STRIKE_MARKER,
+        )
+        self.register_mark_renderer(
+            constants.MarkTypes.CODE,
+            constants.Markdown.CODE_MARKER,
+            constants.Markdown.CODE_MARKER,
+        )
+        self.register_mark_renderer(
+            constants.MarkTypes.LINK,
+            "",
+            "",
+        )
+        self.register_mark_renderer(
+            constants.MarkTypes.UNDERLINE,
+            constants.Markdown.UNDERLINE_HTML_OPEN,
+            constants.Markdown.UNDERLINE_HTML_CLOSE,
+        )
+        self.register_mark_renderer(
+            constants.MarkTypes.HIGHLIGHT,
+            constants.Markdown.HIGHLIGHT_MARKER,
+            constants.Markdown.HIGHLIGHT_MARKER,
+        )
+
+    def _render_columns(self, node: dict) -> str:
+        """Render columns container.
+
+        Args:
+            node: Columns node
+
+        Returns:
+            Rendered columns HTML
+        """
+        attrs = node.get("attrs") or {}
+        count = attrs.get(constants.AttrTypes.COLUMNS_COUNT, 2)
+        gap = attrs.get(constants.AttrTypes.COLUMNS_GAP)
+
+        content = node.get("content")
+        if not content:
+            return ""
+
+        column_nodes: list[dict] = []
+        for item in content:
+            if not item:
+                continue
+            if item.get("type") == constants.NodeTypes.COLUMN:
+                column_nodes.append(item)
+
+        columns_content: list[str] = []
+        for column in column_nodes:
+            column_attrs = column.get("attrs") or {}
+            width = column_attrs.get(constants.AttrTypes.COLUMN_WIDTH)
+
+            column_content = column.get("content")
+            if column_content:
+                column_html = self._render_nodes(column_content, column)
+            else:
+                column_html = ""
+
+            width_attr = f' width="{width}"' if width else ""
+            columns_content.append(f"<column{width_attr}>\n{column_html}\n</column>\n")
+
+        gap_attr = f' gap="{gap}"' if gap else ""
+        return (
+            f'<anti:html type="columns" count="{count}"{gap_attr}>\n'
+            + "".join(columns_content)
+            + "</anti:html>\n"
+        )
+
+    def _render_ai_skill(self, node: dict) -> str:
+        """Render AI skill block.
+
+        Args:
+            node: AI skill node
+
+        Returns:
+            Rendered AI skill HTML
+        """
+        html_tag = constants.NodeTypes.AI_SKILL
+        attrs = node.get("attrs") or {}
+
+        html_attrs = render_utils.attrs_to_html_attrs(attrs)
+
+        content = node.get("content")
+        if content:
+            html_buf = self._render_nodes(content, node)
+        else:
+            html_buf = ""
+
+        return f"<{html_tag}{html_attrs}>\n{html_buf}</{html_tag}>\n"
+
+    def _render_insight_block(self, node: dict) -> str:
+        """Render insight block.
+
+        Args:
+            node: Insight block node
+
+        Returns:
+            Rendered insight block
+        """
+        content = node.get("content")
+        if not content:
+            return ""
+
+        rendered_parts = []
+        for child in content:
+            if child:
+                rendered_parts.append(self.serialize(child))
+
+        return "\n".join(rendered_parts)

dataops_sdk/utils/__init__.py

@@ -0,0 +1,15 @@
+from .common import (
+    calculate_file_hash,
+    generate_slug_id,
+    get_log_dir,
+    get_log_path,
+    get_root_dir,
+    get_unix_timestamp,
+)
+from .utils import (
+    decrypt_body,
+    encrypt_body,
+    encrypt_hex,
+    filter_nodes_by_pattern,
+    get_work_dir,
+)