zscaler-sdk-python 1.1.0__tar.gz → 1.2.0__tar.gz

{zscaler_sdk_python-1.1.0 → zscaler_sdk_python-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zscaler-sdk-python
-Version: 1.1.0
+Version: 1.2.0
 Summary: Official Python SDK for the Zscaler Products
 Home-page: https://github.com/zscaler/zscaler-sdk-python
 License: MIT
@@ -620,6 +620,29 @@ You should now see logs in your console. Notice that API Credentials i.e `client
 
 What it being logged? `requests`, `responses`, `http errors`, `caching responses`.
 
+### Using Your Own Logger (Optional)
+If your script defines its own logging configuration (e.g., for file or custom formatting), the SDK will not interfere with it. You can continue using your own logger like this:
+
+```py
+import logging
+
+my_logger = logging.getLogger("my_app_logger")
+my_logger.setLevel(logging.INFO)
+handler = logging.StreamHandler()
+handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
+my_logger.addHandler(handler)
+
+my_logger.info("This is your app-level log, independent from the SDK.")
+```
+
+To control SDK logging separately, use:
+
+```py
+logging.getLogger("zscaler-sdk-python").setLevel(logging.WARNING)  # or .ERROR to silence SDK logs
+```
+
+The SDK will never globally disable logging or interfere with your existing logging configuration.
+
 ## Configuration reference
 
 This library looks for configuration in the following sources:

{zscaler_sdk_python-1.1.0 → zscaler_sdk_python-1.2.0}/README.md

@@ -581,6 +581,29 @@ You should now see logs in your console. Notice that API Credentials i.e `client
 
 What it being logged? `requests`, `responses`, `http errors`, `caching responses`.
 
+### Using Your Own Logger (Optional)
+If your script defines its own logging configuration (e.g., for file or custom formatting), the SDK will not interfere with it. You can continue using your own logger like this:
+
+```py
+import logging
+
+my_logger = logging.getLogger("my_app_logger")
+my_logger.setLevel(logging.INFO)
+handler = logging.StreamHandler()
+handler.setFormatter(logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s"))
+my_logger.addHandler(handler)
+
+my_logger.info("This is your app-level log, independent from the SDK.")
+```
+
+To control SDK logging separately, use:
+
+```py
+logging.getLogger("zscaler-sdk-python").setLevel(logging.WARNING)  # or .ERROR to silence SDK logs
+```
+
+The SDK will never globally disable logging or interfere with your existing logging configuration.
+
 ## Configuration reference
 
 This library looks for configuration in the following sources:

{zscaler_sdk_python-1.1.0 → zscaler_sdk_python-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zscaler-sdk-python"
-version = "1.1.0"
+version = "1.2.0"
 description = "Official Python SDK for the Zscaler Products"
 authors = ["Zscaler, Inc. <devrel@zscaler.com>"]
 license = "MIT"

{zscaler_sdk_python-1.1.0 → zscaler_sdk_python-1.2.0}/zscaler/__init__.py

@@ -29,7 +29,7 @@ __license__ = "MIT"
 __contributors__ = [
     "William Guilherme",
 ]
-__version__ = "1.1.0"
+__version__ = "1.2.0"
 
 
 from zscaler.oneapi_client import Client as ZscalerClient  # noqa

{zscaler_sdk_python-1.1.0 → zscaler_sdk_python-1.2.0}/zscaler/constants.py

@@ -15,7 +15,7 @@ ZPA_BASE_URLS = {
 DEV_AUTH_URL = "https://authn1.dev.zpath.net/authn/v1/oauth/token"
 
 
-RETRYABLE_STATUS_CODES = {409, 412, 429, 500, 502, 503, 504}
+RETRYABLE_STATUS_CODES = {408, 409, 412, 429, 500, 502, 503, 504}
 MAX_RETRIES = 5
 BACKOFF_FACTOR = 1
 BACKOFF_BASE_DURATION = 2

zscaler_sdk_python-1.2.0/zscaler/errors/zscaler_api_error.py

@@ -0,0 +1,55 @@
+from zscaler.errors.error import Error
+import json
+
+
+class ZscalerAPIError(Error):
+    def __init__(self, url, response_details, response_body, service_type=""):
+        self.status_code = response_details.status_code
+        self.url = url
+        self.headers = response_details.headers
+        self.stack = ""
+        self.service_type = service_type.lower()
+
+        # Ensure response_body is a dict
+        if not isinstance(response_body, dict):
+            response_body = {"message": str(response_body)}
+
+        # Initialize fields
+        self.error_code = None
+        self.error_message = None
+        self.params = None
+        self.path = None
+
+        # Populate based on service type
+        if self.service_type == "zpa":
+            self.error_code = response_body.get("id")
+            self.error_message = response_body.get("reason")
+            self.params = response_body.get("params")
+        else:  # default to ZIA/others
+            self.error_code = response_body.get("code") or response_body.get("id")
+            self.error_message = response_body.get("message") or response_body.get("reason")
+
+        self.params = self.params or []
+        self.path = response_body.get("path")
+
+        # Construct message string
+        message_parts = [f"HTTP {self.status_code}"]
+        if self.error_code:
+            message_parts.append(self.error_code)
+        if self.error_message:
+            message_parts.append(self.error_message)
+        if self.params:
+            message_parts.append(f"Parameters: {', '.join(self.params)}")
+
+        self.message = " ".join(message_parts)
+
+    def __str__(self):
+        error_payload = {"status": self.status_code, "code": self.error_code, "message": self.error_message, "url": self.url}
+        if self.params:
+            error_payload["params"] = self.params
+        if self.path:
+            error_payload["path"] = self.path
+        return json.dumps(error_payload, indent=2)
+
+    def __repr__(self):
+        return self.__str__()

{zscaler_sdk_python-1.1.0 → zscaler_sdk_python-1.2.0}/zscaler/exceptions/exceptions.py

@@ -21,10 +21,12 @@ class HTTPException(ZscalerBaseException):
 
 
 class ZscalerAPIException(ZscalerBaseException):
-    pass
+    def __init__(self, error):
+        # error is a ZscalerAPIError
+        super().__init__(error.url, error, error.message)
 
 
-# Zscaler Private Access specific exceptions (Potential Future Use)
+# Other exceptions (unchanged)
 class ZpaBaseException(Exception):
     pass
 
@@ -34,26 +36,18 @@ class ZpaAPIException(ZpaBaseException):
 
 
 class RateLimitExceededError(Exception):
-    """Raised when the API rate limit is exceeded."""
-
     pass
 
 
 class RetryLimitExceededError(Exception):
-    """Raised when the maximum number of retries is exceeded."""
-
     pass
 
 
 class CacheError(Exception):
-    """Raised for errors related to caching operations."""
-
     pass
 
 
 class BadRequestError(Exception):
-    """Raised when the API responds with a 400 status code."""
-
     pass
 
 
@@ -70,32 +64,22 @@ class NotFoundError(Exception):
 
 
 class APIClientError(Exception):
-    """General exception related to the API client operations."""
-
     pass
 
 
 class InvalidCloudEnvironmentError(Exception):
-    """Raised when an unrecognized cloud environment is specified."""
-
     def __init__(self, cloud: str):
         self.cloud = cloud
         super().__init__(f"Unrecognized cloud environment: {self.cloud}")
 
 
 class TokenExpirationError(Exception):
-    """Raised when the authentication token has expired."""
-
     pass
 
 
 class TokenRefreshError(Exception):
-    """Raised when there's an issue refreshing the authentication token."""
-
     pass
 
 
 class HeaderUpdateError(Exception):
-    """Raised if there's a problem updating the session headers."""
-
     pass

zscaler_sdk_python-1.2.0/zscaler/logger.py

@@ -0,0 +1,181 @@
+import logging
+import json as jsonp
+import os
+import time
+from urllib.parse import urlencode
+from http.client import HTTPConnection
+
+LOG_FORMAT = "%(asctime)s - %(name)s - %(module)s - %(levelname)s - %(message)s"
+
+
+# def setup_logging(logger_name="zscaler-sdk-python", enabled=None, verbose=None):
+#     """
+#     Set up logging with specified level and logger name.
+#     Log level is controlled via ZSCALER_SDK_VERBOSE environment variable.
+#     Logging can be enabled/disabled via ZSCALER_SDK_LOG environment variable.
+
+#     Parameters:
+#     - logger_name (str, optional): Logger name. Defaults to "zscaler-sdk-python".
+#     - enabled (bool, optional): Enable logging. Defaults to None, which uses the environment variable.
+#     - verbose (bool, optional): Set verbose logging. Defaults to None, which uses the environment variable.
+#     """
+#     if enabled is None:
+#         enabled = os.getenv("ZSCALER_SDK_LOG", "false").lower() == "true"
+
+#     # if not enabled:
+#     #     # If logging is not enabled, set up a null handler
+#     #     logging.disable(logging.INFO)
+#     #     return
+
+#     if not enabled:
+#         # Do not globally disable logging
+#         # Just keep the SDK logger silent
+#         sdk_logger = logging.getLogger(logger_name)
+#         sdk_logger.addHandler(logging.NullHandler())
+#         return
+
+#     if verbose is None:
+#         verbose = os.getenv("ZSCALER_SDK_VERBOSE", "false").lower() == "true"
+
+#     log_level = logging.DEBUG if verbose else logging.INFO
+#     HTTPConnection.debuglevel = 0
+#     # Create a logger with the specified name
+#     logger = logging.getLogger(logger_name)
+#     default_logger = logging.getLogger()
+
+#     # If the logger already has handlers, remove them to avoid duplicate logging
+#     for handler in logger.handlers[:]:
+#         logger.removeHandler(handler)
+
+#     for handler in default_logger.handlers[:]:
+#         default_logger.removeHandler(handler)
+
+#     # Set log level
+#     logger.setLevel(log_level)
+#     default_logger.setLevel(log_level)
+#     logging.basicConfig(level=log_level)
+#     # Create a stream handler with the specified level and formatter
+#     stream_handler = logging.StreamHandler()
+#     stream_handler.setLevel(log_level)
+#     log_formatter = logging.Formatter(LOG_FORMAT)
+#     stream_handler.setFormatter(log_formatter)
+
+#     # Add the handler to the logger
+#     logger.addHandler(stream_handler)
+
+
+#     # Option: Add FileHandler if you want logs to be written to a file.
+#     if os.getenv("LOG_TO_FILE", "false").lower() == "true":
+#         file_handler = logging.FileHandler(os.getenv("LOG_FILE_PATH", "sdk.log"))
+#         file_handler.setLevel(log_level)
+#         file_handler.setFormatter(log_formatter)
+#         logger.addHandler(file_handler)
+def setup_logging(logger_name="zscaler-sdk-python", enabled=None, verbose=None):
+    """
+    Set up logging for the Zscaler SDK.
+
+    Logging behavior can be controlled via environment variables or config:
+
+    Environment Variables:
+        ZSCALER_SDK_LOG (true/false): Enable or disable SDK logging.
+        ZSCALER_SDK_VERBOSE (true/false): Enable verbose (DEBUG) logging.
+        LOG_TO_FILE (true/false): Enable file-based logging.
+        LOG_FILE_PATH: File path for logs (default: sdk.log)
+
+    Parameters:
+        logger_name (str): Name of the logger. Defaults to "zscaler-sdk-python".
+        enabled (bool): Enable logging. If None, reads from env.
+        verbose (bool): Enable DEBUG-level logging. If None, reads from env.
+    """
+    if enabled is None:
+        enabled = os.getenv("ZSCALER_SDK_LOG", "false").lower() == "true"
+
+    if not enabled:
+        # Do NOT disable global logging.
+        # Just suppress SDK logs quietly with a NullHandler.
+        logging.getLogger(logger_name).addHandler(logging.NullHandler())
+        return
+
+    if verbose is None:
+        verbose = os.getenv("ZSCALER_SDK_VERBOSE", "false").lower() == "true"
+
+    log_level = logging.DEBUG if verbose else logging.INFO
+    HTTPConnection.debuglevel = 0  # Optional: Enable HTTP debug logging
+
+    # SDK logger (isolated)
+    logger = logging.getLogger(logger_name)
+    logger.setLevel(log_level)
+
+    # Clean up any duplicate handlers
+    if not logger.handlers:
+        stream_handler = logging.StreamHandler()
+        stream_handler.setLevel(log_level)
+        stream_handler.setFormatter(logging.Formatter(LOG_FORMAT))
+        logger.addHandler(stream_handler)
+
+        # Optional file logging
+        if os.getenv("LOG_TO_FILE", "false").lower() == "true":
+            file_handler = logging.FileHandler(os.getenv("LOG_FILE_PATH", "sdk.log"))
+            file_handler.setLevel(log_level)
+            file_handler.setFormatter(logging.Formatter(LOG_FORMAT))
+            logger.addHandler(file_handler)
+
+
+def dump_request(logger, url: str, method: str, json, params, headers, request_uuid: str, body=True):
+    request_headers_filtered = {key: value for key, value in headers.items() if key != "Authorization"}
+    # Log the request details before sending the request
+    log_lines = []
+    request_body = ""
+    if body:
+        request_body = jsonp.dumps(json)
+    log_lines.append(f"\n---[ ZSCALER SDK REQUEST | ID:{request_uuid} ]-------------------------------")
+    full_url = url
+    if params:
+        full_url += "?" + urlencode(params)
+    log_lines.append(f"{method} {full_url}")
+    for key, value in request_headers_filtered.items():
+        log_lines.append(f"{key}: {value}")
+    if body and request_body != "" and request_body != "null":
+        log_lines.append(f"\n{request_body}")
+    log_lines.append("--------------------------------------------------------------------")
+    logger.info("\n".join(log_lines))
+
+
+def dump_response(
+    logger,
+    url: str,
+    method: str,
+    resp,
+    params,
+    request_uuid: str,
+    start_time,
+    from_cache: bool = None,
+):
+    # Calculate the duration in seconds
+    end_time = time.time()
+    duration_seconds = end_time - start_time
+    # Convert the duration to milliseconds
+    duration_ms = duration_seconds * 1000
+    # Convert the headers to a regular dictionary
+    response_headers_dict = dict(resp.headers)
+    full_url = url
+    if params:
+        full_url += "?" + urlencode(params)
+    log_lines = []
+
+    if from_cache:
+        log_lines.append(
+            f"\n---[ ZSCALER SDK RESPONSE | ID:{request_uuid} | " f"FROM CACHE | DURATION:{duration_ms}ms ]" + "-" * 31
+        )
+    else:
+        log_lines.append(f"\n---[ ZSCALER SDK RESPONSE | ID:{request_uuid} | " f"DURATION:{duration_ms}ms ]" + "-" * 46)
+    log_lines.append(f"{method} {full_url}")
+    for key, value in response_headers_dict.items():
+        log_lines.append(f"{key}: {value}")
+    response_body = ""
+    if resp.text:
+        response_body = resp.text
+    if response_body and response_body != "" and response_body != "null":
+        log_lines.append(f"\n{response_body}")
+    log_lines.append("-" * 68)
+    logger.info("\n".join(log_lines))

{zscaler_sdk_python-1.1.0 → zscaler_sdk_python-1.2.0}/zscaler/oneapi_http_client.py

@@ -286,7 +286,7 @@ class HTTPClient:
                 )
 
             else:
-                # Use Standard Session
+                # Standard session
                 if self._session:
                     logger.debug("Request with re-usable session.")
                     response = self._session.request(**params)
@@ -294,11 +294,9 @@ class HTTPClient:
                     logger.debug("Request without re-usable session.")
                     response = requests.request(**params)
 
-            if response is None or not hasattr(response, "status_code"):
-                # If we truly got no response (should be rare unless network error)
-                error_msg = "Request execution failed. Response is None."
-                logger.error(error_msg)
-                return (None, ValueError(error_msg))
+            if response is None:
+                logger.error("Request execution failed. Response is None.")
+                return (None, ValueError("No response received."))
 
             dump_request(
                 logger,
@@ -324,7 +322,7 @@ class HTTPClient:
                 request["uuid"],
                 start_time,
             )
-            # Return (response, None) regardless of status code (including 429)
+            # Return response and None even for 4xx/5xx – let check_response_for_error() decide
             return (response, None)
 
         except (requests.RequestException, requests.Timeout) as error:
@@ -334,7 +332,7 @@ class HTTPClient:
 
         except Exception as error:
             # Unexpected errors
-            logger.error(f"Unexpected error during request execution: {error}")
+            # logger.error(f"Unexpected error during request execution: {error}")
             return (None, error)
 
     @staticmethod
@@ -345,47 +343,43 @@ class HTTPClient:
         Args:
             url (str): URL of the response
             response_details (requests.Response): Response object with details
-            response_body (str): Response body in JSON format
+            response_body (str): Response body in JSON or plain string
 
         Returns:
-            Tuple(dict repr of response (if no error), any error found)
+            Tuple(dict or None, error or None)
         """
-        # Check if response is JSON and parse it
-        if "application/json" in response_details.headers.get("Content-Type", ""):
-            try:
-                formatted_response = json.loads(response_body)
-                # logger.debug("Successfully parsed JSON response")
-            except json.JSONDecodeError as e:
-                logger.error(f"Failed to parse JSON response: {e}")
-                return None, e
-        else:
-            formatted_response = response_body
-
-        if 200 <= response_details.status_code < 300:
-            return formatted_response, None
+        content_type = response_details.headers.get("Content-Type", "")
+        is_json = "application/json" in content_type
 
-        logger.error(f"Error response from {url}: {response_details.status_code} - {formatted_response}")
+        # Attempt to parse JSON safely
+        try:
+            formatted_response = json.loads(response_body) if is_json else response_body
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse JSON response: {e}")
+            if HTTPClient.raise_exception:
+                raise HTTPException(f"Invalid JSON response from {url}: {response_body}")
+            return None, HTTPError(url, response_details, response_body)
 
         status_code = response_details.status_code
 
-        # check if call was succesful
-        if 200 <= status_code <= 299:
-            return (formatted_response, None)
-        else:
-            # create errors
-            try:
-                error = ZscalerAPIError(url, response_details, formatted_response)
-                if HTTPClient.raise_exception:
-                    raise ZscalerAPIException(formatted_response)
-            except ZscalerAPIException:
-                raise
-            except Exception:
-                error = HTTPError(url, response_details, formatted_response)
-                if HTTPClient.raise_exception:
-                    logger.exception(formatted_response)
-                    raise HTTPException(formatted_response)
-            logger.error(error)
-            return (None, error)
+        if 200 <= status_code < 300:
+            return formatted_response, None
+
+        # Defensive error handling block (minimal, correct)
+        try:
+            error = ZscalerAPIError(url, response_details, formatted_response)
+            # logger.debug(f"Raw API Error JSON: {json.dumps(formatted_response, indent=2)}")
+            if HTTPClient.raise_exception:
+                raise ZscalerAPIException(error)
+            return None, error
+
+        except Exception as e:
+            # Catch-all in case ZscalerAPIError constructor fails
+            logger.exception("Failed to construct ZscalerAPIError.")
+            generic_error = HTTPError(url, response_details, formatted_response)
+            if HTTPClient.raise_exception:
+                raise HTTPException(str(generic_error)) from e
+            return None, generic_error
 
     @staticmethod
     def format_binary_data(data):

{zscaler_sdk_python-1.1.0 → zscaler_sdk_python-1.2.0}/zscaler/request_executor.py

@@ -20,7 +20,7 @@ logger = logging.getLogger(__name__)
 
 class RequestExecutor:
     """
-    This class handles all of the requests sent by the Zscaler SDK Client (ZIA, ZPA, ZCC, ZDX, ZWA etc.).
+    This class handles all of the requests sent by the Zscaler SDK Client (ZIA, ZPA, ZCC, ZDX, ZWA, ZTW).
     """
 
     BASE_URL = "https://api.zsapi.net"  # Default base URL for API calls
@@ -323,16 +323,18 @@ class RequestExecutor:
         """
         try:
             request, response, response_body, error = self.fire_request(request)
+            logger.debug(
+                f"[DEBUG] Got response: {response} (status: {getattr(response, 'status_code', 'N/A')}) | error: {error}"
+            )
         except Exception as ex:
             logger.error(f"Exception during HTTP request: {ex}")
             return None, ex
 
-        if not response:
-            logger.error("Response is None after executing request.")
-            return None, ValueError("Response is None")
+        if response is None and error is None:
+            return None, None  # silently return None without manufacturing errors
 
         if error:
-            logger.error(f"Error during request execution: {error}")
+            # logger.error(f"Error during request execution: {error}")
             return None, error
 
         if response.status_code == 204:
@@ -350,7 +352,7 @@ class RequestExecutor:
             return None, ex
 
         if error:
-            logger.error(f"Error in HTTP response: {error}")
+            # logger.error(f"Error in HTTP response: {error}")
             return None, error
 
         logger.debug(f"Successful response from {request['url']}")
@@ -466,8 +468,8 @@ class RequestExecutor:
         response, error = self._http_client.send_request(request)
 
         if error:
-            logger.error(f"Error sending request: {error}")
-            return None, None, None, error
+            # logger.error(f"Error sending request: {error}")
+            return request, response, response.text if response else None, error
 
         headers = response.headers
 
@@ -486,10 +488,14 @@ class RequestExecutor:
         """
         Checks if HTTP status is retryable.
 
-        Retryable statuses: 429, 503, 504
+        Retryable statuses: 408, 409, 412, 429, 500, 502, 503, 504
         """
         return status is not None and status in (
+            HTTPStatus.REQUEST_TIMEOUT,
+            HTTPStatus.CONFLICT,
+            HTTPStatus.PRECONDITION_FAILED,
             HTTPStatus.TOO_MANY_REQUESTS,
+            HTTPStatus.INTERNAL_SERVER_ERROR,
             HTTPStatus.SERVICE_UNAVAILABLE,
             HTTPStatus.GATEWAY_TIMEOUT,
         )

{zscaler_sdk_python-1.1.0 → zscaler_sdk_python-1.2.0}/zscaler/utils.py

@@ -675,6 +675,7 @@ def is_valid_ssh_key(private_key: str) -> bool:
     ]
     return any(re.search(pattern, private_key) for pattern in ssh_key_patterns)
 
+
 def validate_and_convert_times(start_time_str, end_time_str, time_zone_str):
     """
     Validates and converts provided time strings to epoch.
@@ -730,6 +731,7 @@ def validate_and_convert_times(start_time_str, end_time_str, time_zone_str):
 
     return start_epoch, end_epoch
 
+
 def convert_dc_exclusion_times(start_time_str, end_time_str, time_zone_str):
     """
     Converts and validates DC exclusion times based on API rules:
@@ -752,6 +754,7 @@ def convert_dc_exclusion_times(start_time_str, end_time_str, time_zone_str):
 
     return start_epoch, end_epoch
 
+
 def convert_date_time_to_seconds(date_time):
     """
     Takes in a date time string and returns the number of seconds