zscaler-sdk-python 1.9.18__tar.gz → 1.9.20__tar.gz

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: zscaler-sdk-python
-Version: 1.9.18
+Version: 1.9.20
 Summary: Official Python SDK for the Zscaler Products
 Home-page: https://github.com/zscaler/zscaler-sdk-python
 License: MIT
@@ -23,6 +23,7 @@ Requires-Dist: PyJWT (>=2.10.1)
 Requires-Dist: aenum (>=3.1.11)
 Requires-Dist: arrow (>=1.3.0)
 Requires-Dist: cryptography (>=45.0.2)
+Requires-Dist: jmespath (>=1.0.0)
 Requires-Dist: jwcrypto (>=1.5.6)
 Requires-Dist: pydash (>=8.0.3)
 Requires-Dist: python-box (>=7.3.0)
@@ -63,6 +64,7 @@ Description-Content-Type: text/markdown
 * [Zscaler Legacy API Framework](#zscaler-legacy-api-framework)
 * [Configuration reference](#configuration-reference)
 * [Pagination](#pagination)
+* [Client-Side Filtering with JMESPath](#client-side-filtering-with-jmespath)
 * [Contributing](#contributing)
 
 The Zscaler SDK for Python includes functionality to accelerate development via [Python](https://www.python.org/). This SDK can be
@@ -745,6 +747,95 @@ except StopIteration:
     print("All data fetched.")
 ```
 
+### Client-Side Filtering with JMESPath
+
+The SDK supports client-side filtering and projection of API results using [JMESPath](https://jmespath.org/) expressions. After any list call, you can use `resp.search(expression)` to filter, project, or reshape the response data without making additional API calls.
+
+JMESPath is a query language for JSON that lets you declaratively extract and transform elements from JSON documents. The `.search()` method applies a JMESPath expression to the current page of results and returns a list of matching items.
+
+#### Basic Filtering
+
+```py
+# Fetch users and filter admin users client-side
+users, resp, err = client.zia.user_management.list_users()
+admin_users = resp.search("[?adminUser==`true`]")
+print(f"Found {len(admin_users)} admin users")
+```
+
+#### Projection (Selecting Specific Fields)
+
+```py
+# Extract only names and emails
+users, resp, err = client.zia.user_management.list_users()
+names_emails = resp.search("[*].{name: name, email: email}")
+for item in names_emails:
+    print(f"{item['name']}: {item['email']}")
+```
+
+#### Combined Filtering and Projection
+
+```py
+# Filter by role and project specific fields
+users, resp, err = client.zia.user_management.list_users()
+result = resp.search("[?adminUser==`true`].{name: name, id: id}")
+```
+
+#### Nested Field Filtering
+
+```py
+# Filter users by department name
+users, resp, err = client.zia.user_management.list_users()
+eng_users = resp.search("[?department.name=='Engineering'].name")
+```
+
+#### Using with Paginated Results
+
+`.search()` operates on the current page. To filter across all pages, apply it to each page as you paginate:
+
+```py
+users, resp, err = client.zia.user_management.list_users(
+    query_params={"page_size": 1000}
+)
+all_admins = resp.search("[?adminUser==`true`]")
+
+while resp.has_next():
+    next_page, resp, err = resp.next()
+    if err:
+        break
+    if next_page:
+        all_admins.extend(resp.search("[?adminUser==`true`]"))
+
+print(f"Total admins across all pages: {len(all_admins)}")
+```
+
+#### Using with Wrapped Responses
+
+For APIs that wrap results in a named key (e.g., ZDX `items`, ZBI `reports`), reference the key in the expression:
+
+```py
+# ZDX software inventory
+items, resp, err = client.zdx.software.list_inventory()
+zscaler_sw = resp.search(
+    "items[?vendor=='Zscaler'].{name: software_name, devices: device_total}"
+)
+
+# ZBI reports
+reports, resp, err = client.zbi.reports.list_reports(report_type="APPLICATION")
+completed = resp.search("reports[?status=='COMPLETED']")
+```
+
+#### JMESPath Built-in Functions
+
+JMESPath supports built-in functions like `length()`, `sort_by()`, `max_by()`, and more:
+
+```py
+# Users with at least one group assigned
+users, resp, err = client.zia.user_management.list_users()
+with_groups = resp.search("[?length(groups || `[]`) > `0`]")
+```
+
+For the full JMESPath specification and function reference, see [jmespath.org](https://jmespath.org/).
+
 ## Logging
 
 The Zscaler SDK Python, provides robust logging for debug purposes.

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/README.md

@@ -25,6 +25,7 @@
 * [Zscaler Legacy API Framework](#zscaler-legacy-api-framework)
 * [Configuration reference](#configuration-reference)
 * [Pagination](#pagination)
+* [Client-Side Filtering with JMESPath](#client-side-filtering-with-jmespath)
 * [Contributing](#contributing)
 
 The Zscaler SDK for Python includes functionality to accelerate development via [Python](https://www.python.org/). This SDK can be
@@ -707,6 +708,95 @@ except StopIteration:
     print("All data fetched.")
 ```
 
+### Client-Side Filtering with JMESPath
+
+The SDK supports client-side filtering and projection of API results using [JMESPath](https://jmespath.org/) expressions. After any list call, you can use `resp.search(expression)` to filter, project, or reshape the response data without making additional API calls.
+
+JMESPath is a query language for JSON that lets you declaratively extract and transform elements from JSON documents. The `.search()` method applies a JMESPath expression to the current page of results and returns a list of matching items.
+
+#### Basic Filtering
+
+```py
+# Fetch users and filter admin users client-side
+users, resp, err = client.zia.user_management.list_users()
+admin_users = resp.search("[?adminUser==`true`]")
+print(f"Found {len(admin_users)} admin users")
+```
+
+#### Projection (Selecting Specific Fields)
+
+```py
+# Extract only names and emails
+users, resp, err = client.zia.user_management.list_users()
+names_emails = resp.search("[*].{name: name, email: email}")
+for item in names_emails:
+    print(f"{item['name']}: {item['email']}")
+```
+
+#### Combined Filtering and Projection
+
+```py
+# Filter by role and project specific fields
+users, resp, err = client.zia.user_management.list_users()
+result = resp.search("[?adminUser==`true`].{name: name, id: id}")
+```
+
+#### Nested Field Filtering
+
+```py
+# Filter users by department name
+users, resp, err = client.zia.user_management.list_users()
+eng_users = resp.search("[?department.name=='Engineering'].name")
+```
+
+#### Using with Paginated Results
+
+`.search()` operates on the current page. To filter across all pages, apply it to each page as you paginate:
+
+```py
+users, resp, err = client.zia.user_management.list_users(
+    query_params={"page_size": 1000}
+)
+all_admins = resp.search("[?adminUser==`true`]")
+
+while resp.has_next():
+    next_page, resp, err = resp.next()
+    if err:
+        break
+    if next_page:
+        all_admins.extend(resp.search("[?adminUser==`true`]"))
+
+print(f"Total admins across all pages: {len(all_admins)}")
+```
+
+#### Using with Wrapped Responses
+
+For APIs that wrap results in a named key (e.g., ZDX `items`, ZBI `reports`), reference the key in the expression:
+
+```py
+# ZDX software inventory
+items, resp, err = client.zdx.software.list_inventory()
+zscaler_sw = resp.search(
+    "items[?vendor=='Zscaler'].{name: software_name, devices: device_total}"
+)
+
+# ZBI reports
+reports, resp, err = client.zbi.reports.list_reports(report_type="APPLICATION")
+completed = resp.search("reports[?status=='COMPLETED']")
+```
+
+#### JMESPath Built-in Functions
+
+JMESPath supports built-in functions like `length()`, `sort_by()`, `max_by()`, and more:
+
+```py
+# Users with at least one group assigned
+users, resp, err = client.zia.user_management.list_users()
+with_groups = resp.search("[?length(groups || `[]`) > `0`]")
+```
+
+For the full JMESPath specification and function reference, see [jmespath.org](https://jmespath.org/).
+
 ## Logging
 
 The Zscaler SDK Python, provides robust logging for debug purposes.

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "zscaler-sdk-python"
-version = "1.9.18"
+version = "1.9.20"
 description = "Official Python SDK for the Zscaler Products"
 authors = ["Zscaler, Inc. <devrel@zscaler.com>"]
 license = "MIT"
@@ -40,6 +40,7 @@ jwcrypto = ">=1.5.6"
 aenum = ">=3.1.11"
 pydash = ">=8.0.3"
 arrow = ">=1.3.0"
+jmespath = ">=1.0.0"
 
 [tool.poetry.group.dev.dependencies]
 black = ">=24.3.0"

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/__init__.py

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

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/oneapi_response.py

@@ -3,6 +3,7 @@ import json
 import logging
 import uuid
 import requests
+import jmespath
 
 logger = logging.getLogger(__name__)
 
@@ -14,9 +15,9 @@ class ZscalerAPIResponse:
     """
 
     SERVICE_PAGE_LIMITS = {
-        "ZPA": {"default": 100, "max": 500},
-        "ZIA": {"default": 500, "max": 10000},
-        "ZDX": {"default": 10, "min": 1},
+        "zpa": {"default": 100, "max": 500},
+        "zia": {"default": 500, "max": 10000},
+        "zdx": {"default": 10, "min": 1},
     }
 
     def __init__(
@@ -51,10 +52,9 @@ class ZscalerAPIResponse:
 
         self._service_type = service_type
         self._offset = self._params.get("offset", 0)
-        self._limit = self.validate_page_size(self._params.get("limit"), service_type)
         self._next_offset = None
         self._list = []
-        self._is_flat_list_response = False  # Track if response is a flat list (no pagination metadata)
+        self._is_flat_list_response = False
 
         if all_entries:
             self._params["allEntries"] = True
@@ -69,21 +69,22 @@ class ZscalerAPIResponse:
         if end_time:
             self._params["endTime"] = end_time
 
-        # If service is ZIA, ensure the pagination parameter is "pageSize" in camelCase
         if self._service_type == "zia":
+            # Normalize page_size → pageSize if still in snake_case
             if "page_size" in self._params:
                 self._params["pageSize"] = self._params.pop("page_size")
-
-        if self._service_type == "zia":
             # If user supplied pageNumber, initialize self._page accordingly
             if "pageNumber" in self._params:
                 try:
                     self._page = int(self._params["pageNumber"])
                 except Exception:
                     self._page = 1
-            # Always remove 'page' if present for ZIA
             self._params.pop("page", None)
-            # logger.debug(f"[DEBUG] __init__ params after ZIA normalization: {self._params}")
+
+        # Resolve the user-supplied page size from the correct param key per service.
+        # ZIA uses "pageSize"; ZPA uses "pagesize"; others use "limit".
+        raw_page_size = self._params.get("pageSize") or self._params.get("pagesize") or self._params.get("limit")
+        self._limit = self.validate_page_size(raw_page_size, service_type)
 
         if res_details:
             content_type = res_details.headers.get("Content-Type", "").lower()
@@ -160,20 +161,19 @@ class ZscalerAPIResponse:
         self._body = json.loads(response_body)
 
         if isinstance(self._body, list):
-            # Handle direct list responses (ZIA, ZPA simple lists, etc.)
-            # A flat list response means the API returned all results in one response
-            # without pagination metadata - pagination should NOT continue
             self._list = self._body
-            self._is_flat_list_response = True  # Mark as flat list - no pagination
-            # Check if this is a list of simple types (strings, numbers, etc.) vs dicts
-            # If it's a list of simple types, skip the cleaning logic
+
+            # ZIA returns flat JSON arrays for paginated list endpoints.
+            # Do NOT mark those as flat-list (non-paginated); let the
+            # page-size heuristic in _has_next() drive pagination instead.
+            if self._service_type == "zia":
+                self._is_flat_list_response = False
+            else:
+                self._is_flat_list_response = True
+
             if self._body and len(self._body) > 0 and not isinstance(self._body[0], dict):
-                # This is a list of simple types (e.g., ["CRITICAL", "HIGH", ...])
-                # Don't filter it - keep the original list as-is
-                # No cleaning needed for simple types
                 pass
             elif self._body and len(self._body) > 0:
-                # This is a list of dicts - apply cleaning logic
                 cleaned_list = []
                 for item in self._list:
                     if isinstance(item, dict):
@@ -181,8 +181,7 @@ class ZscalerAPIResponse:
                     else:
                         logger.warning("Non-dict item found in response list, skipping: %s", item)
                 self._list = cleaned_list
-            # If list is empty, _list is already set to empty list, no cleaning needed
-        elif self._service_type == "ZDX":
+        elif self._service_type == "zdx":
             self._list = self._body.get("items", [])
             self._next_offset = self._body.get("next_offset")
         elif self._service_type == "zidentity":
@@ -199,13 +198,11 @@ class ZscalerAPIResponse:
             self._total_results = self._body.get("total_results", 0)
             self._next_page = self._body.get("next_page")
             self._prev_page = self._body.get("prev_page")
-        elif self._service_type == "ZCC":
+        elif self._service_type == "zcc":
             # ZCC can return either a single object or a list of objects
             if isinstance(self._body, dict):
-                # If it's a single object, wrap it in a list
                 self._list = [self._body]
             else:
-                # If it's already a list, use it as is
                 self._list = self._body if isinstance(self._body, list) else []
         elif self._service_type == "bi":
             # ZBI list reports returns {"reportType": "...", "reports": [...]}
@@ -237,7 +234,7 @@ class ZscalerAPIResponse:
         else:
             # ZPA and possibly other services use a dict with "list" field
             self._list = self._body.get("list", [])
-            if self._service_type == "ZPA":
+            if self._service_type == "zpa":
                 self._total_pages = int(self._body.get("totalPages", 1))
                 self._total_count = int(self._body.get("totalCount", 0))
 
@@ -261,7 +258,7 @@ class ZscalerAPIResponse:
         """
         logger.debug("Fetching current page results")
 
-        if self._service_type.upper() == "ZCC" and self._type:
+        if self._service_type == "zcc" and self._type:
             try:
                 return [self._type(item) for item in self._list if isinstance(item, dict)]
             except Exception as wrap_error:
@@ -270,6 +267,49 @@ class ZscalerAPIResponse:
 
         return self._list
 
+    def search(self, expression: str) -> List[Any]:
+        """
+        Applies a JMESPath expression to the current page of results for
+        client-side filtering and projection.
+
+        The expression is first evaluated against the full response body
+        (useful for expressions that reference top-level keys, e.g.
+        ``"users[?name=='Alice']"``).  If the body is a plain list, the
+        expression is applied directly to the list instead.
+
+        Args:
+            expression: A JMESPath expression string.
+
+        Returns:
+            A list of matching items (or projected dicts/values).  Returns
+            an empty list when nothing matches.
+
+        Raises:
+            jmespath.exceptions.ParseError: If *expression* is not valid
+                JMESPath syntax.
+
+        Examples:
+            >>> items, resp, err = client.zia.user_management.list_users()
+            >>> admins = resp.search("[?adminUser==`true`]")
+
+            >>> items, resp, err = client.zdx.software.list_inventory()
+            >>> zscaler = resp.search(
+            ...     "items[?vendor=='Zscaler'].{name: software_name}"
+            ... )
+        """
+        compiled = jmespath.compile(expression)
+
+        # Apply against the full body first (handles expressions that target
+        # a named key inside the response envelope, e.g. "reports[?x>1]").
+        target = self._body if self._body is not None else self._list
+        result = compiled.search(target)
+
+        if result is None:
+            return []
+        if isinstance(result, list):
+            return result
+        return [result]
+
     def has_next(self) -> bool:
         """
         Returns True if there are more pages to fetch, False otherwise.
@@ -303,10 +343,10 @@ class ZscalerAPIResponse:
             logger.debug("No more pages to fetch")
             return [], None
 
-        if self._service_type.upper() == "ZDX":
+        if self._service_type == "zdx":
             logger.debug("[DEBUG] Taking ZDX pagination branch.")
             self._params["offset"] = self._next_offset
-        elif self._service_type.upper() == "ZIA":
+        elif self._service_type == "zia":
             logger.debug("[DEBUG] Taking ZIA pagination branch.")
             self._page += 1
             self._params["page"] = self._page
@@ -359,13 +399,11 @@ class ZscalerAPIResponse:
             logger.debug("Has next page: False (flat list response - all results returned in single response)")
             return False
 
-        if self._service_type == "ZPA":
-            # More pages if current page < total_pages
+        if self._service_type == "zpa":
             has_next = self._page < self._total_pages
             logger.debug("Has next page for ZPA: %s (page %d of %d)", has_next, self._page, self._total_pages)
             return has_next
-        elif self._service_type == "ZDX":
-            # More pages if next_offset is not None
+        elif self._service_type == "zdx":
             has_next = self._next_offset is not None
             logger.debug("Has next page for ZDX: %s", has_next)
             return has_next

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/zbi/custom_apps.py

@@ -58,6 +58,14 @@ class CustomAppsAPI(APIClient):
                 ...     print(f"Error: {err}")
                 >>> for app in apps:
                 ...     print(app.as_dict())
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "GET"
         api_url = format_url(f"""

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/zbi/reports.py

@@ -80,6 +80,14 @@ class ReportsAPI(APIClient):
                 ...     print(f"Error: {err}")
                 >>> for r in reports:
                 ...     print(r)
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "GET"
         api_url = format_url(f"""

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/zcc/admin_user.py

@@ -53,6 +53,14 @@ class AdminUserAPI(APIClient):
             ... print(f"Total admin users found: {len(user_list)}")
             ... for user in user_list:
             ...     print(user.as_dict())
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "get".upper()
         api_url = format_url(f"""
@@ -147,6 +155,14 @@ class AdminUserAPI(APIClient):
             ...     print(f"Total admin roles found: {len(role_list)}")
             ...     for role in role_list:
             ...         print(role.as_dict())
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "get".upper()
         api_url = format_url(f"""

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/zcc/devices.py

@@ -323,6 +323,14 @@ class DevicesAPI(APIClient):
             ... print(f"Total devices found: {len(device_list)}")
             ... for device in device_list:
             ...     print(device.as_dict())
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "get".upper()
         api_url = format_url(f"""

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/zcc/fail_open_policy.py

@@ -50,6 +50,14 @@ class FailOpenPolicyAPI(APIClient):
             ...         return
             ...     for policy in policy_list:
             ...         print(policy.as_dict())
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "get".upper()
         api_url = format_url(f"""

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/zcc/forwarding_profile.py

@@ -51,6 +51,14 @@ class ForwardingProfileAPI(APIClient):
             ...         return
             ...     for profile in profile_list:
             ...         print(profile.as_dict())
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "get".upper()
         api_url = format_url(f"""

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/zcc/trusted_networks.py

@@ -52,6 +52,14 @@ class TrustedNetworksAPI(APIClient):
             ...     print(f"Total trusted networks found: {len(network_list)}")
             ...     for network in network_list:
             ...         print(network.as_dict())
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "get".upper()
         api_url = format_url(f"""

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/zcc/web_app_service.py

@@ -49,6 +49,14 @@ class WebAppServiceAPI(APIClient):
             ... else:
             ...     for policy in policies:
             ...         print(policy)
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "get".upper()
         api_url = format_url(f"""

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/zcc/web_policy.py

@@ -59,6 +59,14 @@ class WebPolicyAPI(APIClient):
             ...     return
             ... for policy in policy_list:
             ...     print(policy.as_dict())
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "get".upper()
         api_url = format_url(f"""

{zscaler_sdk_python-1.9.18 → zscaler_sdk_python-1.9.20}/zscaler/zdx/admin.py

@@ -65,6 +65,14 @@ class AdminAPI(APIClient):
             ... print(f"Total department found: {len(dept_list)}")
             ...  for dept in dept_list:
             ...     print(dept.as_dict())
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "get".upper()
         api_url = format_url(f"""
@@ -130,6 +138,14 @@ class AdminAPI(APIClient):
             ... print(f"Total location found: {len(locations_list)}")
             ...  for location in locations_list:
             ...     print(location.as_dict())
+
+            Client-side filtering with JMESPath:
+
+            The response object supports client-side filtering and
+            projection via ``resp.search(expression)``.  See the
+            `JMESPath documentation <https://jmespath.org/>`_ for
+            expression syntax.
+
         """
         http_method = "get".upper()
         api_url = format_url(f"""