zscaler-sdk-python 1.5.8__tar.gz → 1.6.0__tar.gz

{zscaler_sdk_python-1.5.8 → zscaler_sdk_python-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zscaler-sdk-python
-Version: 1.5.8
+Version: 1.6.0
 Summary: Official Python SDK for the Zscaler Products
 Home-page: https://github.com/zscaler/zscaler-sdk-python
 License: MIT
@@ -438,6 +438,81 @@ def main():
 Note, that custom headers will be overwritten with default headers with the same name.
 This doesn't allow breaking the client. Get default headers:
 
+### ZIA and ZTW Context Manager
+
+The Zscaler SDK provides a context manager pattern that automatically handles authentication and session cleanup for both ZIA and ZTW services. This pattern ensures that all configuration changes are properly activated when the context manager exits.
+
+#### How Context Manager Works
+
+When you use the `with` statement with a Zscaler client, the following happens automatically:
+
+1. **Authentication**: The client authenticates when entering the context
+2. **Session Management**: A session is established and maintained throughout the context
+3. **Automatic Deauthentication**: When exiting the context, the client automatically deauthenticates, which activates all staged configuration changes
+
+#### Implicit Activation Process
+
+The context manager implements an "implicit activation" approach where:
+
+- **All changes are final**: Configuration changes are automatically activated when the context exits
+- **No manual activation required**: You don't need to remember to call activation endpoints
+- **Deterministic behavior**: You always know that exiting the context will activate changes
+- **Automation-friendly**: Perfect for scripts and automation scenarios
+
+#### Example Usage
+
+```py
+from zscaler import ZscalerClient
+
+config = {
+    "clientId": '{yourClientId}',
+    "clientSecret": '{yourClientSecret}',
+    "vanityDomain": '{yourvanityDomain}',
+    "cloud": "beta", # Optional when authenticating to an alternative cloud environment
+    "customerId": "", # Optional parameter. Required only when using ZPA
+    "microtenantId": "", # Optional parameter. Required only when using ZPA with Microtenant
+    "logging": {"enabled": False, "verbose": False},
+}
+
+def main():
+    with ZscalerClient(config) as client:
+        # Make ZIA configuration changes
+        added_role, response, error = client.zia.admin_roles.add_role(
+            name="New API Role",
+            description="Role created via API",
+            feature_permissions={"ZIA_ADMIN_ROLE": "READ"}
+        )
+        if error:
+            print(f"Error adding role: {error}")
+            return
+        
+        # Make ZTW configuration changes
+        added_group, response, error = client.ztw.ip_destination_groups.add_group(
+            name="New IP Group",
+            description="IP group created via API"
+        )
+        if error:
+            print(f"Error adding IP group: {error}")
+            return
+        
+        print("All changes made successfully")
+    
+    # Context manager automatically deauthenticates here
+    # All staged changes are activated automatically for both ZIA and ZTW
+    print("Context exited - all changes have been activated")
+
+if __name__ == "__main__":
+    main()
+```
+
+#### Benefits
+
+- **Automatic cleanup**: No need to manually deauthenticate
+- **Error handling**: Even if an exception occurs, the context manager ensures proper cleanup
+- **Staged configuration activation**: All changes are activated when the context exits
+- **Simplified code**: No need to remember activation steps
+- **Multi-service support**: Works seamlessly with both ZIA and ZTW services
+
 ## Zscaler OneAPI Rate Limiting
 
 Zscaler OneAPI provides unique rate limiting numbers for each individual product. Regardless of the product, a 429 response will be returned if too many requests are made within a given time.
@@ -730,7 +805,7 @@ Each one of the configuration values above can be turned into an environment var
 
 ## Zscaler Legacy API Framework
 
-The legacy Zscaler API is still utilized by several customers, and will remain in place for the foreable future with no specific annouced deprecation date.
+The legacy Zscaler API is still utilized by several customers, and will remain in place for the foreseeable future with no specific announced deprecation date.
 
 ### ZIA Legacy Authentication
 
@@ -793,6 +868,78 @@ if __name__ == "__main__":
     main()
 ```
 
+### ZIA and ZTW Context Manager
+
+The Zscaler SDK provides a context manager pattern that automatically handles authentication and session cleanup for both ZIA and ZTW services. This pattern ensures that all configuration changes are properly activated when the context manager exits.
+
+#### How Context Manager Works
+
+When you use the `with` statement with a Zscaler client, the following happens automatically:
+
+1. **Authentication**: The client authenticates when entering the context
+2. **Session Management**: A session is established and maintained throughout the context
+3. **Automatic Deauthentication**: When exiting the context, the client automatically deauthenticates, which activates all staged configuration changes
+
+#### Implicit Activation Process
+
+The context manager implements an "implicit activation" approach where:
+
+- **All changes are final**: Configuration changes are automatically activated when the context exits
+- **No manual activation required**: You don't need to remember to call activation endpoints
+- **Deterministic behavior**: You always know that exiting the context will activate changes
+- **Automation-friendly**: Perfect for scripts and automation scenarios
+
+#### Example Usage
+
+```py
+import random
+from zscaler.oneapi_client import LegacyZIAClient
+
+config = {
+    "username": '{yourUsername}',
+    "password": '{yourPassword}',
+    "api_key": '{yourApiKey}',
+    "cloud": '{yourCloud}',
+    "logging": {"enabled": False, "verbose": False},
+}
+
+def main():
+    with LegacyZIAClient(config) as client:
+        # Make configuration changes
+        added_label, response, error = client.zia.rule_labels.add_label(
+            name=f"NewLabel_{random.randint(1000, 10000)}",
+            description=f"NewLabel_{random.randint(1000, 10000)}",
+        )
+        if error:
+            print(f"Error adding label: {error}")
+            return
+        
+        # Make more changes
+        updated_role, response, error = client.zia.admin_roles.update_role(
+            role_id="12345",
+            name="Updated Role Name"
+        )
+        if error:
+            print(f"Error updating role: {error}")
+            return
+        
+        print("All changes made successfully")
+    
+    # Context manager automatically deauthenticates here
+    # All staged changes are activated automatically
+    print("Context exited - all changes have been activated")
+
+if __name__ == "__main__":
+    main()
+```
+
+#### Benefits
+
+- **Automatic cleanup**: No need to manually deauthenticate
+- **Error handling**: Even if an exception occurs, the context manager ensures proper cleanup
+- **Staged configuration activation**: All changes are activated when the context exits
+- **Simplified code**: No need to remember activation steps
+
 ### ZTW Legacy Authentication
 
 Organizations whose tenant is still not migrated to Zidentity must continue using their previous ZTW API credentials.
@@ -930,7 +1077,7 @@ The ZCC Cloud is identified by several cloud name prefixes, which determines whi
 
 ### Environment variables
 
-You can provide credentials via the `ZCC_CLIENT_ID`, `ZCC_CLIENT_ID`, `ZCC_CLOUD` environment variables, representing your ZIA `api_key`, `secret_key`, and `cloud` respectively.
+You can provide credentials via the `ZCC_CLIENT_ID`, `ZCC_CLIENT_SECRET`, `ZCC_CLOUD` environment variables, representing your ZIA `api_key`, `secret_key`, and `cloud` respectively.
 
 ~> **NOTE** `ZCC_CLOUD` environment variable is required, and is used to identify the correct API gateway where the API requests should be forwarded to.
 

{zscaler_sdk_python-1.5.8 → zscaler_sdk_python-1.6.0}/README.md

@@ -399,6 +399,81 @@ def main():
 Note, that custom headers will be overwritten with default headers with the same name.
 This doesn't allow breaking the client. Get default headers:
 
+### ZIA and ZTW Context Manager
+
+The Zscaler SDK provides a context manager pattern that automatically handles authentication and session cleanup for both ZIA and ZTW services. This pattern ensures that all configuration changes are properly activated when the context manager exits.
+
+#### How Context Manager Works
+
+When you use the `with` statement with a Zscaler client, the following happens automatically:
+
+1. **Authentication**: The client authenticates when entering the context
+2. **Session Management**: A session is established and maintained throughout the context
+3. **Automatic Deauthentication**: When exiting the context, the client automatically deauthenticates, which activates all staged configuration changes
+
+#### Implicit Activation Process
+
+The context manager implements an "implicit activation" approach where:
+
+- **All changes are final**: Configuration changes are automatically activated when the context exits
+- **No manual activation required**: You don't need to remember to call activation endpoints
+- **Deterministic behavior**: You always know that exiting the context will activate changes
+- **Automation-friendly**: Perfect for scripts and automation scenarios
+
+#### Example Usage
+
+```py
+from zscaler import ZscalerClient
+
+config = {
+    "clientId": '{yourClientId}',
+    "clientSecret": '{yourClientSecret}',
+    "vanityDomain": '{yourvanityDomain}',
+    "cloud": "beta", # Optional when authenticating to an alternative cloud environment
+    "customerId": "", # Optional parameter. Required only when using ZPA
+    "microtenantId": "", # Optional parameter. Required only when using ZPA with Microtenant
+    "logging": {"enabled": False, "verbose": False},
+}
+
+def main():
+    with ZscalerClient(config) as client:
+        # Make ZIA configuration changes
+        added_role, response, error = client.zia.admin_roles.add_role(
+            name="New API Role",
+            description="Role created via API",
+            feature_permissions={"ZIA_ADMIN_ROLE": "READ"}
+        )
+        if error:
+            print(f"Error adding role: {error}")
+            return
+        
+        # Make ZTW configuration changes
+        added_group, response, error = client.ztw.ip_destination_groups.add_group(
+            name="New IP Group",
+            description="IP group created via API"
+        )
+        if error:
+            print(f"Error adding IP group: {error}")
+            return
+        
+        print("All changes made successfully")
+    
+    # Context manager automatically deauthenticates here
+    # All staged changes are activated automatically for both ZIA and ZTW
+    print("Context exited - all changes have been activated")
+
+if __name__ == "__main__":
+    main()
+```
+
+#### Benefits
+
+- **Automatic cleanup**: No need to manually deauthenticate
+- **Error handling**: Even if an exception occurs, the context manager ensures proper cleanup
+- **Staged configuration activation**: All changes are activated when the context exits
+- **Simplified code**: No need to remember activation steps
+- **Multi-service support**: Works seamlessly with both ZIA and ZTW services
+
 ## Zscaler OneAPI Rate Limiting
 
 Zscaler OneAPI provides unique rate limiting numbers for each individual product. Regardless of the product, a 429 response will be returned if too many requests are made within a given time.
@@ -691,7 +766,7 @@ Each one of the configuration values above can be turned into an environment var
 
 ## Zscaler Legacy API Framework
 
-The legacy Zscaler API is still utilized by several customers, and will remain in place for the foreable future with no specific annouced deprecation date.
+The legacy Zscaler API is still utilized by several customers, and will remain in place for the foreseeable future with no specific announced deprecation date.
 
 ### ZIA Legacy Authentication
 
@@ -754,6 +829,78 @@ if __name__ == "__main__":
     main()
 ```
 
+### ZIA and ZTW Context Manager
+
+The Zscaler SDK provides a context manager pattern that automatically handles authentication and session cleanup for both ZIA and ZTW services. This pattern ensures that all configuration changes are properly activated when the context manager exits.
+
+#### How Context Manager Works
+
+When you use the `with` statement with a Zscaler client, the following happens automatically:
+
+1. **Authentication**: The client authenticates when entering the context
+2. **Session Management**: A session is established and maintained throughout the context
+3. **Automatic Deauthentication**: When exiting the context, the client automatically deauthenticates, which activates all staged configuration changes
+
+#### Implicit Activation Process
+
+The context manager implements an "implicit activation" approach where:
+
+- **All changes are final**: Configuration changes are automatically activated when the context exits
+- **No manual activation required**: You don't need to remember to call activation endpoints
+- **Deterministic behavior**: You always know that exiting the context will activate changes
+- **Automation-friendly**: Perfect for scripts and automation scenarios
+
+#### Example Usage
+
+```py
+import random
+from zscaler.oneapi_client import LegacyZIAClient
+
+config = {
+    "username": '{yourUsername}',
+    "password": '{yourPassword}',
+    "api_key": '{yourApiKey}',
+    "cloud": '{yourCloud}',
+    "logging": {"enabled": False, "verbose": False},
+}
+
+def main():
+    with LegacyZIAClient(config) as client:
+        # Make configuration changes
+        added_label, response, error = client.zia.rule_labels.add_label(
+            name=f"NewLabel_{random.randint(1000, 10000)}",
+            description=f"NewLabel_{random.randint(1000, 10000)}",
+        )
+        if error:
+            print(f"Error adding label: {error}")
+            return
+        
+        # Make more changes
+        updated_role, response, error = client.zia.admin_roles.update_role(
+            role_id="12345",
+            name="Updated Role Name"
+        )
+        if error:
+            print(f"Error updating role: {error}")
+            return
+        
+        print("All changes made successfully")
+    
+    # Context manager automatically deauthenticates here
+    # All staged changes are activated automatically
+    print("Context exited - all changes have been activated")
+
+if __name__ == "__main__":
+    main()
+```
+
+#### Benefits
+
+- **Automatic cleanup**: No need to manually deauthenticate
+- **Error handling**: Even if an exception occurs, the context manager ensures proper cleanup
+- **Staged configuration activation**: All changes are activated when the context exits
+- **Simplified code**: No need to remember activation steps
+
 ### ZTW Legacy Authentication
 
 Organizations whose tenant is still not migrated to Zidentity must continue using their previous ZTW API credentials.
@@ -891,7 +1038,7 @@ The ZCC Cloud is identified by several cloud name prefixes, which determines whi
 
 ### Environment variables
 
-You can provide credentials via the `ZCC_CLIENT_ID`, `ZCC_CLIENT_ID`, `ZCC_CLOUD` environment variables, representing your ZIA `api_key`, `secret_key`, and `cloud` respectively.
+You can provide credentials via the `ZCC_CLIENT_ID`, `ZCC_CLIENT_SECRET`, `ZCC_CLOUD` environment variables, representing your ZIA `api_key`, `secret_key`, and `cloud` respectively.
 
 ~> **NOTE** `ZCC_CLOUD` environment variable is required, and is used to identify the correct API gateway where the API requests should be forwarded to.
 

{zscaler_sdk_python-1.5.8 → zscaler_sdk_python-1.6.0}/pyproject.toml

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

{zscaler_sdk_python-1.5.8 → zscaler_sdk_python-1.6.0}/zscaler/__init__.py

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

{zscaler_sdk_python-1.5.8 → zscaler_sdk_python-1.6.0}/zscaler/helpers.py

@@ -124,7 +124,8 @@ def to_snake_case(string):
         "extranetDTO": "extranet_dto",
         "locationGroupDTO": "location_group_dto",
         "locationDTO": "location_dto",
-        "predefinedADPControls": "predefined_adp_controls"
+        "predefinedADPControls": "predefined_adp_controls",
+        "runtimeOS": "runtime_os"
     }
 
     if string in FIELD_EXCEPTIONS:
@@ -256,7 +257,8 @@ def to_lower_camel_case(string):
         "extranet_dto": "extranetDTO",
         "location_group_dto": "locationGroupDTO",
         "location_dto": "locationDTO",
-        "predefined_adp_controls": "predefinedADPControls"
+        "predefined_adp_controls": "predefinedADPControls",
+        "runtime_os": "runtimeOS"
     }
 
     if string in FIELD_EXCEPTIONS:
@@ -296,7 +298,14 @@ def convert_keys_to_camel_case(data):
     Handles nested lists and dictionaries.
     """
     if isinstance(data, dict):
-        return {to_lower_camel_case(k): convert_keys_to_camel_case(v) for k, v in data.items()}
+        result = {}
+        for k, v in data.items():
+            # Special handling for featurePermissions - preserve keys as-is
+            if k == "featurePermissions" and isinstance(v, dict):
+                result[k] = v  # Don't convert the keys inside featurePermissions
+            else:
+                result[to_lower_camel_case(k)] = convert_keys_to_camel_case(v)
+        return result
     elif isinstance(data, list):
         return [convert_keys_to_camel_case(item) for item in data]
     else:

{zscaler_sdk_python-1.5.8 → zscaler_sdk_python-1.6.0}/zscaler/oneapi_client.py

@@ -268,6 +268,26 @@ class Client:
         if hasattr(self, "_session"):
             self._session.close()
             self.logger.debug("Session closed.")
+        
+        # Clean up Zscaler authentication session
+        if hasattr(self, '_request_executor'):
+            # For legacy clients, use their deauthenticate method
+            if self.use_legacy_client and hasattr(self._request_executor, 'deauthenticate'):
+                self.logger.debug("Deauthenticating Zscaler session via legacy client.")
+                self._request_executor.deauthenticate()
+                self.logger.debug("Zscaler session deauthenticated.")
+            # For OneAPI clients, use the request executor's deauthenticate method for ZIA/ZTW
+            elif not self.use_legacy_client and hasattr(self._request_executor, 'deauthenticate'):
+                # Get the service type from the request executor's last known service type
+                # or fall back to config if no requests were made
+                service_type = getattr(self._request_executor, '_last_service_type', None)
+                if not service_type:
+                    service_type = self._config.get("client", {}).get("service", "zia")
+                
+                if service_type.lower() in ["zia", "ztw"]:
+                    self.logger.debug(f"Deauthenticating Zscaler session for {service_type} service.")
+                    self._request_executor.deauthenticate(service_type)
+                    self.logger.debug(f"Zscaler session deauthenticated for {service_type}.")
 
     """
     Getters

