docspan 0.1.0__py3-none-any.whl

docspan/backends/google_docs/docs_request_builder.py

@@ -0,0 +1,232 @@
+"""Build Google Docs batchUpdate request lists from structural AST diffs."""
+from __future__ import annotations
+
+import difflib
+from typing import List, Tuple
+
+from docspan.backends.google_docs.docs_structure_parser import DocsParagraphNode
+
+
+def _utf16_len(text: str) -> int:
+    """Return the number of UTF-16 code units in text (surrogate pairs count as 2)."""
+    return len(text.encode("utf-16-le")) // 2
+
+
+class DocsRequestBuilder:
+    """Diff two paragraph ASTs and produce minimal Google Docs batchUpdate requests."""
+
+    def _text_key(self, node: DocsParagraphNode) -> Tuple:
+        """Key used by SequenceMatcher for comparing nodes."""
+        return (node.style, node.text, node.is_list_item)
+
+    def build(
+        self,
+        current: List[DocsParagraphNode],
+        target: List[DocsParagraphNode],
+        doc_end_index: int,
+    ) -> List[dict]:
+        """
+        Build a minimal list of batchUpdate request dicts.
+
+        Args:
+            current: Paragraph nodes parsed from the live Google Doc.
+            target:  Paragraph nodes parsed from the local markdown file.
+            doc_end_index: endIndex of the last body element (used to protect
+                           the terminal newline that Docs API requires).
+
+        Returns:
+            List of request dicts sorted by descending startIndex (write-backwards).
+        """
+        current_keys = [self._text_key(n) for n in current]
+        target_keys = [self._text_key(n) for n in target]
+
+        matcher = difflib.SequenceMatcher(None, current_keys, target_keys, autojunk=False)
+        opcodes = matcher.get_opcodes()
+
+        all_requests: List[dict] = []
+
+        for tag, i1, i2, j1, j2 in opcodes:
+            if tag == "equal":
+                # Nodes match — only emit style update if style differs
+                for ci, ti in zip(range(i1, i2), range(j1, j2)):
+                    all_requests.extend(
+                        self._make_style_update_requests(current[ci], target[ti])
+                    )
+
+            elif tag == "delete":
+                # Remove current nodes i1..i2 with no replacement
+                all_requests.extend(
+                    self._make_delete_requests(current[i1:i2], doc_end_index)
+                )
+
+            elif tag == "insert":
+                # Insert target nodes j1..j2 — determine insertion point
+                if i1 > 0:
+                    insert_at = current[i1 - 1].end_index - 1
+                else:
+                    insert_at = 1  # start of document body
+                all_requests.extend(
+                    self._make_insert_requests(target[j1:j2], insert_at)
+                )
+
+            elif tag == "replace":
+                # Delete current nodes, then insert target nodes at same position
+                delete_start = current[i1].start_index
+                all_requests.extend(
+                    self._make_delete_requests(current[i1:i2], doc_end_index)
+                )
+                all_requests.extend(
+                    self._make_insert_requests(target[j1:j2], delete_start)
+                )
+
+        # Sort descending by startIndex (write-backwards strategy)
+        all_requests.sort(
+            key=lambda r: self._extract_start_index(r),
+            reverse=True,
+        )
+        return all_requests
+
+    # ──────────────────────────────────────────────
+    # Request factories
+    # ──────────────────────────────────────────────
+
+    def _make_delete_requests(
+        self, nodes: List[DocsParagraphNode], doc_end_index: int
+    ) -> List[dict]:
+        requests = []
+        for node in nodes:
+            start = node.start_index
+            end = node.end_index
+            # Never delete the terminal newline
+            if end >= doc_end_index:
+                end = doc_end_index - 1
+            if start >= end:
+                continue
+            requests.append({
+                "deleteContentRange": {
+                    "range": {
+                        "startIndex": start,
+                        "endIndex": end,
+                    }
+                }
+            })
+        return requests
+
+    def _make_insert_requests(
+        self, nodes: List[DocsParagraphNode], insert_at_index: int
+    ) -> List[dict]:
+        """
+        Emit insertText + updateParagraphStyle (+ createParagraphBullets) per node.
+
+        All inserts go at the same index; because we sort descending later the
+        ordering inside a single insert group is preserved.
+        """
+        requests = []
+        # Insert in reverse order so that each insert lands at the right place
+        # when the final descending-sort is applied.
+        for node in reversed(nodes):
+            text = node.text + "\n"
+            requests.append({
+                "insertText": {
+                    "location": {"index": insert_at_index},
+                    "text": text,
+                }
+            })
+            text_len = _utf16_len(text)
+            end_index = insert_at_index + text_len
+            paragraph_range = {
+                "startIndex": insert_at_index,
+                "endIndex": end_index,
+            }
+            requests.append({
+                "updateParagraphStyle": {
+                    "range": paragraph_range,
+                    "paragraphStyle": {"namedStyleType": node.style},
+                    "fields": "namedStyleType",
+                }
+            })
+            if node.is_list_item:
+                requests.append({
+                    "createParagraphBullets": {
+                        "range": paragraph_range,
+                        "bulletPreset": "BULLET_DISC_CIRCLE_SQUARE",
+                    }
+                })
+        return requests
+
+    def _make_style_update_requests(
+        self, current_node: DocsParagraphNode, target_node: DocsParagraphNode
+    ) -> List[dict]:
+        """Emit updateParagraphStyle when style differs (text is equal)."""
+        if current_node.style == target_node.style:
+            return []
+        return [{
+            "updateParagraphStyle": {
+                "range": {
+                    "startIndex": current_node.start_index,
+                    "endIndex": current_node.end_index,
+                },
+                "paragraphStyle": {"namedStyleType": target_node.style},
+                "fields": "namedStyleType",
+            }
+        }]
+
+    def _make_text_style_requests(
+        self, text: str, style_attrs: dict, range_dict: dict
+    ) -> List[dict]:
+        """
+        Emit updateTextStyle with specific FieldMask (never '*').
+
+        Args:
+            text: The text content (for context; not used in request).
+            style_attrs: Dict with keys like 'bold', 'italic', 'link', 'monospace'.
+            range_dict: {'startIndex': int, 'endIndex': int}
+        """
+        fields = []
+        text_style: dict = {}
+
+        if "bold" in style_attrs:
+            fields.append("bold")
+            text_style["bold"] = style_attrs["bold"]
+        if "italic" in style_attrs:
+            fields.append("italic")
+            text_style["italic"] = style_attrs["italic"]
+        if "link" in style_attrs:
+            fields.append("link")
+            text_style["link"] = {"url": style_attrs["link"]}
+        if style_attrs.get("monospace"):
+            fields.append("weightedFontFamily")
+            text_style["weightedFontFamily"] = {"fontFamily": "Courier New", "weight": 400}
+
+        if not fields:
+            return []
+
+        return [{
+            "updateTextStyle": {
+                "range": range_dict,
+                "textStyle": text_style,
+                "fields": ",".join(fields),
+            }
+        }]
+
+    # ──────────────────────────────────────────────
+    # Helpers
+    # ──────────────────────────────────────────────
+
+    @staticmethod
+    def _extract_start_index(request: dict) -> int:
+        """Extract the primary startIndex from any request dict for sorting."""
+        for key in (
+            "deleteContentRange",
+            "insertText",
+            "updateParagraphStyle",
+            "createParagraphBullets",
+            "updateTextStyle",
+        ):
+            if key in request:
+                inner = request[key]
+                if "range" in inner:
+                    return inner["range"].get("startIndex", 0)
+                if "location" in inner:
+                    return inner["location"].get("index", 0)
+        return 0

