zscaler-sdk-python 1.7.9__tar.gz → 1.8.1__tar.gz

{zscaler_sdk_python-1.7.9 → zscaler_sdk_python-1.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zscaler-sdk-python
-Version: 1.7.9
+Version: 1.8.1
 Summary: Official Python SDK for the Zscaler Products
 Home-page: https://github.com/zscaler/zscaler-sdk-python
 License: MIT

{zscaler_sdk_python-1.7.9 → zscaler_sdk_python-1.8.1}/pyproject.toml

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

{zscaler_sdk_python-1.7.9 → zscaler_sdk_python-1.8.1}/zscaler/__init__.py

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

{zscaler_sdk_python-1.7.9 → zscaler_sdk_python-1.8.1}/zscaler/errors/zscaler_api_error.py

@@ -23,7 +23,16 @@ class ZscalerAPIError(Exception):
         if self.error_message:
             message_parts.append(self.error_message)
         if self.params:
-            message_parts.append(f"Parameters: {', '.join(self.params)}")
+            # Handle mixed types in params (lists and strings) safely
+            param_strings = []
+            for param in self.params:
+                if isinstance(param, list):
+                    # Flatten lists and join with commas
+                    param_strings.append(', '.join(str(item) for item in param))
+                else:
+                    # Convert non-list items to strings
+                    param_strings.append(str(param))
+            message_parts.append(f"Parameters: {', '.join(param_strings)}")
 
         self.message = " ".join(message_parts)
         super().__init__(self.message)  # ✅ This is what makes it raise-able

{zscaler_sdk_python-1.7.9 → zscaler_sdk_python-1.8.1}/zscaler/helpers.py

@@ -314,3 +314,36 @@ def convert_keys_to_camel_case(data):
         return [convert_keys_to_camel_case(item) for item in data]
     else:
         return data
+
+
+def convert_keys_to_camel_case_selective(data, preserve_snake_case_keys=None):
+    """
+    Recursively convert keys to camelCase while preserving specific snake_case keys.
+    This function allows users to use snake_case for all attributes, and only converts
+    to camelCase if the attribute is NOT in the preserve_snake_case_keys set.
+    
+    Args:
+        data: Dictionary or list to convert
+        preserve_snake_case_keys: Set of keys that should remain in snake_case
+    
+    Returns:
+        Converted data with selective key preservation
+    """
+    if preserve_snake_case_keys is None:
+        preserve_snake_case_keys = set()
+    
+    if isinstance(data, dict):
+        result = {}
+        for k, v in data.items():
+            # Check if this key should be preserved in snake_case
+            if k in preserve_snake_case_keys:
+                # Keep as snake_case
+                result[k] = convert_keys_to_camel_case_selective(v, preserve_snake_case_keys)
+            else:
+                # Convert to camelCase
+                result[to_lower_camel_case(k)] = convert_keys_to_camel_case_selective(v, preserve_snake_case_keys)
+        return result
+    elif isinstance(data, list):
+        return [convert_keys_to_camel_case_selective(item, preserve_snake_case_keys) for item in data]
+    else:
+        return data

{zscaler_sdk_python-1.7.9 → zscaler_sdk_python-1.8.1}/zscaler/oneapi_response.py

@@ -66,9 +66,6 @@ class ZscalerAPIResponse:
         if end_time:
             self._params["endTime"] = end_time
 
-        # If service is ZPA and user did not specify a pagesize, set it to max=500 by default
-        if self._service_type.upper() == "ZPA" and "pagesize" not in self._params:
-            self._params["pagesize"] = self.SERVICE_PAGE_LIMITS["ZPA"]["max"]
 
         # If service is ZIA, ensure the pagination parameter is "pageSize" in camelCase
         if self._service_type == "zia":

{zscaler_sdk_python-1.7.9 → zscaler_sdk_python-1.8.1}/zscaler/request_executor.py

@@ -119,6 +119,10 @@ class RequestExecutor:
 
         exceptions.raise_exception = self._config["client"].get("raiseException", False)
         self._custom_headers = {}
+        
+        # Track whether any mutations (POST/PUT/DELETE) have occurred during this session
+        # This is used to determine if deauthentication is needed for ZIA/ZTW services
+        self._mutations_occurred = False
 
     def get_base_url(self, endpoint: str) -> str:
         """
@@ -302,6 +306,14 @@ class RequestExecutor:
         if "/zdx/" in endpoint:
             return body  # Do not convert ZDX requests to camelCase
 
+        # Special handling for ZCC service - use selective conversion
+        if "/zcc/" in endpoint and body:
+            from zscaler.helpers import convert_keys_to_camel_case_selective
+            from zscaler.zcc.models.webpolicy import WebPolicy
+            # Use the WebPolicy's snake_case keys for selective conversion
+            body = convert_keys_to_camel_case_selective(body, WebPolicy.SNAKE_CASE_KEYS)
+            return body
+
         # Preserve existing logic for other services
         if body:
             body = convert_keys_to_camel_case(body)
@@ -513,6 +525,13 @@ class RequestExecutor:
             logger.warning("Request Timeout exceeded.")
             return None, None, None, Exception("Request Timeout exceeded.")
 
+        # Track mutations (POST/PUT/DELETE) for ZIA/ZTW deauthentication logic
+        if request["method"].upper() in ["POST", "PUT", "DELETE"]:
+            self._mutations_occurred = True
+            logger.debug(f"Mutation detected: {request['method']} request to {request['url']}")
+        else:
+            logger.debug(f"Non-mutation request: {request['method']} request to {request['url']} (mutations_occurred={self._mutations_occurred})")
+
         # Perform the actual HTTP request
         response, error = self._http_client.send_request(request)
 
@@ -632,11 +651,23 @@ class RequestExecutor:
         logger.debug("Getting custom headers.")
         return self._custom_headers
 
+    def has_mutations_occurred(self):
+        """
+        Check if any mutations (POST/PUT/DELETE) have occurred during this session.
+        
+        Returns:
+            bool: True if mutations occurred, False otherwise.
+        """
+        return self._mutations_occurred
+
     def deauthenticate(self, service_type=None):
         """
         Deauthenticate from Zscaler services that support session-based authentication.
         Currently supports ZIA and ZTW services.
         
+        For ZIA service, deauthentication is only performed if mutations (POST/PUT/DELETE) 
+        have occurred during the session. GET-only sessions do not require deauthentication.
+        
         Args:
             service_type (str, optional): The service type to deauthenticate from.
                 If None, will attempt to determine from the current configuration.
@@ -648,6 +679,11 @@ class RequestExecutor:
             logger.debug(f"Deauthentication not supported for service: {service_type}")
             return False
         
+        # For ZIA service, only deauthenticate if mutations occurred
+        if service_type.lower() == "zia" and not self._mutations_occurred:
+            logger.debug("ZIA service: No mutations occurred during session, skipping deauthentication")
+            return True
+        
         try:
             # Determine the base URL and endpoint based on service type
             if service_type.lower() == "zia":

{zscaler_sdk_python-1.7.9 → zscaler_sdk_python-1.8.1}/zscaler/utils.py

@@ -819,6 +819,60 @@ def format_url(base_string):
 
 #     return wrapper
 
+def validate_and_format_date(date_str: str) -> str:
+    """
+    Validates and formats date string for ZCC API.
+    Accepts various date formats and returns ZCC API format (YYYY-MM-DD HH:MM:SS GMT).
+    
+    Args:
+        date_str (str): Date string in various formats
+        
+    Returns:
+        str: Date in ZCC API format (YYYY-MM-DD HH:MM:SS GMT)
+        
+    Raises:
+        ValueError: If date format is invalid
+    """
+    if not date_str:
+        raise ValueError("Date string cannot be empty")
+    
+    try:
+        # Try to parse the date string
+        parsed_date = parser.parse(date_str)
+        
+        # If no timezone info, assume UTC
+        if parsed_date.tzinfo is None:
+            parsed_date = pytz.UTC.localize(parsed_date)
+        
+        # Convert to ZCC API format: YYYY-MM-DD HH:MM:SS GMT
+        return parsed_date.strftime("%Y-%m-%d %H:%M:%S GMT")
+    except (ValueError, TypeError) as e:
+        raise ValueError(f"Invalid date format: {date_str}. Expected formats: YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS, etc. Error: {e}")
+
+
+def validate_time_zone(time_zone_str: str) -> str:
+    """
+    Validates time zone string against IANA Time Zone database.
+    
+    Args:
+        time_zone_str (str): IANA time zone string
+        
+    Returns:
+        str: Validated time zone string
+        
+    Raises:
+        ValueError: If time zone is invalid
+    """
+    if not time_zone_str:
+        raise ValueError("Time zone cannot be empty")
+    
+    # Check if it's a valid IANA time zone
+    if time_zone_str not in pytz.all_timezones:
+        raise ValueError(f"Invalid time zone: {time_zone_str}. Please use a valid IANA time zone (e.g., 'America/New_York', 'UTC', 'Europe/London')")
+    
+    return time_zone_str
+
+
 def zcc_param_mapper(func):
     @wraps(func)
     def wrapper(self, *args, **kwargs):
@@ -873,10 +927,54 @@ def zcc_param_mapper(func):
             else:
                 mapped_params["registrationTypes"] = ",".join(mapped)
 
+        # Handle date parameters
+        start_date = (
+            query_params.get("start_date") or
+            query_params.get("startDate") or
+            body.get("start_date") or
+            body.get("startDate")
+        )
+        
+        if start_date:
+            try:
+                mapped_params["startDate"] = validate_and_format_date(start_date)
+            except ValueError as e:
+                raise ValueError(f"Invalid start_date: {e}")
+        
+        end_date = (
+            query_params.get("end_date") or
+            query_params.get("endDate") or
+            body.get("end_date") or
+            body.get("endDate")
+        )
+        
+        if end_date:
+            try:
+                mapped_params["endDate"] = validate_and_format_date(end_date)
+            except ValueError as e:
+                raise ValueError(f"Invalid end_date: {e}")
+        
+        # Handle time zone parameter
+        time_zone = (
+            query_params.get("time_zone") or
+            query_params.get("Time-Zone") or
+            body.get("time_zone") or
+            body.get("Time-Zone")
+        )
+        
+        if time_zone:
+            try:
+                mapped_params["Time-Zone"] = validate_time_zone(time_zone)
+            except ValueError as e:
+                raise ValueError(f"Invalid time_zone: {e}")
+
         # Clean aliases
         for key in [
             "os_type", "os_types",
             "registration_type", "registration_types",
+            "start_date", "startDate",
+            "end_date", "endDate", 
+            "time_zone", "Time-Zone",
         ]:
             query_params.pop(key, None)
             kwargs.pop(key, None)

{zscaler_sdk_python-1.7.9 → zscaler_sdk_python-1.8.1}/zscaler/zcc/devices.py

@@ -209,6 +209,104 @@ class DevicesAPI(APIClient):
 
         return filename
 
+    @zcc_param_mapper
+    def download_disable_reasons(self, query_params=None, filename: str = None):
+        """
+        Downloads or exports a report as a CSV file showing the disable reasons of devices.
+
+        Args:
+            query_params (dict, optional): A dictionary containing supported filters.
+
+                ``[query_params.os_types]`` {list}: Filter by OS type. Valid values:
+                    ios, android, windows, macos, linux.
+
+                ``[query_params.start_date]`` {str}: Start date for the report. Accepts various formats:
+                    YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS, etc. Will be converted to ZCC API format.
+
+                ``[query_params.end_date]`` {str}: End date for the report. Accepts various formats:
+                    YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, YYYY-MM-DDTHH:MM:SS, etc. Will be converted to ZCC API format.
+
+                ``[query_params.time_zone]`` {str}: IANA time zone for date interpretation. 
+                    Examples: 'America/New_York', 'UTC', 'Europe/London'.
+
+            filename (str, optional): Custom filename for the CSV file. Defaults to timestamped name.
+
+        Returns:
+            str: Path to the downloaded CSV file.
+
+        Examples:
+            Download disable reasons report for Windows devices:
+
+            >>> try:
+            ...     filename = client.zcc.devices.download_disable_reasons(
+            ...         query_params={
+            ...             "os_types": ["windows"],
+            ...             "start_date": "2024-01-01",
+            ...             "end_date": "2024-01-31",
+            ...             "time_zone": "America/New_York"
+            ...         },
+            ...         filename="disable_reasons_jan2024.csv"
+            ...     )
+            ...     print(f"Disable reasons report downloaded successfully: {filename}")
+            ... except Exception as e:
+            ...     print(f"Error during download: {e}")
+
+            Download disable reasons for all devices with specific date range:
+
+            >>> try:
+            ...     filename = client.zcc.devices.download_disable_reasons(
+            ...         query_params={
+            ...             "start_date": "2024-01-01 00:00:00",
+            ...             "end_date": "2024-01-31 23:59:59",
+            ...             "time_zone": "UTC"
+            ...         }
+            ...     )
+            ...     print(f"Report downloaded: {filename}")
+            ... except Exception as e:
+            ...     print(f"Error: {e}")
+        """
+        query_params = query_params or {}
+
+        if not filename:
+            filename = f"zcc-disable-reasons-{datetime.now().strftime('%Y%m%d-%H_%M_%S')}.csv"
+
+        # The zcc_param_mapper decorator handles parameter mapping and validation
+        # We just need to pass the query_params through
+        params = query_params.copy()
+
+        http_method = "get".upper()
+        api_url = format_url(f"{self._zcc_base_endpoint}/downloadDisableReasons")
+
+        # Prepare headers - include Time-Zone if provided
+        headers = {"Accept": "*/*"}
+        if "Time-Zone" in params:
+            headers["Time-Zone"] = params.pop("Time-Zone")
+
+        request, error = self._request_executor.create_request(
+            http_method,
+            api_url,
+            params=params,
+            headers=headers
+        )
+
+        if error:
+            raise Exception("Error creating request for downloading disable reasons report.")
+
+        response, error = self._request_executor.execute(request, return_raw_response=True)
+        if error:
+            raise error
+        if response is None:
+            raise Exception("No response received when downloading disable reasons report.")
+
+        content_type = response.headers.get("Content-Type", "").lower()
+        if not content_type.startswith("application/octet-stream") and not response.text.startswith('"User","Device type"'):
+            raise Exception("Invalid response content type or unexpected response format.")
+
+        with open(filename, "wb") as f:
+            f.write(response.content)
+
+        return filename
+
     @zcc_param_mapper
     def list_devices(self, query_params=None) -> tuple:
         """
@@ -624,3 +722,4 @@ class DevicesAPI(APIClient):
             return None, response, error
 
         return result, response, None
+