notionary 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

notionary/core/converters/elements/table_element.py

@@ -0,0 +1,306 @@
+# File: elements/tables.py
+
+from typing import Dict, Any, Optional, List, Tuple
+from typing_extensions import override
+import re
+from notionary.core.converters.elements.notion_block_element import NotionBlockElement
+from notionary.core.converters.elements.text_inline_formatter import TextInlineFormatter
+
+
+class TableElement(NotionBlockElement):
+    """
+    Handles conversion between Markdown tables and Notion table blocks.
+
+    Markdown table syntax:
+    | Header 1 | Header 2 | Header 3 |
+    | -------- | -------- | -------- |
+    | Cell 1   | Cell 2   | Cell 3   |
+    | Cell 4   | Cell 5   | Cell 6   |
+
+    The second line with dashes and optional colons defines column alignment.
+    """
+
+    # Patterns for detecting Markdown tables
+    ROW_PATTERN = re.compile(r"^\s*\|(.+)\|\s*$")
+    SEPARATOR_PATTERN = re.compile(r"^\s*\|([\s\-:|]+)\|\s*$")
+
+    @override
+    @staticmethod
+    def match_markdown(text: str) -> bool:
+        """Check if text contains a markdown table."""
+        lines = text.split("\n")
+
+        if len(lines) < 3:
+            return False
+
+        for i, line in enumerate(lines[:-2]):
+            if (
+                TableElement.ROW_PATTERN.match(line)
+                and TableElement.SEPARATOR_PATTERN.match(lines[i + 1])
+                and TableElement.ROW_PATTERN.match(lines[i + 2])
+            ):
+                return True
+
+        return False
+
+    @override
+    @staticmethod
+    def match_notion(block: Dict[str, Any]) -> bool:
+        """Check if block is a Notion table."""
+        return block.get("type") == "table"
+
+    @override
+    @staticmethod
+    def markdown_to_notion(text: str) -> Optional[Dict[str, Any]]:
+        """Convert markdown table to Notion table block."""
+        if not TableElement.match_markdown(text):
+            return None
+
+        lines = text.split("\n")
+
+        table_start = TableElement._find_table_start(lines)
+        if table_start is None:
+            return None
+
+        table_end = TableElement._find_table_end(lines, table_start)
+        table_lines = lines[table_start:table_end]
+
+        rows = TableElement._extract_table_rows(table_lines)
+        if not rows:
+            return None
+
+        column_count = len(rows[0])
+        TableElement._normalize_row_lengths(rows, column_count)
+
+        return {
+            "type": "table",
+            "table": {
+                "table_width": column_count,
+                "has_column_header": True,
+                "has_row_header": False,
+                "children": TableElement._create_table_rows(rows),
+            },
+        }
+
+    @override
+    @staticmethod
+    def notion_to_markdown(block: Dict[str, Any]) -> Optional[str]:
+        """Convert Notion table block to markdown table."""
+        if block.get("type") != "table":
+            return None
+
+        table_data = block.get("table", {})
+        children = block.get("children", [])
+
+        if not children:
+            table_width = table_data.get("table_width", 3)
+
+            header = (
+                "| " + " | ".join([f"Column {i+1}" for i in range(table_width)]) + " |"
+            )
+            separator = (
+                "| " + " | ".join(["--------" for _ in range(table_width)]) + " |"
+            )
+            data_row = (
+                "| " + " | ".join(["        " for _ in range(table_width)]) + " |"
+            )
+
+            table_rows = [header, separator, data_row]
+            return "\n".join(table_rows)
+
+        table_rows = []
+        header_processed = False
+
+        for child in children:
+            if child.get("type") != "table_row":
+                continue
+
+            row_data = child.get("table_row", {})
+            cells = row_data.get("cells", [])
+
+            row_cells = []
+            for cell in cells:
+                cell_text = TextInlineFormatter.extract_text_with_formatting(cell)
+                row_cells.append(cell_text or "")
+
+            row = "| " + " | ".join(row_cells) + " |"
+            table_rows.append(row)
+
+            if not header_processed and table_data.get("has_column_header", True):
+                header_processed = True
+                separator = (
+                    "| " + " | ".join(["--------" for _ in range(len(cells))]) + " |"
+                )
+                table_rows.append(separator)
+
+        if not table_rows:
+            return None
+
+        if len(table_rows) == 1 and table_data.get("has_column_header", True):
+            cells_count = len(children[0].get("table_row", {}).get("cells", []))
+            separator = (
+                "| " + " | ".join(["--------" for _ in range(cells_count)]) + " |"
+            )
+            table_rows.insert(1, separator)
+
+        return "\n".join(table_rows)
+
+    @override
+    @staticmethod
+    def is_multiline() -> bool:
+        """Indicates if this element handles content that spans multiple lines."""
+        return True
+
+    @staticmethod
+    def _find_table_start(lines: List[str]) -> Optional[int]:
+        """Find the start index of a table in the lines."""
+        for i in range(len(lines) - 2):
+            if (
+                TableElement.ROW_PATTERN.match(lines[i])
+                and TableElement.SEPARATOR_PATTERN.match(lines[i + 1])
+                and TableElement.ROW_PATTERN.match(lines[i + 2])
+            ):
+                return i
+        return None
+
+    @staticmethod
+    def _find_table_end(lines: List[str], start_idx: int) -> int:
+        """Find the end index of a table, starting from start_idx."""
+        end_idx = start_idx + 3  # Minimum: Header, Separator, one data row
+        while end_idx < len(lines) and TableElement.ROW_PATTERN.match(lines[end_idx]):
+            end_idx += 1
+        return end_idx
+
+    @staticmethod
+    def _extract_table_rows(table_lines: List[str]) -> List[List[str]]:
+        """Extract row contents from table lines, excluding separator line."""
+        rows = []
+        for i, line in enumerate(table_lines):
+            if i != 1 and TableElement.ROW_PATTERN.match(line):  # Skip separator line
+                cells = TableElement._parse_table_row(line)
+                if cells:
+                    rows.append(cells)
+        return rows
+
+    @staticmethod
+    def _normalize_row_lengths(rows: List[List[str]], column_count: int) -> None:
+        """Normalize row lengths to the specified column count."""
+        for row in rows:
+            if len(row) < column_count:
+                row.extend([""] * (column_count - len(row)))
+            elif len(row) > column_count:
+                del row[column_count:]
+
+    @staticmethod
+    def _parse_table_row(row_text: str) -> List[str]:
+        """Convert table row text to cell contents."""
+        row_content = row_text.strip()
+
+        if row_content.startswith("|"):
+            row_content = row_content[1:]
+        if row_content.endswith("|"):
+            row_content = row_content[:-1]
+
+        return [cell.strip() for cell in row_content.split("|")]
+
+    @staticmethod
+    def _create_table_rows(rows: List[List[str]]) -> List[Dict[str, Any]]:
+        """Create Notion table rows from cell contents."""
+        table_rows = []
+
+        for row in rows:
+            cells_data = []
+
+            for cell_content in row:
+                rich_text = TextInlineFormatter.parse_inline_formatting(cell_content)
+
+                if not rich_text:
+                    rich_text = [
+                        {
+                            "type": "text",
+                            "text": {"content": ""},
+                            "annotations": {
+                                "bold": False,
+                                "italic": False,
+                                "strikethrough": False,
+                                "underline": False,
+                                "code": False,
+                                "color": "default",
+                            },
+                            "plain_text": "",
+                            "href": None,
+                        }
+                    ]
+
+                cells_data.append(rich_text)
+
+            table_rows.append({"type": "table_row", "table_row": {"cells": cells_data}})
+
+        return table_rows
+
+    @staticmethod
+    def find_matches(text: str) -> List[Tuple[int, int, Dict[str, Any]]]:
+        """
+        Find all tables in the text and return their positions.
+
+        Args:
+            text: The text to search in
+
+        Returns:
+            List of tuples with (start_pos, end_pos, block)
+        """
+        matches = []
+        lines = text.split("\n")
+
+        i = 0
+        while i < len(lines) - 2:
+            if (
+                TableElement.ROW_PATTERN.match(lines[i])
+                and TableElement.SEPARATOR_PATTERN.match(lines[i + 1])
+                and TableElement.ROW_PATTERN.match(lines[i + 2])
+            ):
+
+                start_line = i
+                end_line = TableElement._find_table_end(lines, start_line)
+
+                start_pos = TableElement._calculate_position(lines, 0, start_line)
+                end_pos = start_pos + TableElement._calculate_position(
+                    lines, start_line, end_line
+                )
+
+                table_text = "\n".join(lines[start_line:end_line])
+                table_block = TableElement.markdown_to_notion(table_text)
+
+                if table_block:
+                    matches.append((start_pos, end_pos, table_block))
+
+                i = end_line
+            else:
+                i += 1
+
+        return matches
+
+    @staticmethod
+    def _calculate_position(lines: List[str], start: int, end: int) -> int:
+        """Calculate the text position in characters from line start to end."""
+        position = 0
+        for i in range(start, end):
+            position += len(lines[i]) + 1  # +1 for newline
+        return position
+
+    @classmethod
+    def get_llm_prompt_content(cls) -> dict:
+        """Returns information for LLM prompts about this element."""
+        return {
+            "description": "Creates formatted tables with rows and columns for structured data.",
+            "when_to_use": "Use tables to organize and present structured data in a grid format, making information easier to compare and analyze. Tables are ideal for data sets, comparison charts, pricing information, or any content that benefits from columnar organization.",
+            "notes": [
+                "The header row is required and will be displayed differently in Notion",
+                "The separator row with dashes is required to define the table structure",
+                "Table cells support inline formatting such as **bold** and *italic*",
+            ],
+            "examples": [
+                "| Product | Price | Stock |\n| ------- | ----- | ----- |\n| Widget A | $10.99 | 42 |\n| Widget B | $14.99 | 27 |",
+                "| Name | Role | Department |\n| ---- | ---- | ---------- |\n| John Smith | Manager | Marketing |\n| Jane Doe | Director | Sales |",
+            ],
+        }