{zscaler_sdk_python-1.5.8 → zscaler_sdk_python-1.6.0}/zscaler/oneapi_http_client.py

@@ -104,11 +104,11 @@ class HTTPClient:
             }
 
             # Handle payload
-            if request.get("json"):
+            if "json" in request:
                 params["json"] = request["json"]
-            elif request.get("data"):
+            elif "data" in request:
                 params["data"] = request["data"]
-            elif request.get("form"):
+            elif "form" in request:
                 params["data"] = request["form"]
             if request["params"]:
                 params["params"] = request["params"]

{zscaler_sdk_python-1.5.8 → zscaler_sdk_python-1.6.0}/zscaler/request_executor.py

@@ -188,7 +188,9 @@ class RequestExecutor:
             logger.error(f"Service detection failed: {e}")
             raise
 
-        body = body or {}
+        # Preserve empty lists, only convert None to empty dict
+        if body is None:
+            body = {}
         headers = headers or {}
         params = params or {}
 
@@ -225,6 +227,9 @@ class RequestExecutor:
                 raise ValueError("Missing required sandboxToken in config.")
             params["api_token"] = sandbox_token
 
+        # Track the service type for deauthentication
+        self._last_service_type = service_type
+        
         request = {
             "method": method,
             "url": final_url,
@@ -584,35 +589,80 @@ class RequestExecutor:
         logger.debug("Getting custom headers.")
         return self._custom_headers
 
-    # def get_retry_after(self, headers, logger):
-    #     retry_limit_reset_header = (
-    #         headers.get("x-ratelimit-reset") or 
-    #         headers.get("X-RateLimit-Reset") or
-    #         headers.get("RateLimit-Reset") or
+    def deauthenticate(self, service_type=None):
+        """
+        Deauthenticate from Zscaler services that support session-based authentication.
+        Currently supports ZIA and ZTW services.
+        
+        Args:
+            service_type (str, optional): The service type to deauthenticate from.
+                If None, will attempt to determine from the current configuration.
+        """
+        if not service_type:
+            service_type = self.service
+        
+        if service_type.lower() not in ["zia", "ztw"]:
+            logger.debug(f"Deauthentication not supported for service: {service_type}")
+            return False
+        
+        try:
+            # Determine the base URL and endpoint based on service type
+            if service_type.lower() == "zia":
+                if self.cloud and self.cloud != "production":
+                    base_url = f"https://api.{self.cloud}.zsapi.net"
+                else:
+                    base_url = "https://api.{self.cloud}.zsapi.net"
+                endpoint = "/zia/api/v1/authenticatedSession"
+            elif service_type.lower() == "ztw":
+                if self.cloud and self.cloud != "production":
+                    base_url = f"https://api.{self.cloud}.zsapi.net"
+                else:
+                    base_url = "https://api.{self.cloud}.zsapi.net"
+                endpoint = "/ztw/api/v1/auth"
+            
+            url = f"{base_url}{endpoint}"
+            
+            # Prepare headers using the standard method to include bearer token
+            # For DELETE requests, we'll exclude Content-Type to avoid issues with empty body
+            headers = self._prepare_headers({}, endpoint)
+            # Remove Content-Type for DELETE requests to avoid issues with empty body
+            headers.pop("Content-Type", None)
+            
+            # Both ZIA and ZTW require explicit deauthentication to activate staged configurations
+            # regardless of authentication method (OAuth or session-based)
+            if service_type.lower() in ["zia", "ztw"]:
+                logger.debug(f"{service_type.upper()} service requires explicit deauthentication to activate staged configurations")
             
-    #         # ZCC Specific Rate Limiting Headers (LegacyZCCClientHelper)
-    #         headers.get("X-Rate-Limit-Retry-After-Seconds") or # ZCC /downloadDevices Rate Limiting Header (LegacyZCCClientHelper)
-    #         headers.get("X-Rate-Limit-Remaining") # (LegacyZCCClientHelper)
-    #     )
-    #     retry_after = headers.get("Retry-After") or headers.get("retry-after")
-
-    #     if retry_after:
-    #         try:
-    #             return int(retry_after.strip("s")) + 1  # Add 1 second padding
-    #         except ValueError:
-    #             logger.error(f"Error parsing Retry-After header: {retry_after}")
-    #             return None
-
-    #     if retry_limit_reset_header is not None:
-    #         try:
-    #             reset_seconds = float(retry_limit_reset_header)
-    #             return reset_seconds + 1  # Add 1 second padding
-    #         except ValueError:
-    #             logger.error(f"Error parsing x-ratelimit-reset header: {retry_limit_reset_header}")
-    #             return None
-
-    #     logger.error("Missing Retry-After and X-Rate-Limit-Reset headers.")
-    #     return None
+            # Send DELETE request to deauthenticate
+            logger.debug(f"Deauthenticating from {service_type} at {url}")
+            
+            # Use the HTTP client to send the request
+            request = {
+                "method": "DELETE",
+                "url": url,
+                "headers": headers,
+                "params": {},
+                "uuid": uuid.uuid4(),
+                "service_type": service_type,
+            }
+            
+            response, error = self._http_client.send_request(request)
+            
+            if error:
+                logger.warning(f"Failed to deauthenticate from {service_type}: {error}")
+                return False
+            
+            if response and response.status_code == 200:
+                logger.debug(f"Successfully deauthenticated from {service_type}")
+                return True
+            else:
+                logger.warning(f"Unexpected response during deauthentication: {response.status_code if response else 'No response'}")
+                return False
+                
+        except Exception as e:
+            logger.warning(f"Exception during deauthentication for {service_type}: {e}")
+            return False
+
 
     def get_retry_after(self, headers, logger):
         retry_limit_reset_header = (

{zscaler_sdk_python-1.5.8 → zscaler_sdk_python-1.6.0}/zscaler/utils.py

@@ -89,6 +89,7 @@ reformat_params = [
     ("criteria_domain_profile_ids", "criteriaDomainProfiles"),
     ("email_recipient_profile_ids", "emailRecipientProfiles"),
     ("entity_group_ids", "entityGroups"),
+    ("scope_entity_ids", "adminScopeScopeEntities"),
 ]
 
 

{zscaler_sdk_python-1.5.8 → zscaler_sdk_python-1.6.0}/zscaler/zcc/devices.py

@@ -407,6 +407,8 @@ class DevicesAPI(APIClient):
         """
         )
 
+        query_params = query_params or {}
+
         body = {}
         headers = {}