sfq 0.0.10__tar.gz → 0.0.12__tar.gz

{sfq-0.0.10 → sfq-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sfq
-Version: 0.0.10
+Version: 0.0.12
 Summary: Python wrapper for the Salesforce's Query API.
 Author-email: David Moruzzi <sfq.pypi@dmoruzi.com>
 Keywords: salesforce,salesforce query

{sfq-0.0.10 → sfq-0.0.12}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sfq"
-version = "0.0.10"
+version = "0.0.12"
 description = "Python wrapper for the Salesforce's Query API."
 readme = "README.md"
 authors = [{ name = "David Moruzzi", email = "sfq.pypi@dmoruzi.com" }]

{sfq-0.0.10 → sfq-0.0.12}/src/sfq/__init__.py

@@ -4,6 +4,10 @@ import json
 import logging
 import os
 import time
+import warnings
+from collections import OrderedDict
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from queue import Empty, Queue
 from typing import Any, Dict, Optional
 from urllib.parse import quote, urlparse
 
@@ -11,31 +15,43 @@ TRACE = 5
 logging.addLevelName(TRACE, "TRACE")
 
 
+class ExperimentalWarning(Warning):
+    pass
+
+
 def trace(self: logging.Logger, message: str, *args: Any, **kwargs: Any) -> None:
     """Custom TRACE level logging function with redaction."""
 
     def _redact_sensitive(data: Any) -> Any:
         """Redacts sensitive keys from a dictionary or query string."""
         REDACT_VALUE = "*" * 8
+        REDACT_KEYS = [
+            "access_token",
+            "authorization",
+            "set-cookie",
+            "cookie",
+            "refresh_token",
+        ]
         if isinstance(data, dict):
             return {
-                k: (
-                    REDACT_VALUE
-                    if k.lower() in ["access_token", "authorization", "refresh_token"]
-                    else v
-                )
+                k: (REDACT_VALUE if k.lower() in REDACT_KEYS else v)
                 for k, v in data.items()
             }
+        elif isinstance(data, (list, tuple)):
+            return type(data)(
+                (
+                    (item[0], REDACT_VALUE)
+                    if isinstance(item, tuple) and item[0].lower() in REDACT_KEYS
+                    else item
+                    for item in data
+                )
+            )
         elif isinstance(data, str):
             parts = data.split("&")
             for i, part in enumerate(parts):
                 if "=" in part:
                     key, value = part.split("=", 1)
-                    if key.lower() in [
-                        "access_token",
-                        "authorization",
-                        "refresh_token",
-                    ]:
+                    if key.lower() in REDACT_KEYS:
                         parts[i] = f"{key}={REDACT_VALUE}"
             return "&".join(parts)
         return data
@@ -71,7 +87,7 @@ class SFAuth:
         access_token: Optional[str] = None,
         token_expiration_time: Optional[float] = None,
         token_lifetime: int = 15 * 60,
-        user_agent: str = "sfq/0.0.10",
+        user_agent: str = "sfq/0.0.12",
         proxy: str = "auto",
     ) -> None:
         """
@@ -85,7 +101,7 @@ class SFAuth:
         :param access_token: The access token for the current session (default is None).
         :param token_expiration_time: The expiration time of the access token (default is None).
         :param token_lifetime: The lifetime of the access token in seconds (default is 15 minutes).
-        :param user_agent: Custom User-Agent string (default is "sfq/0.0.10").
+        :param user_agent: Custom User-Agent string (default is "sfq/0.0.12").
         :param proxy: The proxy configuration, "auto" to use environment (default is "auto").
         """
         self.instance_url = instance_url
@@ -179,6 +195,7 @@ class SFAuth:
             logger.exception("Error during token request: %s", err)
 
         finally:
+            logger.trace("Closing connection.")
             conn.close()
 
         return None
@@ -346,6 +363,7 @@ class SFAuth:
             )
 
         finally:
