Merge pull request #436 from the-gigi-pplx/feature/doc-links

Add hyperlink support to modify_doc_text

Author: taylorwilsdon

README.md

@@ -930,7 +930,7 @@ Saved files expire after 1 hour and are cleaned up automatically.
 |------|------|-------------|
 | `get_doc_content` | **Core** | Extract document text |
 | `create_doc` | **Core** | Create new documents |
-| `modify_doc_text` | **Core** | Modify document text |
+| `modify_doc_text` | **Core** | Modify document text (formatting + links) |
 | `search_docs` | Extended | Find documents by name |
 | `find_and_replace_doc` | Extended | Find and replace text |
 | `list_docs_in_folder` | Extended | List docs in folder |

README_NEW.md

@@ -97,7 +97,7 @@ export OAUTHLIB_INSECURE_TRANSPORT=1  # Development only
 |------|------|-------------|
 | `get_doc_content` | Core | Extract text from Docs or .docx files (supports tabs) |
 | `create_doc` | Core | Create new documents with optional initial content |
-| `modify_doc_text` | Core | Insert, replace, format text (bold, italic, colors, fonts) |
+| `modify_doc_text` | Core | Insert, replace, format text (bold, italic, colors, fonts, links) |
 | `search_docs` | Extended | Find documents by name |
 | `find_and_replace_doc` | Extended | Global find/replace with case matching |
 | `list_docs_in_folder` | Extended | List Docs in a specific folder |

gdocs/docs_helpers.py

@@ -46,6 +46,7 @@ def build_text_style(
     font_family: str = None,
     text_color: str = None,
     background_color: str = None,
+    link_url: str = None,
 ) -> tuple[Dict[str, Any], list[str]]:
     """
     Build text style object for Google Docs API requests.
@@ -58,6 +59,7 @@ def build_text_style(
         font_family: Font family name
         text_color: Text color as hex string "#RRGGBB"
         background_color: Background (highlight) color as hex string "#RRGGBB"
+        link_url: Hyperlink URL (http/https)
 
     Returns:
         Tuple of (text_style_dict, list_of_field_names)
@@ -95,6 +97,10 @@ def build_text_style(
         text_style["backgroundColor"] = {"color": {"rgbColor": rgb}}
         fields.append("backgroundColor")
 
+    if link_url is not None:
+        text_style["link"] = {"url": link_url}
+        fields.append("link")
+
     return text_style, fields
 
 
@@ -242,6 +248,7 @@ def create_format_text_request(
     font_family: str = None,
     text_color: str = None,
     background_color: str = None,
+    link_url: str = None,
 ) -> Optional[Dict[str, Any]]:
     """
     Create an updateTextStyle request for Google Docs API.
