Refactor device utility functions to use WebSocketWrapper for asynchronous operations

- Updated clear_sessions, clear_mac_table, and clear_learned_mac functions to utilize WebSocketWrapper for handling API calls and WebSocket events.
- Enhanced logging for debugging purposes in various functions including ping, traceroute, and OSPF commands.
- Removed synchronous trigger handling and replaced it with asynchronous WebSocket handling across multiple device utility functions.
- Updated version number in uv.lock to 0.61.1.

Author: tmunzer-AIDE

README.md

@@ -35,6 +35,10 @@ A comprehensive Python package to interact with the Mist Cloud APIs, built from
     - [Callbacks](#callbacks)
     - [Available Channels](#available-channels)
     - [Usage Patterns](#usage-patterns)
+- [Async Usage](#async-usage)
+    - [Running API Calls Asynchronously](#running-api-calls-asynchronously)
+    - [Concurrent API Calls](#concurrent-api-calls)
+    - [Combining with Device Utilities](#combining-with-device-utilities)
 - [Device Utilities](#device-utilities)
     - [Supported Devices](#supported-devices)
     - [Usage](#device-utilities-usage)
@@ -63,9 +67,10 @@ Support for all Mist cloud instances worldwide:
 
 ### Core Features
 - **Complete API Coverage**: Auto-generated from OpenAPI specs
+- **Async Support**: Run any API call asynchronously with `mistapi.arun()` — no changes to existing code
 - **Automatic Pagination**: Built-in support for paginated responses
 - **WebSocket Streaming**: Real-time event streaming for devices, clients, and location data
-- **Device Diagnostics**: High-level utilities for ping, traceroute, ARP, BGP, OSPF, and more
+- **Device Diagnostics**: High-level, non-blocking utilities for ping, traceroute, ARP, BGP, OSPF, and more
 - **Error Handling**: Detailed error responses and logging
 - **Proxy Support**: HTTP/HTTPS proxy configuration
 - **Log Sanitization**: Automatic redaction of sensitive data in logs
@@ -492,6 +497,82 @@ events = mistapi.api.v1.orgs.clients.searchOrgClientsEvents(
 
 ---
 
+## Async Usage
+
+All API functions in `mistapi.api.v1` are synchronous by default. To use them in an `asyncio` context (e.g., FastAPI, aiohttp, or any async application) without blocking the event loop, use `mistapi.arun()`.
+
+`arun()` wraps any sync mistapi function in `asyncio.to_thread()`, running the blocking HTTP request in a thread pool while the event loop continues. No changes are needed to the existing API functions.
+
+### Running API Calls Asynchronously
+
+```python
+import asyncio
+import mistapi
+from mistapi.api.v1.sites import devices
+
+apisession = mistapi.APISession(env_file="~/.mist_env")
+apisession.login()
+
+async def main():
+    # Wrap any sync API call with mistapi.arun()
+    response = await mistapi.arun(
+        devices.listSiteDevices, apisession, site_id
+    )
+    print(response.data)
+
+asyncio.run(main())
+```
+
+### Concurrent API Calls
+
+Use `asyncio.gather()` to run multiple API calls concurrently:
+
+```python
+import asyncio
+import mistapi
+from mistapi.api.v1.orgs import orgs
+from mistapi.api.v1.sites import devices
+
+async def main():
+    org_info, site_devices = await asyncio.gather(
+        mistapi.arun(orgs.getOrg, apisession, org_id),
+        mistapi.arun(devices.listSiteDevices, apisession, site_id),
+    )
+    print(f"Org: {org_info.data['name']}")
+    print(f"Devices: {len(site_devices.data)}")
+
+asyncio.run(main())
+```
+
+### Combining with Device Utilities
+
+Device utility functions are already non-blocking and return a `UtilResponse` that supports `await`. You can mix `arun()` for API calls and `await` for device utilities:
+
+```python
+import asyncio
+import mistapi
+from mistapi.api.v1.sites import devices
+from mistapi.device_utils import ex
+
+async def main():
+    # Device utility — already non-blocking, supports await
+    response = ex.retrieveArpTable(apisession, site_id, device_id)
+
+    # API call — use arun() to avoid blocking the event loop
+    device_info = await mistapi.arun(
+        devices.getSiteDevice, apisession, site_id, device_id
+    )
+    print(f"Device: {device_info.data['name']}")
+
+    # Await the device utility result
+    await response
+    print(f"ARP entries: {len(response.ws_data)}")
+
+asyncio.run(main())
+```
+
+---
+
 ## WebSocket Streaming
 
 The package provides a WebSocket client for real-time event streaming from the Mist API (`wss://{host}/api-ws/v1/stream`). Authentication is handled automatically using the same session credentials (API token or login/password).
@@ -533,7 +614,7 @@ ws.connect()
 |-------|---------|-------------|
 | `mistapi.websockets.orgs.InsightsEvents` | `/orgs/{org_id}/insights/summary` | Real-time insights events for an organization |
 | `mistapi.websockets.orgs.MxEdgesStatsEvents` | `/orgs/{org_id}/stats/mxedges` | Real-time MX edges stats for an organization |
-| `mistapi.websockets.orgs.MxEdgesUpgradesEvents` | `/orgs/{org_id}/mxedges` | Real-time MX edges upgrades events for an organization |
+| `mistapi.websockets.orgs.MxEdgesEvents` | `/orgs/{org_id}/mxedges` | Real-time MX edges events for an organization |
 
 #### Site Channels
 
@@ -542,7 +623,7 @@ ws.connect()
 | `mistapi.websockets.sites.ClientsStatsEvents` | `/sites/{site_id}/stats/clients` | Real-time clients stats for a site |
 | `mistapi.websockets.sites.DeviceCmdEvents` | `/sites/{site_id}/devices/{device_id}/cmd` | Real-time device command events for a site |
 | `mistapi.websockets.sites.DeviceStatsEvents` | `/sites/{site_id}/stats/devices` | Real-time device stats for a site |
-| `mistapi.websockets.sites.DeviceUpgradesEvents` | `/sites/{site_id}/devices` | Real-time device upgrades events for a site |
+| `mistapi.websockets.sites.DeviceEvents` | `/sites/{site_id}/devices` | Real-time device events for a site |
 | `mistapi.websockets.sites.MxEdgesStatsEvents` | `/sites/{site_id}/stats/mxedges` | Real-time MX edges stats for a site |
 | `mistapi.websockets.sites.PcapEvents` | `/sites/{site_id}/pcap` | Real-time PCAP events for a site |
 

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mistapi"
-version = "0.61.0"
+version = "0.61.1"
 authors = [{ name = "Thomas Munzer", email = "tmunzer@juniper.net" }]
 description = "Python package to simplify the Mist System APIs usage"
 keywords = ["Mist", "Juniper", "API"]

src/mistapi/__api_request.py

@@ -17,6 +17,7 @@
 import json
 import os
 import re
+import threading
 import time
 import urllib.parse
 from collections.abc import Callable
@@ -45,6 +46,7 @@ def __init__(self) -> None:
         self._count: int = 0
         self._apitoken: list[str] = []
         self._apitoken_index: int = -1
+        self._token_lock: threading.Lock = threading.Lock()
 
     def get_request_count(self):
         """
@@ -86,40 +88,41 @@ def _log_proxy(self) -> None:
             )
 
     def _next_apitoken(self) -> None:
-        logger.info("apirequest:_next_apitoken:rotating API Token")
-        logger.debug(
-            "apirequest:_next_apitoken:current API Token is %s...%s",
-            self._apitoken[self._apitoken_index][:4],
-            self._apitoken[self._apitoken_index][-4:],
-        )
-        new_index = self._apitoken_index + 1
-        if new_index >= len(self._apitoken):
-            new_index = 0
-        if self._apitoken_index != new_index:
-            self._apitoken_index = new_index
-            self._session.headers.update(
-                {"Authorization": "Token " + self._apitoken[self._apitoken_index]}
-            )
+        with self._token_lock:
+            logger.info("apirequest:_next_apitoken:rotating API Token")
             logger.debug(
-                "apirequest:_next_apitoken:new API Token is %s...%s",
+                "apirequest:_next_apitoken:current API Token is %s...%s",
                 self._apitoken[self._apitoken_index][:4],
                 self._apitoken[self._apitoken_index][-4:],
             )
-        else:
-            logger.critical(" /!\\ API TOKEN CRITICAL ERROR /!\\")
-            logger.critical(
-                " There is no other API Token to use and the API"
-                " Request limit has been reached for the current one"
-            )
-            logger.critical(
-                " For large organization, it is recommended to configure"
-                " multiple API Tokens (comma separated list) to avoid this issue"
-            )
-            raise RuntimeError(
-                "API rate limit reached and no other API Token available. "
-                "For large organizations, configure multiple API Tokens "
-                "(comma separated list) to avoid this issue."
-            )
+            new_index = self._apitoken_index + 1
+            if new_index >= len(self._apitoken):
+                new_index = 0
+            if self._apitoken_index != new_index:
+                self._apitoken_index = new_index
+                self._session.headers.update(
+                    {"Authorization": "Token " + self._apitoken[self._apitoken_index]}
+                )
+                logger.debug(
+                    "apirequest:_next_apitoken:new API Token is %s...%s",
+                    self._apitoken[self._apitoken_index][:4],
+                    self._apitoken[self._apitoken_index][-4:],
+                )
+            else:
+                logger.critical(" /!\\ API TOKEN CRITICAL ERROR /!\\")
+                logger.critical(
+                    " There is no other API Token to use and the API"
+                    " Request limit has been reached for the current one"
+                )
+                logger.critical(
+                    " For large organization, it is recommended to configure"
+                    " multiple API Tokens (comma separated list) to avoid this issue"
+                )
+                raise RuntimeError(
+                    "API rate limit reached and no other API Token available. "
+                    "For large organizations, configure multiple API Tokens "
+                    "(comma separated list) to avoid this issue."
+                )
 
     def _gen_query(self, query: dict[str, str] | None) -> str:
         if not query:
@@ -344,6 +347,7 @@ def mist_post_file(
             multipart_form_data,
         )
         generated_multipart_form_data: dict[str, Any] = {}
+        opened_files: list = []
         for key in multipart_form_data:
             logger.debug(
                 "apirequest:mist_post_file:multipart_form_data:%s = %s",
@@ -358,6 +362,7 @@ def mist_post_file(
                             multipart_form_data[key],
                         )
                         f = open(multipart_form_data[key], "rb")
+                        opened_files.append(f)
                         generated_multipart_form_data[key] = (
                             os.path.basename(multipart_form_data[key]),
                             f,
@@ -392,4 +397,8 @@ def _do_post_file():
             )
             return resp
 
-        return self._request_with_retry("mist_post_file", _do_post_file, url)
+        try:
+            return self._request_with_retry("mist_post_file", _do_post_file, url)
+        finally:
+            for f in opened_files:
+                f.close()

src/mistapi/__api_response.py

@@ -51,7 +51,7 @@ def __init__(
             console.debug(f"Response Status Code: {response.status_code}")
 
             try:
-                self.raw_data = str(response.content)
+                self.raw_data = response.text
                 self.data = response.json()
                 self._check_next()
                 logger.debug("apiresponse:__init__:HTTP response processed")

src/mistapi/__init__.py

@@ -17,6 +17,8 @@
 from mistapi.__version import __author__ as __author__
 from mistapi.__version import __version__ as __version__
 
+import asyncio as _asyncio
+from collections.abc import Callable as _Callable
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -41,3 +43,43 @@ def __getattr__(name: str):
         globals()[name] = module
         return module
     raise AttributeError(f"module 'mistapi' has no attribute {name!r}")
+
+
+async def arun(func: _Callable, *args, **kwargs):
+    """
+    Run any sync mistapi function without blocking the event loop.
+
+    Wraps the function call in ``asyncio.to_thread()`` so the blocking
+    HTTP request runs in a thread pool while the event loop continues.
+
+    EXAMPLE
+    -----------
+    ::
+
+        import asyncio
+        import mistapi
+        from mistapi.api.v1.sites import devices
+
+        async def main():
+            session = mistapi.APISession(env_file="~/.mist_env")
+            session.login()
+
+            response = await mistapi.arun(
+                devices.listSiteDevices, session, site_id
+            )
+            print(response.data)
+
+        asyncio.run(main())
+
+    PARAMS
+    -----------
+    func : callable
+        Any sync mistapi API function.
+    *args, **kwargs
+        Arguments forwarded to *func*.
+
+    RETURNS
+    -----------
+    The return value of *func* (typically ``APIResponse``).
+    """
+    return await _asyncio.to_thread(func, *args, **kwargs)

src/mistapi/__version.py

@@ -1,2 +1,2 @@
-__version__ = "0.61.0"
+__version__ = "0.61.1"
 __author__ = "Thomas Munzer <tmunzer@juniper.net>"

src/mistapi/api/v1/sites/sle.py

@@ -19,7 +19,7 @@
 @deprecation.deprecated(
     deprecated_in="0.59.2",
     removed_in="0.65.0",
-    current_version="0.61.0",
+    current_version="0.61.1",
     details="function replaced with getSiteSleClassifierSummaryTrend",
 )
 def getSiteSleClassifierDetails(
@@ -691,7 +691,7 @@ def listSiteSleImpactedWirelessClients(
 @deprecation.deprecated(
     deprecated_in="0.59.2",
     removed_in="0.65.0",
-    current_version="0.61.0",
+    current_version="0.61.1",
     details="function replaced with getSiteSleSummaryTrend",
 )
 def getSiteSleSummary(

src/mistapi/device_utils/__init__.py

@@ -18,7 +18,7 @@
 --------------------------------------
 Import device-specific modules for a clean, organized API:
 
-    from mistapi.utils import ap, ex, srx, ssr
+    from mistapi.device_utils import ap, ex, srx, ssr
 
     # Use device-specific utilities
     ap.ping(session, site_id, device_id, host)
@@ -30,15 +30,6 @@
 - ex:  Juniper EX Switches
 - srx: Juniper SRX Firewalls
 - ssr: Juniper Session Smart Routers
-
-Function-Based Modules (Legacy)
----------------------------------
-Original organization by function type (still available):
-
-    from mistapi.utils import arp, bgp, dhcp, mac, port, routes, tools
-
-Available modules: arp, bgp, bpdu, dhcp, dns, dot1x, mac, policy, port, routes,
-                   service_path, tools
 """
 
 # Device-specific modules (recommended)