+            logger.trace("Closing connection...")
             conn.close()
 
         return None
@@ -444,6 +462,7 @@ class SFAuth:
             logger.exception("Error during patch request: %s", err)
 
         finally:
+            logger.trace("Closing connection.")
             conn.close()
 
         return None
@@ -492,6 +511,7 @@ class SFAuth:
             logger.exception("Error during limits request: %s", err)
 
         finally:
+            logger.debug("Closing connection...")
             conn.close()
 
         return None
@@ -573,6 +593,7 @@ class SFAuth:
             logger.exception("Exception during query: %s", err)
 
         finally:
+            logger.trace("Closing connection...")
             conn.close()
 
         return None
@@ -585,3 +606,324 @@ class SFAuth:
         :return: Parsed JSON response or None on failure.
         """
         return self.query(query, tooling=True)
+
+    def cquery(self, query_dict: dict[str, str], max_workers: int = 10) -> Optional[Dict[str, Any]]:
+        """
+        Execute multiple SOQL queries using the Composite Batch API with threading to reduce network overhead.
+        The function returns a dictionary mapping the original keys to their corresponding batch response.
+        The function requires a dictionary of SOQL queries with keys as logical names (referenceId) and values as SOQL queries.
+        Each query (subrequest) is counted as a unique API request against Salesforce governance limits.
+
+        :param query_dict: A dictionary of SOQL queries with keys as logical names and values as SOQL queries.
+        :param max_workers: The maximum number of threads to spawn for concurrent execution (default is 10).
+        :return: Dict mapping the original keys to their corresponding batch response or None on failure.
+        """
+        if not query_dict:
+            logger.warning("No queries to execute.")
+            return None
+
+        self._refresh_token_if_needed()
+
+        if not self.access_token:
+            logger.error("No access token available for query.")
+            return None
+
+        def _execute_batch(queries_batch):
+            endpoint = f"/services/data/{self.api_version}/composite/batch"
+            headers = {
+                "Authorization": f"Bearer {self.access_token}",
+                "User-Agent": self.user_agent,
+                "Accept": "application/json",
+                "Content-Type": "application/json",
+            }
+
+            payload = {
+                "haltOnError": False,
+                "batchRequests": [
+                    {
+                        "method": "GET",
+                        "url": f"/services/data/{self.api_version}/query?q={quote(query)}",
+                    }
+                    for query in queries_batch
+                ],
+            }
+
+            parsed_url = urlparse(self.instance_url)
+            conn = self._create_connection(parsed_url.netloc)
+            batch_results = {}
+
+            try:
+                logger.trace("Request endpoint: %s", endpoint)
+                logger.trace("Request headers: %s", headers)
+                logger.trace("Request payload: %s", json.dumps(payload, indent=2))
+
+                conn.request("POST", endpoint, json.dumps(payload), headers=headers)
+                conn.sock.settimeout(60 * 10)
+                response = conn.getresponse()
+                data = response.read().decode("utf-8")
+                self._http_resp_header_logic(response)
+
+                if response.status == 200:
+                    logger.debug("Composite query successful.")
+                    logger.trace("Composite query full response: %s", data)
+                    results = json.loads(data).get("results", [])
+                    for i, result in enumerate(results):
+                        batch_results[keys[i]] = result
+                        if result.get("statusCode") != 200:
+                            logger.error("Query failed for key %s: %s", keys[i], result)
+                            logger.error(
+                                "Query failed with HTTP status %s (%s)",
+                                result.get("statusCode"),
+                                result.get("statusMessage"),
+                            )
+                            logger.trace("Query response: %s", result)
+                else:
+                    logger.error(
+                        "Composite query failed with HTTP status %s (%s)",
+                        response.status,
+                        response.reason,
+                    )
+                    batch_results[keys[i]] = data
+                    logger.trace("Composite query response: %s", data)
+            except Exception as err:
+                logger.exception("Exception during composite query: %s", err)
+            finally:
+                logger.trace("Closing connection...")
+                conn.close()
+
+            return batch_results
+
+        keys = list(query_dict.keys())
+        results_dict = OrderedDict()
+
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = []
+            for i in range(0, len(keys), 25):
+                batch_keys = keys[i : i + 25]
+                batch_queries = [query_dict[key] for key in batch_keys]
+                futures.append(executor.submit(_execute_batch, batch_queries))
+
+            for future in as_completed(futures):
+                results_dict.update(future.result())
+
+        logger.trace("Composite query results: %s", results_dict)
+        return results_dict
+
+    def _subscribe_topic(
+        self,
+        topic: str,
+        queue_timeout: int = 90,
+        max_runtime: Optional[int] = None,
+    ):
+        """
+        Yields events from a subscribed Salesforce CometD topic.
+
+        :param topic: Topic to subscribe to, e.g. '/event/MyEvent__e'
+        :param queue_timeout: Seconds to wait for a message before logging heartbeat
+        :param max_runtime: Max total time to listen in seconds (None = unlimited)
+        """
+        warnings.warn(
+            "The _subscribe_topic method is experimental and subject to change in future versions.",
+            ExperimentalWarning,
+            stacklevel=2,
+        )
+
+        self._refresh_token_if_needed()
+        self._msg_count: int = 0
+
+        if not self.access_token:
+            logger.error("No access token available for event stream.")
+            return
+
+        start_time = time.time()
+        message_queue = Queue()
+        headers = {
+            "Authorization": f"Bearer {self.access_token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": self.user_agent,
+        }
+
+        parsed_url = urlparse(self.instance_url)
+        conn = self._create_connection(parsed_url.netloc)
+        _API_VERSION = str(self.api_version).removeprefix("v")
+        client_id = str()
+
+        try:
+            logger.trace("Starting handshake with Salesforce CometD server.")
+            handshake_payload = json.dumps(
+                {
+                    "id": str(self._msg_count + 1),
+                    "version": "1.0",
+                    "minimumVersion": "1.0",
+                    "channel": "/meta/handshake",
+                    "supportedConnectionTypes": ["long-polling"],
+                    "advice": {"timeout": 60000, "interval": 0},
+                }
+            )
+            conn.request(
+                "POST",
+                f"/cometd/{_API_VERSION}/meta/handshake",
+                headers=headers,
+                body=handshake_payload,
+            )
+            response = conn.getresponse()
+            self._http_resp_header_logic(response)
+
+            logger.trace("Received handshake response.")
+            for name, value in response.getheaders():
+                if name.lower() == "set-cookie" and "BAYEUX_BROWSER=" in value:
+                    _bayeux_browser_cookie = value.split("BAYEUX_BROWSER=")[1].split(
+                        ";"
+                    )[0]
+                    headers["Cookie"] = f"BAYEUX_BROWSER={_bayeux_browser_cookie}"
+                    break
+
+            data = json.loads(response.read().decode("utf-8"))
+            if not data or not data[0].get("successful"):
+                logger.error("Handshake failed: %s", data)
+                return
+
+            client_id = data[0]["clientId"]
+            logger.trace(f"Handshake successful, client ID: {client_id}")
+
+            logger.trace(f"Subscribing to topic: {topic}")
+            subscribe_message = {
+                "channel": "/meta/subscribe",
+                "clientId": client_id,
+                "subscription": topic,
+                "id": str(self._msg_count + 1),
+            }
+            conn.request(
+                "POST",
+                f"/cometd/{_API_VERSION}/meta/subscribe",
+                headers=headers,
+                body=json.dumps(subscribe_message),
+            )
+            response = conn.getresponse()
+            self._http_resp_header_logic(response)
+
+            sub_response = json.loads(response.read().decode("utf-8"))
+            if not sub_response or not sub_response[0].get("successful"):
+                logger.error("Subscription failed: %s", sub_response)
+                return
+
+            logger.info(f"Successfully subscribed to topic: {topic}")
+            logger.trace("Entering event polling loop.")
+
+            try:
+                while True:
+                    if max_runtime and (time.time() - start_time > max_runtime):
+                        logger.info(
+                            f"Disconnecting after max_runtime={max_runtime} seconds"
+                        )
+                        break
+
+                    logger.trace("Sending connection message.")
+                    connect_payload = json.dumps(
+                        [
+                            {
+                                "channel": "/meta/connect",
+                                "clientId": client_id,
+                                "connectionType": "long-polling",
+                                "id": str(self._msg_count + 1),
+                            }
+                        ]
+                    )
+
+                    max_retries = 5
+                    attempt = 0
+
+                    while attempt < max_retries:
+                        try:
+                            conn.request(
+                                "POST",
+                                f"/cometd/{_API_VERSION}/meta/connect",
+                                headers=headers,
+                                body=connect_payload,
+                            )
+                            response = conn.getresponse()
+                            self._http_resp_header_logic(response)
+                            self._msg_count += 1
+
+                            events = json.loads(response.read().decode("utf-8"))
+                            for event in events:
+                                if event.get("channel") == topic and "data" in event:
+                                    logger.trace(
+                                        f"Event received for topic {topic}, data: {event['data']}"
+                                    )
+                                    message_queue.put(event)
+                            break
+                        except (
+                            http.client.RemoteDisconnected,
+                            ConnectionResetError,
+                            TimeoutError,
+                            http.client.BadStatusLine,
+                            http.client.CannotSendRequest,
+                            ConnectionAbortedError,
+                            ConnectionRefusedError,
+                            ConnectionError,
+                        ) as e:
+                            logger.warning(
+                                f"Connection error (attempt {attempt + 1}): {e}"
+                            )
+                            conn.close()
+                            conn = self._create_connection(parsed_url.netloc)
+                            self._reconnect_with_backoff(attempt)
+                            attempt += 1
+                        except Exception as e:
+                            logger.exception(
+                                f"Connection error (attempt {attempt + 1}): {e}"
+                            )
+                            break
+                    else:
+                        logger.error("Max retries reached. Exiting event stream.")
+                        break
+
+                    while True:
+                        try:
+                            msg = message_queue.get(timeout=queue_timeout, block=True)
+                            yield msg
+                        except Empty:
+                            logger.debug(
+                                f"Heartbeat: no message in last {queue_timeout} seconds"
+                            )
+                            break
+            except KeyboardInterrupt:
+                logger.info("Received keyboard interrupt, disconnecting...")
+
+            except Exception as e:
+                logger.exception(f"Polling error: {e}")
+
+        finally:
+            if client_id:
+                try:
+                    logger.trace(
+                        f"Disconnecting from server with client ID: {client_id}"
+                    )
+                    disconnect_payload = json.dumps(
+                        [
+                            {
+                                "channel": "/meta/disconnect",
+                                "clientId": client_id,
+                                "id": str(self._msg_count + 1),
+                            }
+                        ]
+                    )
+                    conn.request(
+                        "POST",
+                        f"/cometd/{_API_VERSION}/meta/disconnect",
+                        headers=headers,
+                        body=disconnect_payload,
+                    )
+                    response = conn.getresponse()
+                    self._http_resp_header_logic(response)
+                    _ = response.read()
+                    logger.trace("Disconnected successfully.")
+                except Exception as e:
+                    logger.warning(f"Exception during disconnect: {e}")
+            if conn:
+                logger.trace("Closing connection.")
+                conn.close()
+
+            logger.trace("Leaving event polling loop.")

{sfq-0.0.10 → sfq-0.0.12}/uv.lock

@@ -3,5 +3,5 @@ requires-python = ">=3.9"
 
 [[package]]
 name = "sfq"
-version = "0.0.10"
+version = "0.0.12"
 source = { editable = "." }