@@ -256,12 +263,20 @@ def create_format_text_request(
         font_family: Font family name
         text_color: Text color as hex string "#RRGGBB"
         background_color: Background (highlight) color as hex string "#RRGGBB"
+        link_url: Hyperlink URL (http/https)
 
     Returns:
         Dictionary representing the updateTextStyle request, or None if no styles provided
     """
     text_style, fields = build_text_style(
-        bold, italic, underline, font_size, font_family, text_color, background_color
+        bold,
+        italic,
+        underline,
+        font_size,
+        font_family,
+        text_color,
+        background_color,
+        link_url,
     )
 
     if not text_style:

gdocs/docs_tools.py

@@ -367,6 +367,7 @@ async def modify_doc_text(
     font_family: str = None,
     text_color: str = None,
     background_color: str = None,
+    link_url: str = None,
 ) -> str:
     """
     Modifies text in a Google Doc - can insert/replace text and/or apply formatting in a single operation.
@@ -384,13 +385,14 @@ async def modify_doc_text(
         font_family: Font family name (e.g., "Arial", "Times New Roman")
         text_color: Foreground text color (#RRGGBB)
         background_color: Background/highlight color (#RRGGBB)
+        link_url: Hyperlink URL (http/https)
 
     Returns:
         str: Confirmation message with operation details
     """
     logger.info(
         f"[modify_doc_text] Doc={document_id}, start={start_index}, end={end_index}, text={text is not None}, "
-        f"formatting={any([bold, italic, underline, font_size, font_family, text_color, background_color])}"
+        f"formatting={any(p is not None for p in [bold, italic, underline, font_size, font_family, text_color, background_color, link_url])}"
     )
 
     # Input validation
@@ -401,31 +403,21 @@ async def modify_doc_text(
         return f"Error: {error_msg}"
 
     # Validate that we have something to do
-    if text is None and not any(
-        [
-            bold is not None,
-            italic is not None,
-            underline is not None,
-            font_size,
-            font_family,
-            text_color,
-            background_color,
-        ]
-    ):
-        return "Error: Must provide either 'text' to insert/replace, or formatting parameters (bold, italic, underline, font_size, font_family, text_color, background_color)."
+    formatting_params = [
+        bold,
+        italic,
+        underline,
+        font_size,
+        font_family,
+        text_color,
+        background_color,
+        link_url,
+    ]
+    if text is None and not any(p is not None for p in formatting_params):
+        return "Error: Must provide either 'text' to insert/replace, or formatting parameters (bold, italic, underline, font_size, font_family, text_color, background_color, link_url)."
 
     # Validate text formatting params if provided
-    if any(
-        [
-            bold is not None,
-            italic is not None,
-            underline is not None,
-            font_size,
-            font_family,
-            text_color,
-            background_color,
-        ]
-    ):
+    if any(p is not None for p in formatting_params):
         is_valid, error_msg = validator.validate_text_formatting_params(
             bold,
             italic,
@@ -434,6 +426,7 @@ async def modify_doc_text(
             font_family,
             text_color,
             background_color,
+            link_url,
         )
         if not is_valid:
             return f"Error: {error_msg}"
@@ -482,17 +475,7 @@ async def modify_doc_text(
             operations.append(f"Inserted text at index {start_index}")
 
     # Handle formatting
-    if any(
-        [
-            bold is not None,
-            italic is not None,
-            underline is not None,
-            font_size,
-            font_family,
-            text_color,
-            background_color,
-        ]
-    ):
+    if any(p is not None for p in formatting_params):
         # Adjust range for formatting based on text operations
         format_start = start_index
         format_end = end_index
@@ -524,24 +507,24 @@ async def modify_doc_text(
                 font_family,
                 text_color,
                 background_color,
+                link_url,
             )
         )
 
-        format_details = []
-        if bold is not None:
-            format_details.append(f"bold={bold}")
-        if italic is not None:
-            format_details.append(f"italic={italic}")
-        if underline is not None:
-            format_details.append(f"underline={underline}")
-        if font_size:
-            format_details.append(f"font_size={font_size}")
-        if font_family:
-            format_details.append(f"font_family={font_family}")
-        if text_color:
-            format_details.append(f"text_color={text_color}")
-        if background_color:
-            format_details.append(f"background_color={background_color}")
+        format_details = [
+            f"{name}={value}"
+            for name, value in [
+                ("bold", bold),
+                ("italic", italic),
+                ("underline", underline),
+                ("font_size", font_size),
+                ("font_family", font_family),
+                ("text_color", text_color),
+                ("background_color", background_color),
+                ("link_url", link_url),
+            ]
+            if value is not None
+        ]
 
         operations.append(
             f"Applied formatting ({', '.join(format_details)}) to range {format_start}-{format_end}"

gdocs/managers/batch_operation_manager.py

@@ -190,6 +190,7 @@ def _build_operation_request(
                 op.get("font_family"),
                 op.get("text_color"),
                 op.get("background_color"),
+                op.get("link_url"),
             )
 
             if not request:
@@ -205,6 +206,7 @@ def _build_operation_request(
                 ("font_family", "font family"),
                 ("text_color", "text color"),
                 ("background_color", "background color"),
+                ("link_url", "link"),
             ]:
                 if op.get(param) is not None:
                     value = f"{op[param]}pt" if param == "font_size" else op[param]
@@ -370,6 +372,7 @@ def get_supported_operations(self) -> dict[str, Any]:
                         "font_family",
                         "text_color",
                         "background_color",
+                        "link_url",
                     ],
                     "description": "Apply formatting to text range",
                 },

gdocs/managers/validation_manager.py

@@ -7,6 +7,7 @@
 
 import logging
 from typing import Dict, Any, List, Tuple, Optional
+from urllib.parse import urlparse
 
 from gdocs.docs_helpers import validate_operation
 
@@ -159,6 +160,7 @@ def validate_text_formatting_params(
         font_family: Optional[str] = None,
         text_color: Optional[str] = None,
         background_color: Optional[str] = None,
+        link_url: Optional[str] = None,
     ) -> Tuple[bool, str]:
         """
         Validate text formatting parameters.
@@ -171,6 +173,7 @@ def validate_text_formatting_params(
             font_family: Font family name
             text_color: Text color in "#RRGGBB" format
             background_color: Background color in "#RRGGBB" format
+            link_url: Hyperlink URL (http/https)
 
         Returns:
             Tuple of (is_valid, error_message)
@@ -184,11 +187,12 @@ def validate_text_formatting_params(
             font_family,
             text_color,
             background_color,
+            link_url,
         ]
         if all(param is None for param in formatting_params):
             return (
                 False,
-                "At least one formatting parameter must be provided (bold, italic, underline, font_size, font_family, text_color, or background_color)",
+                "At least one formatting parameter must be provided (bold, italic, underline, font_size, font_family, text_color, background_color, or link_url)",
             )
 
         # Validate boolean parameters
@@ -240,6 +244,30 @@ def validate_text_formatting_params(
         if not is_valid:
             return False, error_msg
 
+        is_valid, error_msg = self.validate_link_url(link_url)
+        if not is_valid:
+            return False, error_msg
+
+        return True, ""
+
+    def validate_link_url(self, link_url: Optional[str]) -> Tuple[bool, str]:
+        """Validate hyperlink URL parameters."""
+        if link_url is None:
+            return True, ""
+
+        if not isinstance(link_url, str):
+            return False, f"link_url must be a string, got {type(link_url).__name__}"
+
+        if not link_url.strip():
+            return False, "link_url cannot be empty"
+
+        parsed = urlparse(link_url)
+        if parsed.scheme not in ("http", "https"):
+            return False, "link_url must start with http:// or https://"
+
+        if not parsed.netloc:
+            return False, "link_url must include a valid host"
+
         return True, ""
 
     def validate_paragraph_style_params(
@@ -578,6 +606,7 @@ def validate_batch_operations(
                     op.get("font_family"),
                     op.get("text_color"),
                     op.get("background_color"),
+                    op.get("link_url"),
                 )
                 if not is_valid:
                     return False, f"Operation {i + 1} (format_text): {error_msg}"