PyPI - arcade-google-docs - Versions diffs - 4.3.1__py3-none-any.whl → 5.0.0__py3-none-any.whl - Mend

arcade-google-docs 4.3.1py3-none-any.whl → 5.0.0py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

arcade_google_docs/__init__.py +6 -0
arcade_google_docs/doc_to_html.py +195 -4
arcade_google_docs/doc_to_markdown.py +181 -3
arcade_google_docs/docmd.py +115 -36
arcade_google_docs/models/responses.py +143 -0
arcade_google_docs/tools/__init__.py +7 -1
arcade_google_docs/tools/edit_agent/utils.py +3 -1
arcade_google_docs/tools/get.py +64 -7
arcade_google_docs/tools/search.py +33 -33
arcade_google_docs/utils.py +262 -1
{arcade_google_docs-4.3.1.dist-info → arcade_google_docs-5.0.0.dist-info}/METADATA +4 -4
{arcade_google_docs-4.3.1.dist-info → arcade_google_docs-5.0.0.dist-info}/RECORD +13 -12
{arcade_google_docs-4.3.1.dist-info → arcade_google_docs-5.0.0.dist-info}/WHEEL +0 -0

arcade_google_docs/__init__.py CHANGED Viewed

@@ -3,11 +3,14 @@ from arcade_google_docs.tools import (
     create_blank_document,
     create_document_from_text,
     generate_google_file_picker_url,
+    get_document_as_docmd,
     get_document_by_id,
+    get_document_metadata,
     insert_text_at_end_of_document,
     list_document_comments,
     search_and_retrieve_documents,
     search_documents,
+    who_am_i,
 )
 __all__ = [
@@ -15,9 +18,12 @@ __all__ = [
     "create_document_from_text",
     "comment_on_document",
     "list_document_comments",
+    "get_document_as_docmd",
     "get_document_by_id",
+    "get_document_metadata",
     "insert_text_at_end_of_document",
     "search_and_retrieve_documents",
     "search_documents",
     "generate_google_file_picker_url",
+    "who_am_i",
 ]

arcade_google_docs/doc_to_html.py CHANGED Viewed

@@ -1,17 +1,47 @@
-def convert_document_to_html(document: dict) -> str:
+"""
+Google Docs to HTML converter.
+"""
+import html as html_module
+def convert_document_to_html(document: dict, include_all_tabs: bool = True) -> str:
+    """Convert a Google Docs document to HTML format.
+    Args:
+        document: Document dict from Google Docs API
+        include_all_tabs: Whether to include all tabs (True) or just main body (False)
+    Returns:
+        HTML string representation of the document
+    """
+    escaped_title = html_module.escape(document.get("title", ""))
     html = (
         "<html><head>"
-        f"<title>{document['title']}</title>"
+        f"<title>{escaped_title}</title>"
         f'<meta name="documentId" content="{document["documentId"]}">'
         "</head><body>"
     )
-    for element in document["body"]["content"]:
-        html += convert_structural_element(element)
+    if include_all_tabs and "tabs" in document and document["tabs"]:
+        html += _convert_tabs_to_html(document["tabs"])
+    else:
+        html += _convert_body_to_html(document.get("body", {}))
     html += "</body></html>"
     return html
 def convert_structural_element(element: dict, wrap_paragraphs: bool = True) -> str:
+    """Convert a structural element to HTML.
+    Args:
+        element: Structural element dict
+        wrap_paragraphs: Whether to wrap paragraphs in <p> tags
+    Returns:
+        HTML string
+    """
     if "sectionBreak" in element or "tableOfContents" in element:
         return ""
@@ -51,12 +81,30 @@ def convert_structural_element(element: dict, wrap_paragraphs: bool = True) -> s
 def extract_paragraph_content(text_run: dict) -> str:
+    """Extract content from a paragraph text run.
+    Args:
+        text_run: Text run dict
+    Returns:
+        Styled HTML string
+    """
     content = text_run["content"]
     style = text_run["textStyle"]
     return apply_text_style(content, style)
 def apply_text_style(content: str, style: dict) -> str:
+    """Apply text styling to content.
+    Args:
+        content: Text content
+        style: Style dict
+    Returns:
+        Styled content with HTML tags
+    """
+    content = content.replace("\u000b", "\n")  # Replace vertical tab with newline
     content = content.rstrip("\n")
     content = content.replace("\n", "<br>")
     italic = style.get("italic", False)
@@ -69,6 +117,15 @@ def apply_text_style(content: str, style: dict) -> str:
 def get_paragraph_style_tags(style: dict, wrap_paragraphs: bool = True) -> tuple[str, str]:
+    """Get HTML opening and closing tags for paragraph style.
+    Args:
+        style: Paragraph style dict
+        wrap_paragraphs: Whether to wrap in paragraph tags
+    Returns:
+        Tuple of (opening_tag, closing_tag)
+    """
     named_style = style["namedStyleType"]
     if named_style == "NORMAL_TEXT":
         return ("<p>", "</p>") if wrap_paragraphs else ("", "")
@@ -87,6 +144,14 @@ def get_paragraph_style_tags(style: dict, wrap_paragraphs: bool = True) -> tuple
 def table_list_to_html(table: list[list[str]]) -> str:
+    """Convert a table list to HTML.
+    Args:
+        table: List of rows, where each row is a list of cell contents
+    Returns:
+        HTML table string
+    """
     html = "<table>"
     for row in table:
         html += "<tr>"
@@ -97,3 +162,129 @@ def table_list_to_html(table: list[list[str]]) -> str:
         html += "</tr>"
     html += "</table>"
     return html
+def _flatten_tabs_for_html(
+    tabs: list[dict], max_depth: int = 4, current_depth: int = 0
+) -> list[dict]:
+    """Flatten tab hierarchy using depth-first traversal for HTML conversion.
+    Args:
+        tabs: List of tab dicts with potential childTabs
+        max_depth: Maximum recursion depth (Google Docs enforces 3 levels, using 4 for safety)
+        current_depth: Current recursion depth
+    Returns:
+        Flattened list in depth-first order
+    """
+    if current_depth >= max_depth:
+        return []
+    result: list[dict] = []
+    for tab in tabs:
+        result.append(tab)
+        if tab.get("childTabs"):
+            result.extend(_flatten_tabs_for_html(tab["childTabs"], max_depth, current_depth + 1))
+    return result
+def _convert_tabs_to_html(tabs: list[dict]) -> str:
+    """Convert all tabs to HTML format.
+    Args:
+        tabs: List of tab dicts
+    Returns:
+        HTML string for all tabs
+    """
+    html = ""
+    flattened_tabs = _flatten_tabs_for_html(tabs)
+    for tab in flattened_tabs:
+        html += _convert_single_tab_to_html(tab)
+    return html
+def _convert_single_tab_to_html(tab: dict) -> str:
+    """Convert a single tab to HTML.
+    Args:
+        tab: Single tab dict
+    Returns:
+        HTML string for the tab
+    """
+    if "documentTab" not in tab or "tabProperties" not in tab:
+        return ""
+    tab_props = tab.get("tabProperties")
+    if not tab_props:
+        return ""
+    nesting_level = _validate_nesting_level_for_html(tab_props.get("nestingLevel", 0))
+    tab_title = tab_props.get("title", "Untitled")
+    tab_id = tab_props.get("tabId", "")
+    escaped_tab_id = html_module.escape(tab_id, quote=True)
+    escaped_tab_title = html_module.escape(tab_title, quote=True)
+    header_level = min(nesting_level + 1, 6)
+    html = (
+        f'<section id="tab-{escaped_tab_id}" data-title="{escaped_tab_title}" '
+        f'data-level="{nesting_level}">'
+        f"<h{header_level}>{html_module.escape(tab_title)}</h{header_level}>"
+    )
+    html += _convert_tab_body_to_html(tab.get("documentTab", {}))
+    html += "</section>"
+    return html
+def _convert_body_to_html(body: dict) -> str:
+    """Convert document body to HTML.
+    Args:
+        body: Body dict with content
+    Returns:
+        HTML string
+    """
+    html = ""
+    for element in body.get("content", []):
+        html += convert_structural_element(element)
+    return html
+def _convert_tab_body_to_html(doc_tab: dict) -> str:
+    """Convert tab body content to HTML.
+    Args:
+        doc_tab: DocumentTab dict
+    Returns:
+        HTML string
+    """
+    body = doc_tab.get("body")
+    if not body:
+        return ""
+    html = ""
+    for element in body.get("content", []):
+        html += convert_structural_element(element)
+    return html
+def _validate_nesting_level_for_html(nesting_level: int) -> int:
+    """Validate and clamp nesting level to safe range.
+    Args:
+        nesting_level: The nesting level to validate
+    Returns:
+        Validated nesting level (0-5)
+    """
+    if not isinstance(nesting_level, int) or nesting_level < 0:
+        return 0
+    return nesting_level

arcade_google_docs/doc_to_markdown.py CHANGED Viewed

@@ -1,14 +1,43 @@
+"""
+Google Docs to Markdown converter.
+File organization:
+1. Public functions (convert_document_to_markdown, convert_structural_element, etc.)
+2. Private helper functions (prefixed with _) at the end
+"""
 import arcade_google_docs.doc_to_html as doc_to_html
-def convert_document_to_markdown(document: dict) -> str:
+def convert_document_to_markdown(document: dict, include_all_tabs: bool = True) -> str:
+    """Convert a Google Docs document to Markdown format.
+    Args:
+        document: Document dict from Google Docs API
+        include_all_tabs: Whether to include all tabs (True) or just main body (False)
+    Returns:
+        Markdown string representation of the document
+    """
     md = f"---\ntitle: {document['title']}\ndocumentId: {document['documentId']}\n---\n"
-    for element in document["body"]["content"]:
-        md += convert_structural_element(element)
+    if include_all_tabs and "tabs" in document and document["tabs"]:
+        md += _convert_tabs_to_markdown(document["tabs"])
+    else:
+        md += _convert_body_to_markdown(document.get("body", {}))
     return md
 def convert_structural_element(element: dict) -> str:
+    """Convert a structural element to markdown.
+    Args:
+        element: Structural element dict
+    Returns:
+        Markdown string
+    """
     if "sectionBreak" in element or "tableOfContents" in element:
         return ""
@@ -30,12 +59,29 @@ def convert_structural_element(element: dict) -> str:
 def extract_paragraph_content(text_run: dict) -> str:
+    """Extract and style paragraph content.
+    Args:
+        text_run: Text run dict
+    Returns:
+        Styled markdown string
+    """
     content = text_run["content"]
     style = text_run["textStyle"]
     return apply_text_style(content, style)
 def apply_text_style(content: str, style: dict) -> str:
+    """Apply text styling to content.
+    Args:
+        content: Text content
+        style: Style dict
+    Returns:
+        Styled content with markdown formatting
+    """
     append = "\n" if content.endswith("\n") else ""
     content = content.rstrip("\n")
     italic = style.get("italic", False)
@@ -48,6 +94,14 @@ def apply_text_style(content: str, style: dict) -> str:
 def get_paragraph_style_prepend_str(style: dict) -> str:
+    """Get markdown prefix for paragraph style.
+    Args:
+        style: Paragraph style dict
+    Returns:
+        Markdown prefix string (e.g., "# ", "## ", etc.)
+    """
     named_style = style["namedStyleType"]
     if named_style == "NORMAL_TEXT":
         return ""
@@ -62,3 +116,127 @@ def get_paragraph_style_prepend_str(style: dict) -> str:
         except ValueError:
             return ""
     return ""
+def _flatten_tabs_for_conversion(
+    tabs: list[dict], max_depth: int = 4, current_depth: int = 0
+) -> list[dict]:
+    """Flatten tab hierarchy using depth-first traversal for conversion.
+    Args:
+        tabs: List of tab dicts with potential childTabs
+        max_depth: Maximum recursion depth (Google Docs enforces 3 levels, using 4 for safety)
+        current_depth: Current recursion depth
+    Returns:
+        Flattened list in depth-first order
+    """
+    if current_depth >= max_depth:
+        return []
+    result: list[dict] = []
+    for tab in tabs:
+        result.append(tab)
+        if tab.get("childTabs"):
+            result.extend(
+                _flatten_tabs_for_conversion(tab["childTabs"], max_depth, current_depth + 1)
+            )
+    return result
+def _convert_tabs_to_markdown(tabs: list[dict]) -> str:
+    """Convert all tabs to markdown format.
+    Args:
+        tabs: List of tab dicts
+    Returns:
+        Markdown string for all tabs
+    """
+    md = ""
+    flattened_tabs = _flatten_tabs_for_conversion(tabs)
+    for tab in flattened_tabs:
+        md += _convert_single_tab_to_markdown(tab)
+    return md
+def _convert_single_tab_to_markdown(tab: dict) -> str:
+    """Convert a single tab to markdown.
+    Args:
+        tab: Single tab dict
+    Returns:
+        Markdown string for the tab
+    """
+    if "documentTab" not in tab or "tabProperties" not in tab:
+        return ""
+    tab_props = tab.get("tabProperties")
+    if not tab_props:
+        return ""
+    nesting_level = _validate_nesting_level(tab_props.get("nestingLevel", 0))
+    tab_title = tab_props.get("title", "Untitled")
+    tab_id = tab_props.get("tabId", "")
+    header_prefix = "#" * (nesting_level + 1)
+    md = f"\n{header_prefix} {tab_title}\n\n"
+    if tab_id:
+        md += f"<!-- Tab ID: {tab_id} -->\n\n"
+    else:
+        md += "<!-- Tab ID:  -->\n\n"
+    md += _convert_tab_body_to_markdown(tab.get("documentTab", {}))
+    return md
+def _convert_body_to_markdown(body: dict) -> str:
+    """Convert document body to markdown.
+    Args:
+        body: Body dict with content
+    Returns:
+        Markdown string
+    """
+    md = ""
+    for element in body.get("content", []):
+        md += convert_structural_element(element)
+    return md
+def _convert_tab_body_to_markdown(doc_tab: dict) -> str:
+    """Convert tab body content to markdown.
+    Args:
+        doc_tab: DocumentTab dict
+    Returns:
+        Markdown string
+    """
+    body = doc_tab.get("body")
+    if not body:
+        return ""
+    md = ""
+    for element in body.get("content", []):
+        md += convert_structural_element(element)
+    return md
+def _validate_nesting_level(nesting_level: int) -> int:
+    """Validate and clamp nesting level to safe range.
+    Args:
+        nesting_level: The nesting level to validate
+    Returns:
+        Validated nesting level (0-5)
+    """
+    if not isinstance(nesting_level, int) or nesting_level < 0:
+        return 0
+    return min(nesting_level, 5)

arcade-google-docs 4.3.1__py3-none-any.whl → 5.0.0__py3-none-any.whl

arcade-google-docs 4.3.1py3-none-any.whl → 5.0.0py3-none-any.whl