zscaler-sdk-python 1.2.3__tar.gz → 1.3.0__tar.gz

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/PKG-INFO

@@ -1,23 +1,23 @@
 Metadata-Version: 2.1
 Name: zscaler-sdk-python
-Version: 1.2.3
+Version: 1.3.0
 Summary: Official Python SDK for the Zscaler Products
 Home-page: https://github.com/zscaler/zscaler-sdk-python
 License: MIT
 Keywords: zscaler,sdk,zpa,zia,zdx,zcc,ztw,zwa
 Author: Zscaler, Inc.
 Author-email: devrel@zscaler.com
-Requires-Python: >=3.9,<4.0
+Requires-Python: >=3.9.2,<4.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
 Classifier: Topic :: Security
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Provides-Extra: dev

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zscaler-sdk-python"
-version = "1.2.3"
+version = "1.3.0"
 description = "Official Python SDK for the Zscaler Products"
 authors = ["Zscaler, Inc. <devrel@zscaler.com>"]
 license = "MIT"
@@ -28,7 +28,7 @@ packages = [
 "Bug Tracker" = "https://github.com/zscaler/zscaler-sdk-python/issues"
 
 [tool.poetry.dependencies]
-python = ">=3.9,<4.0"
+python = ">=3.9.2,<4.0"
 requests = ">=2.32.3"
 cryptography = ">=43.0.0"
 pyyaml = ">=6.0.0"

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/zscaler/__init__.py

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

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/zscaler/request_executor.py

@@ -14,7 +14,6 @@ from zscaler.zdx.legacy import LegacyZDXClientHelper
 from zscaler.zpa.legacy import LegacyZPAClientHelper
 from zscaler.zia.legacy import LegacyZIAClientHelper
 from zscaler.zwa.legacy import LegacyZWAClientHelper
-# from zscaler.logger import setup_logging  # ✅ Import here
 
 logger = logging.getLogger('zscaler-sdk-python')
 
@@ -463,35 +462,100 @@ class RequestExecutor:
             request_start_time (float): Original start time of request.
 
         Returns:
-            Tuple of request, response object, response body, and error.
+            Tuple of (request, response object, response body, error).
         """
         current_req_start_time = time.time()
         max_retries = self._max_retries
         req_timeout = self._request_timeout
 
+        # Check if total elapsed time exceeds the configured request timeout
         if req_timeout > 0 and (current_req_start_time - request_start_time) > req_timeout:
             logger.warning("Request Timeout exceeded.")
             return None, None, None, Exception("Request Timeout exceeded.")
 
+        # Perform the actual HTTP request
         response, error = self._http_client.send_request(request)
 
+        # If a low-level error occurred (network, request construction, etc.)
         if error:
-            # logger.error(f"Error sending request: {error}")
             return request, response, response.text if response else None, error
 
-        headers = response.headers
+        # Check for 401 -> Trigger re-auth if we still have retries left
+        if response.status_code == 401:
+            # We only want to attempt refreshing the token if we haven't hit max_retries
+            if attempts < max_retries:
+                logger.info("Got 401 response; clearing token and re-authenticating.")
+                self._oauth.clear_access_token()
+
+                try:
+                    fresh_token = self._oauth._get_access_token()
+                except Exception as e:
+                    # If re-auth fails, return immediately
+                    logger.error(f"Token refresh failed after 401: {e}")
+                    return request, response, response.text, e
+
+                # Update the request with the new token
+                request["headers"]["Authorization"] = f"Bearer {fresh_token}"
+                attempts += 1
+                return self.fire_request_helper(request, attempts, request_start_time)
+            else:
+                logger.error("401 Unauthorized - token refresh attempts exhausted.")
+                return request, response, response.text, Exception("401 Unauthorized - token refresh attempts exhausted.")
 
+        # Handle “retryable” statuses such as 429, 503, etc.
         if attempts < max_retries and self.is_retryable_status(response.status_code):
-            backoff_seconds = self.get_retry_after(headers, logger)
+            backoff_seconds = self.get_retry_after(response.headers, logger)
             if backoff_seconds is None:
                 return None, response, response.text, Exception(ERROR_MESSAGE_429_MISSING_DATE_X_RESET)
-            logger.info(f"Hit rate limit. Retrying request in {backoff_seconds} seconds.")
+
+            logger.info(f"Hit rate limit or retryable status {response.status_code}. "
+                        f"Retrying request in {backoff_seconds} seconds.")
             time.sleep(backoff_seconds)
             attempts += 1
             return self.fire_request_helper(request, attempts, request_start_time)
 
+        # If we reach here, no further retries; return whatever we got
         return request, response, response.text, None
 
+    # def fire_request_helper(self, request, attempts, request_start_time):
+    #     """
+    #     Helper method to perform HTTP call with retries if needed.
+
+    #     Args:
+    #         request (dict): HTTP request representation.
+    #         attempts (int): Number of attempted HTTP calls so far.
+    #         request_start_time (float): Original start time of request.
+
+    #     Returns:
+    #         Tuple of request, response object, response body, and error.
+    #     """
+    #     current_req_start_time = time.time()
+    #     max_retries = self._max_retries
+    #     req_timeout = self._request_timeout
+
+    #     if req_timeout > 0 and (current_req_start_time - request_start_time) > req_timeout:
+    #         logger.warning("Request Timeout exceeded.")
+    #         return None, None, None, Exception("Request Timeout exceeded.")
+
+    #     response, error = self._http_client.send_request(request)
+
+    #     if error:
+    #         # logger.error(f"Error sending request: {error}")
+    #         return request, response, response.text if response else None, error
+
+    #     headers = response.headers
+
+    #     if attempts < max_retries and self.is_retryable_status(response.status_code):
+    #         backoff_seconds = self.get_retry_after(headers, logger)
+    #         if backoff_seconds is None:
+    #             return None, response, response.text, Exception(ERROR_MESSAGE_429_MISSING_DATE_X_RESET)
+    #         logger.info(f"Hit rate limit. Retrying request in {backoff_seconds} seconds.")
+    #         time.sleep(backoff_seconds)
+    #         attempts += 1
+    #         return self.fire_request_helper(request, attempts, request_start_time)
+
+    #     return request, response, response.text, None
+
     def is_retryable_status(self, status):
         """
         Checks if HTTP status is retryable.

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/zscaler/utils.py

@@ -207,33 +207,6 @@ def add_id_groups(id_groups: list, kwargs: dict, payload: dict):
             payload[entry[1]] = [{"id": param_id} for param_id in kwargs.pop(entry[0])]
     return
 
-
-#### Working function
-# def transform_common_id_fields(id_groups: list, source_dict: dict, target_dict: dict):
-#     """
-#     For each (key, payload_key) in 'id_groups':
-#       - If 'key' is found in source_dict,
-#       - pop that value,
-#       - insert it into target_dict with name 'payload_key',
-#       - converting each item in the list to { "id": int(item) } if it's a string or int.
-
-#     Additional domain logic can be placed here, e.g. for zpa_app_segments or cbi_profile, etc.
-#     """
-#     for (key, payload_key) in id_groups:
-#         if key in source_dict:
-#             value = source_dict.pop(key)
-#             # Example logic: if it's a list, do the ID transform
-#             if isinstance(value, list):
-#                 target_dict[payload_key] = [
-#                     {"id": int(item)} if isinstance(item, (str, int)) else item
-#                     for item in value
-#                 ]
-#             elif isinstance(value, dict) and "id" in value:
-#                 # single dict with ID
-#                 target_dict[payload_key] = {"id": int(value["id"])}
-#     return
-
-
 def transform_common_id_fields(id_groups: list, source_dict: dict, target_dict: dict):
     """
     For each (key, payload_key) in 'id_groups':
@@ -378,45 +351,6 @@ def pick_version_profile(kwargs: list, payload: list):
         elif version_profile == "new_release":
             payload["versionProfileId"] = 2
 
-
-# class Iterator(APIIterator):
-#     """Iterator class."""
-
-#     page_size = 100
-
-#     def __init__(self, api, path: str = "", **kw):
-#         """Initialize Iterator class."""
-#         super().__init__(api, **kw)
-
-#         self.path = path
-#         self.max_items = kw.pop("max_items", 0)
-#         self.max_pages = kw.pop("max_pages", 0)
-#         self.payload = {}
-#         if kw:
-#             self.payload = {snake_to_camel(key): value for key, value in kw.items()}
-
-#     def _get_page(self) -> None:
-#         """Iterator function to get the page."""
-#         resp = self._api.get(
-#             self.path,
-#             params={**self.payload, "page": self.num_pages + 1},
-#         )
-#         try:
-#             # If we are using ZPA then the API will return records under the
-#             # 'list' key.
-#             self.page = resp.get("list") or []
-#         except AttributeError:
-#             # If the list key doesn't exist then we're likely using ZIA so just
-#             # return the full response.
-#             self.page = resp
-#         finally:
-#             # If we use the default retry-after logic in Restfly then we are
-#             # going to keep seeing 429 messages in stdout. ZIA and ZPA have a
-#             # standard 1 sec rate limit on the API endpoints with pagination so
-#             # we are going to include it here.
-#             time.sleep(1)
-
-
 def calculate_epoch(hours: int):
     current_time = int(time.time())
     past_time = int(current_time - (hours * 3600))
@@ -695,7 +629,7 @@ def validate_and_convert_times(start_time_str, end_time_str, time_zone_str):
     """
     # Validate time zone
     if time_zone_str not in pytz.all_timezones:
-        raise ValueError(f"Invalid time zone: {time_zone_str}")
+        raise ValueError(f"Invalid time zone. Please visit the following site for reference: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones:{time_zone_str}")
 
     # Convert times
     try:

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/zscaler/zcc/devices.py

@@ -38,20 +38,13 @@ class DevicesAPI(APIClient):
         Downloads the list of devices as a CSV file from the ZCC portal.
 
         Args:
-            query_params (dict, optional): A dictionary containing supported filters:
-                ``[query_params.os_types]`` {str}: Filter by device operating system type. Valid options are:
-                    - ios
-                    - android
-                    - windows
-                    - macos
-                    - linux
-                ``[query_params.registration_types]`` {str}: Filter by device operating system type. Valid options are:
-                    - all
-                    - registered
-                    - unregistered
-                    - removal_pending
-                    - removed
-                    - quarantined
+            query_params (dict, optional): A dictionary containing supported filters.
+
+                ``[query_params.os_types]`` {str}: Filter by OS type. Valid values:
+                    ios, android, windows, macos, linux.
+
+                ``[query_params.registration_types]`` {str}: Filter by registration type. Valid values:
+                    all, registered, unregistered, removal_pending, removed, quarantined.
 
             filename (str, optional): Custom filename for the CSV file. Defaults to timestamped name.
 
@@ -73,7 +66,6 @@ class DevicesAPI(APIClient):
             ... except Exception as e:
             ...     print(f"Error during download: {e}")
         """
-
         query_params = query_params or {}
 
         if not filename:
@@ -131,22 +123,13 @@ class DevicesAPI(APIClient):
         Downloads service status for all devices from the ZCC portal.
 
         Args:
-            query_params (dict, optional): A dictionary containing supported filters:
-        Args:
-            query_params (dict, optional): A dictionary containing supported filters:
-                ``[query_params.os_types]`` {str}: Filter by device operating system type. Valid options are:
-                    - ios
-                    - android
-                    - windows
-                    - macos
-                    - linux
-                ``[query_params.registration_types]`` {str}: Filter by device operating system type. Valid options are:
-                    - all
-                    - registered
-                    - unregistered
-                    - removal_pending
-                    - removed
-                    - quarantined
+            query_params (dict, optional): A dictionary containing supported filters.
+
+                ``[query_params.os_types]`` {str}: Filter by OS type. Valid values:
+                    ios, android, windows, macos, linux.
+
+                ``[query_params.registration_types]`` {str}: Filter by registration type. Valid values:
+                    all, registered, unregistered, removal_pending, removed, quarantined.
 
                 filename (str, optional): Custom filename for the CSV file. Defaults to timestamped name.
 
@@ -226,18 +209,17 @@ class DevicesAPI(APIClient):
         Returns the list of devices enrolled in the Client Connector Portal.
 
         Args:
-            query_params {dict}: Map of query parameters for the request.
+            query_params (dict, optional): A dictionary containing supported filters.
 
                 ``[query_params.os_type]`` {str}: Filter by device operating system type. Valid options are:
-                    - ios
-                    - android
-                    - windows
-                    - macos
-                    - linux
-                ``[query_params.username]`` {str}: Filter by enrolled user name for the device.
+                    ios, android, windows, macos, linux.
+
+                ``[query_params.username]`` {str}:  Filter by enrolled username for the device.
 
                 ``[query_params.page]`` {str}: Specifies the page number.
-                ``[query_params.page_size]`` {str}: Specifies the page size. The default page size is 50.
+
+                ``[query_params.page_size]`` {str}: Specifies the page size.
+                    The default page size is 50.
                     The max page size is 5000.
 
         Returns:
@@ -247,7 +229,7 @@ class DevicesAPI(APIClient):
             Prints all devices in the Client Connector Portal to the console:
 
             >>> device_list, _, err = client.zcc.devices.list_devices(
-            ... query_params = { "os_type": "3", 'page': 1, 'page_size': 1})
+            ... query_params = {'username': 'jdoe@acme.com', "os_type": "3", 'page': 1, 'page_size': 1})
             >>> if err:
             ...     print(f"Error listing devices: {err}")
             ...     return
@@ -445,7 +427,9 @@ class DevicesAPI(APIClient):
 
         Args:
             query_params {dict}: Map of query parameters for the request.
-                ``[query_params.page_size]`` {int}: Specifies the page size.  If not provided, the default page size is 30.
+
+                ``[query_params.page_size]`` {int}: Specifies the page size.
+                    If not provided, the default page size is 30.
                     The max page size is 5000.
 
         Returns:
@@ -506,7 +490,9 @@ class DevicesAPI(APIClient):
 
         Args:
             query_params {dict}: Map of query parameters for the request.
-                ``[query_params.page_size]`` {int}: Specifies the page size. If not provided, the default page size is 30.
+
+                ``[query_params.page_size]`` {int}: Specifies the page size.
+                    If not provided, the default page size is 30.
                     The max page size is 5000.
 
         Returns:

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/zscaler/zcc/models/devices.py

@@ -135,14 +135,14 @@ class ForceRemoveDevices(ZscalerObject):
             )
             self.os_type = config["osType"] if "osType" in config else None
             self.udids = ZscalerCollection.form_list(config["udids"] if "udids" in config else [], str)
-            self.user_name = config["userName"] if "userName" in config else None
+            self.username = config["username"] if "username" in config else None
             self.devices_removed = config["devicesRemoved"] if "devicesRemoved" in config else None
             self.error_msg = config["errorMsg"] if "errorMsg" in config else None
         else:
             self.client_connector_version = ZscalerCollection.form_list([], str)
             self.os_type = None
             self.udids = ZscalerCollection.form_list([], str)
-            self.user_name = None
+            self.username = None
             self.devices_removed = None
             self.error_msg = None
 
@@ -155,7 +155,7 @@ class ForceRemoveDevices(ZscalerObject):
             "clientConnectorVersion": self.client_connector_version,
             "osType": self.os_type,
             "udids": self.udids,
-            "userName": self.user_name,
+            "username": self.username,
             "devicesRemoved": self.devices_removed,
             "errorMsg": self.error_msg,
         }

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/zscaler/zcc/secrets.py

@@ -86,10 +86,12 @@ class SecretsAPI(APIClient):
         Return passwords for the specified username and device OS type.
 
         Args:
-            query_params (dict): Optional parameters.
-                - username (str): The username associated with the device.
-                - os_type (str): Device OS. One of:
-                    - ios, android, windows, macos, linux
+            query_params (dict, optional): A dictionary containing supported filters.
+
+                ``[query_params.os_type]`` {str}: Filter by device operating system type. Valid options are:
+                    ios, android, windows, macos, linux.
+
+                ``[query_params.username]`` {str}:  Filter by enrolled username for the device.
 
         Returns:
             tuple: (Passwords object, response, error)

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/zscaler/zcc/web_policy.py

@@ -35,14 +35,14 @@ class WebPolicyAPI(APIClient):
         Args:
             query_params {dict}: Map of query parameters for the request.
                 ``[query_params.page]`` {int}: Specifies the page offset.
+
                 ``[query_params.page_size]`` {int}: Specifies the page size.
+
                 ``[query_params.device_type]`` {str}: Filter by device operating system type. Valid options are:
-                    - ios
-                    - android
-                    - windows
-                    - macos
-                    - linux
+                    ios, android, windows, macos, linux.
+
                 ``[query_params.search]`` {str}: The search string used to partially match.
+
                 ``[query_params.search_type]`` {str}: The search string used to partially match.
 
         Returns:

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/zscaler/zia/models/dlp_web_rules.py

@@ -65,7 +65,6 @@ class DLPWebRules(ZscalerObject):
             self.zscaler_incident_receiver = config["zscalerIncidentReceiver"] if "zscalerIncidentReceiver" in config else None
             self.external_auditor_email = config["externalAuditorEmail"] if "externalAuditorEmail" in config else None
 
-            # Handling lists of simple values
             self.protocols = ZscalerCollection.form_list(config["protocols"] if "protocols" in config else [], str)
 
             self.file_types = ZscalerCollection.form_list(config["fileTypes"] if "fileTypes" in config else [], str)
@@ -73,6 +72,9 @@ class DLPWebRules(ZscalerObject):
             self.cloud_applications = ZscalerCollection.form_list(
                 config["cloudApplications"] if "cloudApplications" in config else [], str
             )
+            self.user_risk_score_levels = ZscalerCollection.form_list(
+                config["userRiskScoreLevels"] if "userRiskScoreLevels" in config else [], str
+            )
             self.url_categories = ZscalerCollection.form_list(
                 config["urlCategories"] if "urlCategories" in config else [], common_reference.ResourceReference
             )
@@ -112,10 +114,10 @@ class DLPWebRules(ZscalerObject):
                 config["dlpEngines"] if "dlpEngines" in config else [], dlp_engine.DLPEngine
             )
             self.labels = ZscalerCollection.form_list(
-                config["labels"] if "labels" in config else [], labels.RuleLabels  # Missing Attribute
+                config["labels"] if "labels" in config else [], labels.RuleLabels
             )
             self.excluded_groups = ZscalerCollection.form_list(
-                config["excludedGroups"] if "excludedGroups" in config else [], user_management.Groups  # New Attribute
+                config["excludedGroups"] if "excludedGroups" in config else [], user_management.Groups
             )
             self.excluded_departments = ZscalerCollection.form_list(
                 config["excludedDepartments"] if "excludedDepartments" in config else [], user_management.Department
@@ -133,7 +135,6 @@ class DLPWebRules(ZscalerObject):
             self.icap_server = dlp_resources.DLPICAPServer(config["icapServer"]) if "icapServer" in config else None
 
         else:
-            # Defaults when config is None
             self.id = None
             self.name = None
             self.description = None
@@ -171,6 +172,7 @@ class DLPWebRules(ZscalerObject):
             self.excluded_groups = []
             self.excluded_departments = []
             self.excluded_users = []
+            self.user_risk_score_levels = []
             self.auditor = None
             self.notification_template = None
             self.icap_server = None
@@ -204,6 +206,7 @@ class DLPWebRules(ZscalerObject):
             "protocols": self.protocols,
             "fileTypes": self.file_types,
             "cloudApplications": self.cloud_applications,
+            "userRiskScoreLevels": self.user_risk_score_levels,
             "locations": [location.request_format() for location in (self.locations or [])],
             "locationGroups": [group.request_format() for group in (self.location_groups or [])],
             "groups": [group.request_format() for group in (self.groups or [])],

{zscaler_sdk_python-1.2.3 → zscaler_sdk_python-1.3.0}/zscaler/zia/models/url_filtering_rules.py

@@ -75,7 +75,9 @@ class URLFilteringRule(ZscalerObject):
             self.device_trust_levels = ZscalerCollection.form_list(
                 config["deviceTrustLevels"] if "deviceTrustLevels" in config else [], str
             )
-
+            self.user_risk_score_levels = ZscalerCollection.form_list(
+                config["userRiskScoreLevels"] if "userRiskScoreLevels" in config else [], str
+            )
             # Handling nested objects and lists of objects
             self.locations = ZscalerCollection.form_list(
                 config["locations"] if "locations" in config else [], location.LocationManagement
@@ -102,6 +104,9 @@ class URLFilteringRule(ZscalerObject):
             self.location_groups = ZscalerCollection.form_list(
                 config["locationGroups"] if "locationGroups" in config else [], location_group.LocationGroup
             )
+            self.source_ip_groups = ZscalerCollection.form_list(
+                config["sourceIpGroups"] if "sourceIpGroups" in config else [], cloud_firewall_source_groups.IPSourceGroup
+            )
             self.labels = ZscalerCollection.form_list(config["labels"] if "labels" in config else [], labels.RuleLabels)
             self.devices = ZscalerCollection.form_list(config["devices"] if "devices" in config else [], devices.Devices)
             self.device_groups = ZscalerCollection.form_list(
@@ -149,6 +154,8 @@ class URLFilteringRule(ZscalerObject):
             self.labels = []
             self.devices = []
             self.device_groups = []
+            self.user_risk_score_levels = []
+            self.source_ip_groups = []
             self.cbi_profile = None
 
     def request_format(self):
@@ -181,6 +188,8 @@ class URLFilteringRule(ZscalerObject):
             "urlCategories2": self.url_categories2,
             "requestMethods": self.request_methods,
             "deviceTrustLevels": self.device_trust_levels,
+            "userRiskScoreLevels": self.user_risk_score_levels,
+            "sourceIpGroups": [group.request_format() for group in (self.source_ip_groups or [])],
             "locations": [location.request_format() for location in (self.locations or [])],
             "groups": [group.request_format() for group in self.groups],
             "departments": [department.request_format() for department in (self.departments or [])],