docspan/backends/google_docs/docs_structure_parser.py

@@ -0,0 +1,120 @@
+"""Parse a Google Docs JSON document into a list of DocsParagraphNode objects."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class TextSpan:
+    text: str
+    bold: bool = False
+    italic: bool = False
+    link: Optional[str] = None
+    monospace: bool = False
+
+
+@dataclass
+class DocsParagraphNode:
+    """Represents a single paragraph in a Google Docs document."""
+    style: str  # e.g. "NORMAL_TEXT", "HEADING_1", "HEADING_2", ...
+    text: str   # Concatenated plain text (trailing \n stripped)
+    is_list_item: bool = False
+    nesting_level: int = 0
+    start_index: int = 0
+    end_index: int = 0
+    spans: List[TextSpan] = field(default_factory=list)
+
+
+class DocsStructureParser:
+    """Parse a Google Docs document dict into a list of DocsParagraphNode."""
+
+    def parse(self, doc: dict) -> List[DocsParagraphNode]:
+        """
+        Parse a Google Docs document dict.
+
+        Handles both tabs-based format (doc['tabs'][0]['documentTab']['body']['content'])
+        and legacy single-tab format (doc['body']['content']).
+
+        Args:
+            doc: Full Google Docs document resource dict (from documents.get())
+
+        Returns:
+            List of DocsParagraphNode in document order.
+
+        Raises:
+            KeyError: If the document has neither 'tabs' nor 'body' key.
+        """
+        # Determine body content — handle tabs-based and legacy structure
+        if "tabs" in doc and doc["tabs"]:
+            body = doc["tabs"][0].get("documentTab", doc).get("body", {})
+        elif "body" in doc:
+            body = doc["body"]
+        else:
+            raise KeyError("Document has neither 'tabs' nor 'body' key")
+
+        content = body.get("content", [])
+        nodes: List[DocsParagraphNode] = []
+
+        for element in content:
+            if "paragraph" in element:
+                node = self._parse_paragraph(element)
+                if node is not None:
+                    nodes.append(node)
+            # table, sectionBreak, tableOfContents are silently skipped
+
+        return nodes
+
+    def _parse_paragraph(self, element: dict) -> Optional[DocsParagraphNode]:
+        """Parse a structural element that contains a paragraph."""
+        paragraph = element["paragraph"]
+        paragraph_style = paragraph.get("paragraphStyle", {})
+        style = paragraph_style.get("namedStyleType", "NORMAL_TEXT")
+
+        start_index = element.get("startIndex", 0)
+        end_index = element.get("endIndex", 0)
+
+        # Extract text from all TextRuns, collecting spans
+        spans: List[TextSpan] = []
+        text_parts: List[str] = []
+
+        for pe in paragraph.get("elements", []):
+            text_run = pe.get("textRun")
+            if text_run is None:
+                continue
+            run_content = text_run.get("content", "")
+            text_style = text_run.get("textStyle", {})
+            bold = text_style.get("bold", False)
+            italic = text_style.get("italic", False)
+            link = text_style.get("link", {}).get("url") if text_style.get("link") else None
+            # Monospace: check weightedFontFamily.fontFamily for "Courier New" or similar
+            font_family = text_style.get("weightedFontFamily", {}).get("fontFamily", "")
+            monospace = "Courier" in font_family or "mono" in font_family.lower()
+
+            text_parts.append(run_content)
+            spans.append(TextSpan(
+                text=run_content,
+                bold=bool(bold),
+                italic=bool(italic),
+                link=link,
+                monospace=monospace,
+            ))
+
+        raw_text = "".join(text_parts)
+        # Strip trailing newline (each paragraph ends with \n in the Docs model)
+        text = raw_text.rstrip("\n")
+
+        # Check for bullet / list item
+        bullet = paragraph.get("bullet")
+        is_list_item = bullet is not None
+        nesting_level = bullet.get("nestingLevel", 0) if bullet else 0
+
+        return DocsParagraphNode(
+            style=style,
+            text=text,
+            is_list_item=is_list_item,
+            nesting_level=nesting_level,
+            start_index=start_index,
+            end_index=end_index,
+            spans=spans,
+        )

docspan/backends/google_docs/markdown_to_paragraph_parser.py

@@ -0,0 +1,145 @@
+"""Parse Markdown content into DocsParagraphNode list for Google Docs push."""
+from __future__ import annotations
+
+from typing import List
+
+from docspan.backends.google_docs.docs_structure_parser import DocsParagraphNode, TextSpan
+
+
+def _extract_text_from_token(token: dict) -> str:
+    """Recursively extract plain text from a mistune AST token."""
+    if token.get("type") == "raw":
+        return token.get("raw", "")
+    if token.get("type") == "text":
+        return token.get("raw", "")
+    if token.get("type") == "codespan":
+        return token.get("raw", "")
+    # For inline tokens: code_span, emphasis, strong, link, etc.
+    children = token.get("children") or token.get("children", [])
+    if children:
+        return "".join(_extract_text_from_token(c) for c in children)
+    return token.get("raw", "")
+
+
+def _walk_list_items(token: dict, nesting_level: int = 0) -> List[DocsParagraphNode]:
+    """Walk a list token and yield DocsParagraphNode for each list item."""
+    nodes = []
+    for item in token.get("children", []):
+        if item.get("type") != "list_item":
+            continue
+        # Gather text from children of list_item (may be paragraph or inline tokens)
+        text_parts = []
+        for child in item.get("children", []):
+            if child.get("type") == "paragraph":
+                for inline in child.get("children", []):
+                    text_parts.append(_extract_text_from_token(inline))
+            elif child.get("type") == "list":
+                # Nested list — recurse
+                nodes.append(DocsParagraphNode(
+                    style="NORMAL_TEXT",
+                    text="".join(text_parts).strip(),
+                    is_list_item=True,
+                    nesting_level=nesting_level,
+                    start_index=0,
+                    end_index=0,
+                ))
+                text_parts = []
+                nodes.extend(_walk_list_items(child, nesting_level + 1))
+                continue
+            else:
+                text_parts.append(_extract_text_from_token(child))
+        text = "".join(text_parts).strip()
+        if text:
+            nodes.append(DocsParagraphNode(
+                style="NORMAL_TEXT",
+                text=text,
+                is_list_item=True,
+                nesting_level=nesting_level,
+                start_index=0,
+                end_index=0,
+            ))
+    return nodes
+
+
+class MarkdownToParagraphParser:
+    """
+    Parse Markdown content into a list of DocsParagraphNode.
+
+    Uses mistune>=3.0 (AST renderer) for accurate block-level parsing.
+    All target nodes have start_index=0, end_index=0 (not meaningful for push targets).
+
+    Acceptance criteria:
+    - A blank line between paragraphs produces two separate nodes (not one)
+    - '## Heading' produces style="HEADING_2"
+    - '- item' produces is_list_item=True
+    - A fenced code block produces a single node with monospace=True span
+    """
+
+    def parse(self, content: str) -> List[DocsParagraphNode]:
+        """
+        Parse markdown content into DocsParagraphNode list.
+
+        Args:
+            content: Raw markdown string.
+
+        Returns:
+            List of DocsParagraphNode in document order.
+        """
+        import mistune
+
+        # mistune.create_markdown(renderer=None) returns AST tokens
+        md = mistune.create_markdown(renderer=None)
+        tokens = md(content) or []
+
+        nodes: List[DocsParagraphNode] = []
+        for token in tokens:
+            token_type = token.get("type")
+
+            if token_type == "heading":
+                level = token.get("attrs", {}).get("level", token.get("level", 1))
+                style = f"HEADING_{level}"
+                text_parts = []
+                for child in token.get("children", []):
+                    text_parts.append(_extract_text_from_token(child))
+                text = "".join(text_parts).strip()
+                nodes.append(DocsParagraphNode(
+                    style=style,
+                    text=text,
+                    start_index=0,
+                    end_index=0,
+                ))
+
+            elif token_type == "paragraph":
+                text_parts = []
+                for child in token.get("children", []):
+                    text_parts.append(_extract_text_from_token(child))
+                text = "".join(text_parts).strip()
+                nodes.append(DocsParagraphNode(
+                    style="NORMAL_TEXT",
+                    text=text,
+                    start_index=0,
+                    end_index=0,
+                ))
+
+            elif token_type == "list":
+                nodes.extend(_walk_list_items(token, nesting_level=0))
+
+            elif token_type in ("block_code", "code"):
+                # Fenced code block — single node with monospace span
+                raw = token.get("raw", "").strip()
+                span = TextSpan(text=raw, monospace=True)
+                nodes.append(DocsParagraphNode(
+                    style="NORMAL_TEXT",
+                    text=raw,
+                    start_index=0,
+                    end_index=0,
+                    spans=[span],
+                ))
+
+            elif token_type == "blank_line":
+                # blank_line between paragraphs — skip (mistune handles separation)
+                pass
+
+            # block_quote, thematic_break, html, etc. are silently skipped
+
+        return nodes