Refactor API parameter handling and improve documentation

- Updated `searchOrgNacClients` and `searchSiteNacClients` to correct status options from 'session_ended' to 'session_stopped'.
- Rearranged parameters in `searchOrgWanClients`, `searchSiteWanClients`, and `searchSiteWirelessClients` for consistency and clarity.
- Added new parameters `cert_expiry_duration` and `psk_name` to `searchSiteNacClients` and `searchSiteWirelessClients` respectively.
- Removed unused parameters and cleaned up query parameter handling in various search functions.
- Enhanced logging and sanitization in `test_logger.py` to ensure sensitive data is properly redacted.
- Deleted obsolete test file `test.py` to streamline the test suite.
- Improved test readability and structure across multiple test files.

Author: tmunzer-AIDE

mist_openapi

@@ -188,7 +188,9 @@ def _request_with_retry(
                 self._log_proxy()
                 resp = request_fn()
                 logger.debug(
-                    "apirequest:%s:request headers:%s", method_name, self._remove_auth_from_headers(resp)
+                    "apirequest:%s:request headers:%s",
+                    method_name,
+                    self._remove_auth_from_headers(resp),
                 )
                 resp.raise_for_status()
                 break
@@ -203,7 +205,9 @@ def _request_with_retry(
                 if e.response.status_code == 429 and attempt < self._MAX_429_RETRIES:
                     logger.warning(
                         "apirequest:%s:HTTP 429 (attempt %s/%s)",
-                        method_name, attempt + 1, self._MAX_429_RETRIES,
+                        method_name,
+                        attempt + 1,
+                        self._MAX_429_RETRIES,
                     )
                     try:
                         self._next_apitoken()
@@ -214,7 +218,9 @@ def _request_with_retry(
                 logger.error("apirequest:%s:HTTP error: %s", method_name, e)
                 if resp:
                     logger.error(
-                        "apirequest:%s:HTTP error description: %s", method_name, resp.json()
+                        "apirequest:%s:HTTP error description: %s",
+                        method_name,
+                        resp.json(),
                     )
                 break
             except Exception as e:
@@ -334,19 +340,22 @@ def mist_post_file(
             multipart_form_data = {}
         url = self._url(uri)
         logger.debug(
-            "apirequest:mist_post_file:initial multipart_form_data:%s", multipart_form_data
+            "apirequest:mist_post_file:initial multipart_form_data:%s",
+            multipart_form_data,
         )
         generated_multipart_form_data: dict[str, Any] = {}
         for key in multipart_form_data:
             logger.debug(
                 "apirequest:mist_post_file:multipart_form_data:%s = %s",
-                key, multipart_form_data[key],
+                key,
+                multipart_form_data[key],
             )
             if multipart_form_data[key]:
                 try:
                     if key in ["csv", "file"]:
                         logger.debug(
-                            "apirequest:mist_post_file:reading file:%s", multipart_form_data[key]
+                            "apirequest:mist_post_file:reading file:%s",
+                            multipart_form_data[key],
                         )
                         f = open(multipart_form_data[key], "rb")
                         generated_multipart_form_data[key] = (
@@ -363,7 +372,8 @@ def mist_post_file(
                     logger.error(
                         "apirequest:mist_post_file:multipart_form_data:"
                         "Unable to parse JSON object %s with value %s",
-                        key, multipart_form_data[key],
+                        key,
+                        multipart_form_data[key],
                     )
                     logger.error(
                         "apirequest:mist_post_file: Exception occurred",
@@ -377,7 +387,8 @@ def mist_post_file(
         def _do_post_file():
             resp = self._session.post(url, files=generated_multipart_form_data)
             logger.debug(
-                "apirequest:mist_post_file:request body:%s", self.remove_file_from_body(resp)
+                "apirequest:mist_post_file:request body:%s",
+                self.remove_file_from_body(resp),
             )
             return resp
 

src/mistapi/__api_request.py

@@ -859,7 +859,10 @@ def login_with_return(
             LOGGER.info("apisession:login_with_return:access authorized")
             return {"authenticated": True, "error": ""}
         else:
-            LOGGER.error("apisession:login_with_return:access denied: status code %s", resp.status_code)
+            LOGGER.error(
+                "apisession:login_with_return:access denied: status code %s",
+                resp.status_code,
+            )
             return {"authenticated": False, "error": resp.data}
 
     def logout(self) -> None:
@@ -1102,9 +1105,7 @@ def _getself(self) -> bool:
                     print()
                     print(" Authenticated ".center(80, "-"))
                     print(f"\r\nWelcome {self.first_name} {self.last_name}!\r\n")
-                LOGGER.info(
-                    "apisession:_getself:account info processed successfully"
-                )
+                LOGGER.info("apisession:_getself:account info processed successfully")
                 return True
         elif resp.proxy_error:
             LOGGER.critical("apisession:_getself:proxy not valid...")

src/mistapi/__api_session.py

@@ -284,20 +284,20 @@ def searchOrgWirelessClients(
     mist_session: _APISession,
     org_id: str,
     site_id: str | None = None,
-    mac: str | None = None,
-    ip: str | None = None,
-    hostname: str | None = None,
+    ap: str | None = None,
     band: str | None = None,
     device: str | None = None,
-    os: str | None = None,
+    hostname: str | None = None,
+    ip: str | None = None,
+    mac: str | None = None,
     model: str | None = None,
-    ap: str | None = None,
+    os: str | None = None,
     psk_id: str | None = None,
     psk_name: str | None = None,
-    username: str | None = None,
-    vlan: str | None = None,
     ssid: str | None = None,
     text: str | None = None,
+    username: str | None = None,
+    vlan: str | None = None,
     limit: int | None = None,
     start: str | None = None,
     end: str | None = None,
@@ -320,20 +320,20 @@ def searchOrgWirelessClients(
     QUERY PARAMS
     ------------
     site_id : str
-    mac : str
-    ip : str
-    hostname : str
+    ap : str
     band : str
     device : str
-    os : str
+    hostname : str
+    ip : str
+    mac : str
     model : str
-    ap : str
+    os : str
     psk_id : str
     psk_name : str
-    username : str
-    vlan : str
     ssid : str
     text : str
+    username : str
+    vlan : str
     limit : int, default: 100
     start : str
     end : str
@@ -351,34 +351,34 @@ def searchOrgWirelessClients(
     query_params: dict[str, str] = {}
     if site_id:
         query_params["site_id"] = str(site_id)
-    if mac:
-        query_params["mac"] = str(mac)
-    if ip:
-        query_params["ip"] = str(ip)
-    if hostname:
-        query_params["hostname"] = str(hostname)
+    if ap:
+        query_params["ap"] = str(ap)
     if band:
         query_params["band"] = str(band)
     if device:
         query_params["device"] = str(device)
-    if os:
-        query_params["os"] = str(os)
+    if hostname:
+        query_params["hostname"] = str(hostname)
+    if ip:
+        query_params["ip"] = str(ip)
+    if mac:
+        query_params["mac"] = str(mac)
     if model:
         query_params["model"] = str(model)
-    if ap:
-        query_params["ap"] = str(ap)
+    if os:
+        query_params["os"] = str(os)
     if psk_id:
         query_params["psk_id"] = str(psk_id)
     if psk_name:
         query_params["psk_name"] = str(psk_name)
-    if username:
-        query_params["username"] = str(username)
-    if vlan:
-        query_params["vlan"] = str(vlan)
     if ssid:
         query_params["ssid"] = str(ssid)
     if text:
         query_params["text"] = str(text)
+    if username:
+        query_params["username"] = str(username)
+    if vlan:
+        query_params["vlan"] = str(vlan)
     if limit:
         query_params["limit"] = str(limit)
     if start:

src/mistapi/api/v1/orgs/clients.py

@@ -485,17 +485,16 @@ def listOrgApsMacs(
 def searchOrgDevices(
     mist_session: _APISession,
     org_id: str,
-    band_24_bandwidth: int | None = None,
     band_24_channel: int | None = None,
-    band_24_power: int | None = None,
-    band_5_bandwidth: int | None = None,
     band_5_channel: int | None = None,
-    band_5_power: int | None = None,
-    band_6_bandwidth: int | None = None,
     band_6_channel: int | None = None,
+    band_24_bandwidth: int | None = None,
+    band_5_bandwidth: int | None = None,
+    band_6_bandwidth: int | None = None,
+    band_24_power: int | None = None,
+    band_5_power: int | None = None,
     band_6_power: int | None = None,
-    cpu: str | None = None,
-    clustered: str | None = None,
+    clustered: bool | None = None,
     eth0_port_speed: int | None = None,
     evpntopo_id: str | None = None,
     ext_ip: str | None = None,
@@ -505,8 +504,6 @@ def searchOrgDevices(
     last_hostname: str | None = None,
     lldp_mgmt_addr: str | None = None,
     lldp_port_id: str | None = None,
-    lldp_power_allocated: int | None = None,
-    lldp_power_draw: int | None = None,
     lldp_system_desc: str | None = None,
     lldp_system_name: str | None = None,
     mac: str | None = None,
@@ -518,10 +515,12 @@ def searchOrgDevices(
     node0_mac: str | None = None,
     node1_mac: str | None = None,
     power_constrained: bool | None = None,
+    radius_stats: str | None = None,
     site_id: str | None = None,
+    stats: bool | None = None,
     t128agent_version: str | None = None,
-    version: str | None = None,
     type: str | None = None,
+    version: str | None = None,
     limit: int | None = None,
     start: str | None = None,
     end: str | None = None,
@@ -543,17 +542,16 @@ def searchOrgDevices(
 
     QUERY PARAMS
     ------------
-    band_24_bandwidth : int
     band_24_channel : int
-    band_24_power : int
-    band_5_bandwidth : int
     band_5_channel : int
-    band_5_power : int
-    band_6_bandwidth : int
     band_6_channel : int
+    band_24_bandwidth : int
+    band_5_bandwidth : int
+    band_6_bandwidth : int
+    band_24_power : int
+    band_5_power : int
     band_6_power : int
-    cpu : str
-    clustered : str
+    clustered : bool
     eth0_port_speed : int
     evpntopo_id : str
     ext_ip : str
@@ -563,25 +561,26 @@ def searchOrgDevices(
     last_hostname : str
     lldp_mgmt_addr : str
     lldp_port_id : str
-    lldp_power_allocated : int
-    lldp_power_draw : int
     lldp_system_desc : str
     lldp_system_name : str
     mac : str
     model : str
     mxedge_id : str
     mxedge_ids : str
     mxtunnel_status : str{'down', 'up'}
-      If `type`==`ap`, MxTunnel status, up / down
-    node : str
+      When `type`==`ap`, MxTunnel status, up / down.
+    node : str{'node0', 'node1'}
+      When `type`==`gateway`. enum: `node0`, `node1`
     node0_mac : str
     node1_mac : str
     power_constrained : bool
+    radius_stats : str
     site_id : str
+    stats : bool
     t128agent_version : str
-    version : str
     type : str{'ap', 'gateway', 'switch'}, default: ap
       Type of device. enum: `ap`, `gateway`, `switch`
+    version : str
     limit : int, default: 100
     start : str
     end : str
@@ -597,26 +596,24 @@ def searchOrgDevices(
 
     uri = f"/api/v1/orgs/{org_id}/devices/search"
     query_params: dict[str, str] = {}
-    if band_24_bandwidth:
-        query_params["band_24_bandwidth"] = str(band_24_bandwidth)
     if band_24_channel:
         query_params["band_24_channel"] = str(band_24_channel)
-    if band_24_power:
-        query_params["band_24_power"] = str(band_24_power)
-    if band_5_bandwidth:
-        query_params["band_5_bandwidth"] = str(band_5_bandwidth)
     if band_5_channel:
         query_params["band_5_channel"] = str(band_5_channel)
-    if band_5_power:
-        query_params["band_5_power"] = str(band_5_power)
-    if band_6_bandwidth:
-        query_params["band_6_bandwidth"] = str(band_6_bandwidth)
     if band_6_channel:
         query_params["band_6_channel"] = str(band_6_channel)
+    if band_24_bandwidth:
+        query_params["band_24_bandwidth"] = str(band_24_bandwidth)
+    if band_5_bandwidth:
+        query_params["band_5_bandwidth"] = str(band_5_bandwidth)
+    if band_6_bandwidth:
+        query_params["band_6_bandwidth"] = str(band_6_bandwidth)
+    if band_24_power:
+        query_params["band_24_power"] = str(band_24_power)
+    if band_5_power:
+        query_params["band_5_power"] = str(band_5_power)
     if band_6_power:
         query_params["band_6_power"] = str(band_6_power)
-    if cpu:
-        query_params["cpu"] = str(cpu)
     if clustered:
         query_params["clustered"] = str(clustered)
     if eth0_port_speed:
@@ -637,10 +634,6 @@ def searchOrgDevices(
         query_params["lldp_mgmt_addr"] = str(lldp_mgmt_addr)
     if lldp_port_id:
         query_params["lldp_port_id"] = str(lldp_port_id)
-    if lldp_power_allocated:
-        query_params["lldp_power_allocated"] = str(lldp_power_allocated)
-    if lldp_power_draw:
-        query_params["lldp_power_draw"] = str(lldp_power_draw)
     if lldp_system_desc:
         query_params["lldp_system_desc"] = str(lldp_system_desc)
     if lldp_system_name:
@@ -663,14 +656,18 @@ def searchOrgDevices(
         query_params["node1_mac"] = str(node1_mac)
     if power_constrained:
         query_params["power_constrained"] = str(power_constrained)
+    if radius_stats:
+        query_params["radius_stats"] = str(radius_stats)
     if site_id:
         query_params["site_id"] = str(site_id)
+    if stats:
+        query_params["stats"] = str(stats)
     if t128agent_version:
         query_params["t128agent_version"] = str(t128agent_version)
-    if version:
-        query_params["version"] = str(version)
     if type:
         query_params["type"] = str(type)
+    if version:
+        query_params["version"] = str(version)
     if limit:
         query_params["limit"] = str(limit)
     if start: