wordlift-sdk 2.7.6__py3-none-any.whl → 2.9.0__py3-none-any.whl

wordlift_sdk/google_sheets/__init__.py

@@ -0,0 +1,3 @@
+from .google_sheets_lookup import GoogleSheetsLookup
+
+__all__ = ["GoogleSheetsLookup"]

wordlift_sdk/google_sheets/google_sheets_lookup.py

@@ -0,0 +1,121 @@
+import logging
+import os
+from typing import Optional, Any, Dict
+
+import gspread
+from wordlift_sdk.configuration import ConfigurationProvider
+
+logger = logging.getLogger(__name__)
+
+
+class GoogleSheetsLookup:
+    """
+    A generic class to lookup values from a Google Sheet.
+    Preloads data upon initialization for O(1) lookup performance.
+    """
+
+    def __init__(
+        self,
+        spreadsheet_url: str,
+        sheet_name: str,
+        key_column: str,
+        value_column: str,
+        configuration_provider: ConfigurationProvider,
+        service_account_file: Optional[str] = None,
+    ):
+        """
+        Initialize the GoogleSheetsLookup.
+
+        :param spreadsheet_url: The URL of the Google Sheet.
+        :param sheet_name: The name of the specific worksheet (tab).
+        :param key_column: The header name of the column to use as keys.
+        :param value_column: The header name of the column to use as values.
+        :param configuration_provider: The ConfigurationProvider instance.
+        :param service_account_file: Optional path to the service account JSON file.
+                                     If not provided, it will be looked up in the configuration.
+        """
+        self.spreadsheet_url = spreadsheet_url
+        self.sheet_name = sheet_name
+        self.key_column = key_column
+        self.value_column = value_column
+        self.configuration_provider = configuration_provider
+        self.service_account_file = service_account_file
+
+        self._data: Dict[str, Any] = {}
+        self._load_data()
+
+    def _resolve_service_account_file(self) -> Optional[str]:
+        """
+        Resolves the service account file path.
+        Priority:
+        1. Argument passed to __init__
+        2. 'SERVICE_ACCOUNT_FILE' from ConfigurationProvider
+        """
+        if self.service_account_file:
+            return self.service_account_file
+
+        # Attempt to retrieve from ConfigurationProvider
+        return self.configuration_provider.get_value("SERVICE_ACCOUNT_FILE")
+
+        # Fallback: check environment variable directly if ConfigurationProvider
+        # behavior is different or it didn't return anything.
+        return os.getenv("SERVICE_ACCOUNT_FILE")
+
+    def _load_data(self):
+        """
+        Connects to Google Sheets and preloads the data into a dictionary.
+        """
+        credentials_file = self._resolve_service_account_file()
+
+        try:
+            if credentials_file:
+                logger.info(
+                    f"Connecting to Google Sheets using credentials: {credentials_file}"
+                )
+                gc = gspread.service_account(filename=credentials_file)
+            else:
+                logger.info(
+                    "Connecting to Google Sheets using default environment credentials"
+                )
+                gc = gspread.service_account()
+
+            # Open spreadsheet by URL
+            sh = gc.open_by_url(self.spreadsheet_url)
+
+            # Select worksheet
+            worksheet = sh.worksheet(self.sheet_name)
+
+            # Get all records
+            records = worksheet.get_all_records()
+            logger.info(
+                f"Fetched {len(records)} records from sheet '{self.sheet_name}'"
+            )
+
+            # Build lookup dictionary
+            for i, record in enumerate(records):
+                key = record.get(self.key_column)
+                value = record.get(self.value_column)
+
+                if key is None:
+                    logger.warning(
+                        f"Row {i + 2}: Key column '{self.key_column}' is missing or empty. Skipping."
+                    )
+                    continue
+
+                # We stringify the key to ensure consistent lookup, optional but recommended for mixed types
+                self._data[str(key)] = value
+
+            logger.info(f"Successfully loaded {len(self._data)} items into cache.")
+
+        except Exception as e:
+            logger.error(f"Failed to load data from Google Sheets: {e}")
+            raise
+
+    def get_value(self, key: Any) -> Optional[Any]:
+        """
+        Look up a value by its key.
+
+        :param key: The key to look up.
+        :return: The corresponding value, or None if not found.
+        """
+        return self._data.get(str(key))

wordlift_sdk/utils/__init__.py

@@ -1,10 +1,13 @@
 from .create_dataframe_from_google_sheets import create_dataframe_from_google_sheets
 from .create_dataframe_of_entities_by_types import create_dataframe_of_entities_by_types
-from .create_dataframe_of_entities_with_embedding_vectors import create_dataframe_of_entities_with_embedding_vectors
+from .create_dataframe_of_entities_with_embedding_vectors import (
+    create_dataframe_of_entities_with_embedding_vectors,
+)
 from .create_dataframe_of_url_iri import create_dataframe_of_url_iri
 from .create_entity_patch_request import create_entity_patch_request
 from .delayed import create_delayed
 from .get_me import get_me
+from .html_converter import HtmlConverter
 
 __all__ = [
     "create_dataframe_from_google_sheets",
@@ -13,5 +16,6 @@ __all__ = [
     "create_dataframe_of_url_iri",
     "create_entity_patch_request",
     "create_delayed",
-    "get_me"
+    "get_me",
+    "HtmlConverter",
 ]

wordlift_sdk/utils/html_converter.py

@@ -0,0 +1,56 @@
+"""HTML to XHTML conversion utility."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_INVALID_XML_CHARS_RE = re.compile(r"[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]")
+_XML_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_.:-]*$")
+
+
+class HtmlConverter:
+    """Converts HTML to XHTML."""
+
+    def convert(self, html: str) -> str:
+        """
+        Convert an HTML string to a valid XHTML string.
+
+        Args:
+            html: The raw HTML string.
+
+        Returns:
+            A sanitized XHTML string.
+        """
+        html = re.sub(r"<!DOCTYPE[^>]*>", "", html, flags=re.IGNORECASE)
+        html = self._strip_invalid_xml_chars(html)
+        try:
+            from lxml import html as lxml_html
+        except ImportError as exc:
+            raise ImportError(
+                "lxml is required for XHTML output. Install with: pip install lxml"
+            ) from exc
+
+        try:
+            parser = lxml_html.HTMLParser(encoding="utf-8", recover=True)
+            doc = lxml_html.document_fromstring(html, parser=parser)
+            self._sanitize_xhtml_tree(doc)
+            xhtml = lxml_html.tostring(doc, encoding="unicode", method="xml")
+            return self._strip_invalid_xml_chars(xhtml)
+        except Exception as exc:
+            raise RuntimeError("Failed to convert HTML to XHTML.") from exc
+
+    def _strip_invalid_xml_chars(self, value: str) -> str:
+        return _INVALID_XML_CHARS_RE.sub("", value)
+
+    def _sanitize_xhtml_tree(self, doc: Any) -> None:
+        for element in doc.iter():
+            if not hasattr(element, "attrib"):
+                continue
+            for attr in list(element.attrib):
+                if not _XML_NAME_RE.match(attr):
+                    del element.attrib[attr]
+                    continue
+                value = element.attrib.get(attr)
+                if isinstance(value, str):
+                    element.attrib[attr] = self._strip_invalid_xml_chars(value)

{wordlift_sdk-2.7.6.dist-info → wordlift_sdk-2.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wordlift-sdk
-Version: 2.7.6
+Version: 2.9.0
 Summary: 
 Author: David Riccitelli
 Author-email: david@wordlift.io
@@ -123,3 +123,8 @@ poetry install --with dev
 poetry run pytest
 ```
 
+## Documentation
+
+- [Google Sheets Lookup](docs/google_sheets_lookup.md): Utility for O(1) lookups from Google Sheets.
+
+

{wordlift_sdk-2.7.6.dist-info → wordlift_sdk-2.9.0.dist-info}/RECORD

@@ -14,6 +14,8 @@ wordlift_sdk/entity/patch.py,sha256=CP2H2nrrli4A_zu1D00Egye1I784ZQ6MxL_jS9ZsW9k,
 wordlift_sdk/google_search_console/__init__.py,sha256=-PmsnNYsGs4Utb9l7AXz0qAzcWhJeD-eZyFNfOHM5ow,384
 wordlift_sdk/google_search_console/create_google_search_console_data_import.py,sha256=xP_koUaaXYnnNVyw2ld4jbqc_d7yFkYXLe2dC2vLpm0,2223
 wordlift_sdk/google_search_console/raise_error_if_account_analytics_not_configured.py,sha256=pXcRlaVAODSbSgxI3KTtsHp37qiIaWCu9ISDKtDw6qM,830
+wordlift_sdk/google_sheets/__init__.py,sha256=CEeLCBM2IJ_Yux0bY2T4MfIHVRc93OMF3aRPfpIYXRU,87
+wordlift_sdk/google_sheets/google_sheets_lookup.py,sha256=oQwPizlT7Imbeq_Vlc5ZWfv2lkrO4VnA2sNeqdZHqew,4278
 wordlift_sdk/graph/graph_bag.py,sha256=Gp0ufstKY5xCx6dZNohcTmaEhoEYef891eaLuESUJpM,105
 wordlift_sdk/graph/ttl_liquid/__init__.py,sha256=2AmJpsFFkJxv6FyO7J3XFUfX1nSPDoY31tRom-K5C_w,97
 wordlift_sdk/graph/ttl_liquid/ttl_liquid_graph_factory.py,sha256=CSzO36YZ-XQrV7xRi99LhmYfQgMxjBkKdfEGeD0Zt9M,1242
@@ -65,7 +67,7 @@ wordlift_sdk/url_source/new_or_changed_url_source.py,sha256=81ZEitfxxMof5-fcKuvT
 wordlift_sdk/url_source/sitemap_url_source.py,sha256=JMIteakIFIWcHoQ3Uf0fyMh8pYz4YM_rnJvdm7NXYak,1198
 wordlift_sdk/url_source/url_source.py,sha256=ZmGOiDlPVzoOTt2Qz69onpnFzQYZlrwWaogOkZMEqGc,403
 wordlift_sdk/url_source/url_source_input.py,sha256=GvRAjBb103DS--rR7M8oIxIjWhQbYUTldwbPx2BctaU,152
-wordlift_sdk/utils/__init__.py,sha256=_BB9cgIXFY5JUDowedu2tZeQmLhtGElUTh6qzVQ-Xoc,759
+wordlift_sdk/utils/__init__.py,sha256=3l2N8t7LlaEScp08rRApx6fKvx3bo9hnUdGAcZRZG8w,832
 wordlift_sdk/utils/create_dataframe_from_google_sheets.py,sha256=7j0oCwUwSqoo2505_QfcUCx4XNqhw94Y_UTL5tyIk5U,1117
 wordlift_sdk/utils/create_dataframe_of_entities_by_types.py,sha256=5U5k_OheifPJyod4PB0HEdYCGwZEMgkdiwckAR8LFJY,770
 wordlift_sdk/utils/create_dataframe_of_entities_with_embedding_vectors.py,sha256=A_JMVoYS4pcWCsKYGH_sHyc9MJvg5EuoKELp1BCI2Ko,679
@@ -73,6 +75,7 @@ wordlift_sdk/utils/create_dataframe_of_url_iri.py,sha256=xTxNyHb1Vo7YdfoYoaiCqp6
 wordlift_sdk/utils/create_entity_patch_request.py,sha256=-fEZrflVpTBtk7c7ME8-BWn6-r86cQJp7fvQJznj_aU,497
 wordlift_sdk/utils/delayed.py,sha256=uy-cQsLMprakx8CiQl6ZLL49bfYB1C6oQt4UObr5TwU,323
 wordlift_sdk/utils/get_me.py,sha256=-mr0DscVWEDFvgBYtmgND3_gIuh2q7kfD-OiqrYwLJU,297
+wordlift_sdk/utils/html_converter.py,sha256=MGdXQg2EAhI2K7CWtbIzZip08clVPUgL84Xt_xxa-h4,1945
 wordlift_sdk/utils/import_url.py,sha256=KiUFkU4mRfd7YWFlLoz5bB13AgPURV8Km8H05LxevCI,1299
 wordlift_sdk/wordlift/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 wordlift_sdk/wordlift/entity_gaps/__init__.py,sha256=PMtdyBoUD-oiTE-7Izr6fuod7OxGOQIhFSasZG_SafM,109
@@ -95,6 +98,6 @@ wordlift_sdk/workflow/url_handler/default_url_handler.py,sha256=irMoJftx9Gyq-8HQ
 wordlift_sdk/workflow/url_handler/search_console_url_handler.py,sha256=uOwD4t009-cA9JI7ZtbYhCGRwjhLzDpBNTWHERPnNqI,2698
 wordlift_sdk/workflow/url_handler/url_handler.py,sha256=meyOpWVhLk2NcbtUOO_V0z6_T9q-D3pD7kWQCRioYh0,129
 wordlift_sdk/workflow/url_handler/web_page_import_url_handler.py,sha256=xQiy-fgFj_dWKFFBNWeodAGhIMJQereSPdgnjK-Crmo,3529
-wordlift_sdk-2.7.6.dist-info/METADATA,sha256=GtUczWgOG4_IP8PN5NisKsEh4YPnxYS_iNcU9ekXCio,4977
-wordlift_sdk-2.7.6.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-wordlift_sdk-2.7.6.dist-info/RECORD,,
+wordlift_sdk-2.9.0.dist-info/METADATA,sha256=NF2Kp2Z4kFdv2TXA7Tf3zJjzebs_EuH8MG0deldHtx4,5098
+wordlift_sdk-2.9.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+wordlift_sdk-2.9.0.dist-info/RECORD,,