notionary/core/converters/elements/text_inline_formatter.py

@@ -0,0 +1,294 @@
+from typing import Dict, Any, List, Tuple
+import re
+
+
+class TextInlineFormatter:
+    """
+    Handles conversion between Markdown inline formatting and Notion rich text elements.
+
+    Supports various formatting options:
+    - Bold: **text**
+    - Italic: *text* or _text_
+    - Underline: __text__
+    - Strikethrough: ~~text~~
+    - Code: `text`
+    - Links: [text](url)
+    - Highlights: ==text== (default yellow) or ==color:text== (custom color)
+    """
+
+    # Format patterns for matching Markdown formatting
+    FORMAT_PATTERNS = [
+        (r"\*\*(.+?)\*\*", {"bold": True}),
+        (r"\*(.+?)\*", {"italic": True}),
+        (r"_(.+?)_", {"italic": True}),
+        (r"__(.+?)__", {"underline": True}),
+        (r"~~(.+?)~~", {"strikethrough": True}),
+        (r"`(.+?)`", {"code": True}),
+        (r"\[(.+?)\]\((.+?)\)", {"link": True}),
+        (r"==([a-z_]+):(.+?)==", {"highlight": True}),
+        (r"==(.+?)==", {"highlight_default": True}),
+    ]
+
+    # Valid colors for highlighting
+    VALID_COLORS = [
+        "default",
+        "gray",
+        "brown",
+        "orange",
+        "yellow",
+        "green",
+        "blue",
+        "purple",
+        "pink",
+        "red",
+        "gray_background",
+        "brown_background",
+        "orange_background",
+        "yellow_background",
+        "green_background",
+        "blue_background",
+        "purple_background",
+        "pink_background",
+        "red_background",
+    ]
+
+    @classmethod
+    def parse_inline_formatting(cls, text: str) -> List[Dict[str, Any]]:
+        """
+        Parse inline text formatting into Notion rich_text format.
+
+        Args:
+            text: Markdown text with inline formatting
+
+        Returns:
+            List of Notion rich_text objects
+        """
+        if not text:
+            return []
+
+        return cls._split_text_into_segments(text, cls.FORMAT_PATTERNS)
+
+    @classmethod
+    def _split_text_into_segments(
+        cls, text: str, format_patterns: List[Tuple]
+    ) -> List[Dict[str, Any]]:
+        """
+        Split text into segments by formatting markers and convert to Notion rich_text format.
+
+        Args:
+            text: Text to split
+            format_patterns: List of (regex pattern, formatting dict) tuples
+
+        Returns:
+            List of Notion rich_text objects
+        """
+        segments = []
+        remaining_text = text
+
+        while remaining_text:
+            earliest_match = None
+            earliest_format = None
+            earliest_pos = len(remaining_text)
+
+            # Find the earliest formatting marker
+            for pattern, formatting in format_patterns:
+                match = re.search(pattern, remaining_text)
+                if match and match.start() < earliest_pos:
+                    earliest_match = match
+                    earliest_format = formatting
+                    earliest_pos = match.start()
+
+            if earliest_match is None:
+                if remaining_text:
+                    segments.append(cls._create_text_element(remaining_text, {}))
+                break
+
+            if earliest_pos > 0:
+                segments.append(
+                    cls._create_text_element(remaining_text[:earliest_pos], {})
+                )
+
+            if "highlight" in earliest_format:
+                color = earliest_match.group(1)
+                content = earliest_match.group(2)
+
+                if color not in cls.VALID_COLORS:
+                    if not color.endswith("_background"):
+                        color = f"{color}_background"
+
+                    if color not in cls.VALID_COLORS:
+                        color = "yellow_background"
+
+                segments.append(cls._create_text_element(content, {"color": color}))
+
+            elif "highlight_default" in earliest_format:
+                content = earliest_match.group(1)
+                segments.append(
+                    cls._create_text_element(content, {"color": "yellow_background"})
+                )
+
+            elif "link" in earliest_format:
+                content = earliest_match.group(1)
+                url = earliest_match.group(2)
+                segments.append(cls._create_link_element(content, url))
+
+            else:
+                content = earliest_match.group(1)
+                segments.append(cls._create_text_element(content, earliest_format))
+
+            # Move past the processed segment
+            remaining_text = remaining_text[
+                earliest_pos + len(earliest_match.group(0)) :
+            ]
+
+        return segments
+
+    @classmethod
+    def _create_text_element(
+        cls, text: str, formatting: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Create a Notion text element with formatting.
+
+        Args:
+            text: The text content
+            formatting: Dictionary of formatting options
+
+        Returns:
+            Notion rich_text element
+        """
+        annotations = cls._default_annotations()
+
+        # Apply formatting
+        for key, value in formatting.items():
+            if key == "color":
+                annotations["color"] = value
+            elif key in annotations:
+                annotations[key] = value
+
+        return {
+            "type": "text",
+            "text": {"content": text},
+            "annotations": annotations,
+            "plain_text": text,
+        }
+
+    @classmethod
+    def _create_link_element(cls, text: str, url: str) -> Dict[str, Any]:
+        """
+        Create a Notion link element.
+
+        Args:
+            text: The link text
+            url: The URL
+
+        Returns:
+            Notion rich_text element with link
+        """
+        return {
+            "type": "text",
+            "text": {"content": text, "link": {"url": url}},
+            "annotations": cls._default_annotations(),
+            "plain_text": text,
+        }
+
+    @classmethod
+    def extract_text_with_formatting(cls, rich_text: List[Dict[str, Any]]) -> str:
+        """
+        Convert Notion rich_text elements back to Markdown formatted text.
+
+        Args:
+            rich_text: List of Notion rich_text elements
+
+        Returns:
+            Markdown formatted text
+        """
+        formatted_parts = []
+
+        for text_obj in rich_text:
+            # Fallback: If plain_text is missing, use text['content']
+            content = text_obj.get("plain_text")
+            if content is None:
+                content = text_obj.get("text", {}).get("content", "")
+
+            annotations = text_obj.get("annotations", {})
+
+            if annotations.get("code", False):
+                content = f"`{content}`"
+            if annotations.get("strikethrough", False):
+                content = f"~~{content}~~"
+            if annotations.get("underline", False):
+                content = f"__{content}__"
+            if annotations.get("italic", False):
+                content = f"*{content}*"
+            if annotations.get("bold", False):
+                content = f"**{content}**"
+
+            color = annotations.get("color", "default")
+            if color != "default":
+                content = f"=={color.replace('_background', '')}:{content}=="
+
+            text_data = text_obj.get("text", {})
+            link_data = text_data.get("link")
+            if link_data:
+                url = link_data.get("url", "")
+                content = f"[{content}]({url})"
+
+            formatted_parts.append(content)
+
+        return "".join(formatted_parts)
+
+    @classmethod
+    def _default_annotations(cls) -> Dict[str, bool]:
+        """
+        Create default annotations object.
+
+        Returns:
+            Default Notion text annotations
+        """
+        return {
+            "bold": False,
+            "italic": False,
+            "strikethrough": False,
+            "underline": False,
+            "code": False,
+            "color": "default",
+        }
+
+    @classmethod
+    def get_llm_prompt_content(cls) -> Dict[str, Any]:
+        """
+        Returns information about inline text formatting capabilities for LLM prompts.
+
+        This method provides documentation about supported inline formatting options
+        that can be used across all block elements.
+
+        Returns:
+            A dictionary with descriptions, syntax examples, and usage guidelines
+        """
+        return {
+            "description": "Standard Markdown formatting is supported in all text blocks. Additionally, a custom highlight syntax is available for emphasizing important information. To create vertical spacing between elements, use the special spacer tag.",
+            "syntax": [
+                "**text** - Bold text",
+                "*text* or _text_ - Italic text",
+                "__text__ - Underlined text",
+                "~~text~~ - Strikethrough text",
+                "`text` - Inline code",
+                "[text](url) - Link",
+                "==text== - Default highlight (yellow background)",
+                "==color:text== - Colored highlight (e.g., ==red:warning==)",
+                "<!-- spacer --> - Creates vertical spacing between elements",
+            ],
+            "examples": [
+                "This is a **bold** statement with some *italic* words.",
+                "This feature is ~~deprecated~~ as of version 2.0.",
+                "Edit the `config.json` file to configure settings.",
+                "Check our [documentation](https://docs.example.com) for more details.",
+                "==This is an important note== that you should remember.",
+                "==red:Warning:== This action cannot be undone.",
+                "==blue:Note:== Common colors include red, blue, green, yellow, purple.",
+                "First paragraph content.\n\n<!-- spacer -->\n\nSecond paragraph with additional spacing above.",
+            ],
+            "highlight_usage": "The highlight syntax (==text== and ==color:text==) should be used to emphasize important information, warnings, notes, or other content that needs to stand out. This is particularly useful for making content more scannable at a glance.",
+            "spacer_usage": "Use the <!-- spacer --> tag on its own line to create additional vertical spacing between elements. This is useful for improving readability by visually separating sections of content. Multiple spacer tags can be used for greater spacing.",
+        }