Customize timeout for the call (#5)

* customize timeout for the call

.github/workflows/test.yml

@@ -1,6 +1,11 @@
 name: Test
 
-on: [push, pull_request]
+on:
+  pull_request:
+    branches:
+      - '*'
+  workflow_dispatch:
+
 
 jobs:
   analyse:

README.md

@@ -25,13 +25,18 @@ https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md
   * [Register AVL Events](#register-avl-events)
   * [On login/logout](#on-loginlogout)
   * [AVL Events Handling](#avl-events-handling)
+    * [Register AVL Events handler](#register-avl-events-handlers)
+    * [Remove AVL Events handler](#remove-avl-events-handlers)
+    * [Disposable handlers](#disposable-handlers)
 * [Exceptions Handling](#exceptions-handling)
   * [Get exception results, batch exceptions](#exceptions-handling-batch)
 * [Quick API Help](#quick-api-help)
 * [Advanced](#advanced-usage)
   * [Limitations](#limitations)
   * [Prevent polling auto logout](#prevent-polling-logout)
   * [Critical requests execution (Render, Reports, Messages)](#critical-requests-execution)
+    * [Async session lock](#async-session-lock)
+    * [Timeout for API call](#timeout-for-api-call)
   * [Extending AIO Wialon](#extending-aio-wialon)
   * [Debugging](#debugging)
 
@@ -43,7 +48,7 @@ pip install py-aiowialon
 ```
 
 ## Start Polling
-Open session and start poll AVL events immediately
+Open session and start poll AVL events immediately.
 [Look the Wialon Events section](#wialon-events) to see how we can handle AVL Events on polling
 ```python
 import asyncio
@@ -236,6 +241,7 @@ async def on_session_close(session_logout):
 After polling start and AVL Items registered for polling we can handle the AVL Events.
 Use `@wialon.avl_event_handler()` decorator
 
+#### Register AVL Events handlers
 ```python
 from aiowialon import AvlEvent
 
@@ -258,6 +264,23 @@ async def unit_734455_event(event: AvlEvent):
 > [!NOTE]
 > Register handlers in an order in which filters have to be applied. If some handler catched the event, next handler in order will never do.
 
+#### Remove AVL Events handlers
+```python
+# use them as you need
+wialon.remove_avl_event_handler('handler_name')
+wialon.remove_avl_event_handler(handler_func)
+```
+
+#### Disposable handlers
+Use `@wialon.avl_event_once` to be certain that handler will be removed immediately after single execution
+```python
+@wialon.avl_event_handler()
+@wialon.avl_event_once
+async def unit_event(event: AvlEvent):
+    print("Handler got event:", event)
+```
+
+
 ## Exceptions Handling
 The avl_event_handler suppress the callback's WialonError exceptions to protect app to be closed on unexpected behaviour
 So if u want to handle some specific WialonError, do it in handler's callback scope
@@ -325,10 +348,12 @@ wialon.start_polling(token=TOKEN, logout_finally=False)
 ```
 
 ### Critical requests execution
+
+#### Async session lock
 Some requests to services like `Render`, `Reports`, `Messages` requires blocking other requests to be executed together per single session.
-* Use the `@wialon.lock_session` decorator to block async loop till your operation done
-* You can apply `@wialon.session_lock` also for handlers
-* You can use `@wialon.session_lock` inside the methods when [inheriting Wialon](#extending-aio-wialon)
+* Use the `@Wialon.lock_session` decorator to block async loop till your operation done
+* You can apply `@Wialon.session_lock` also for handlers
+* You can use `@Wialon.session_lock` inside the methods when [inheriting Wialon](#extending-aio-wialon)
 
 ```python
 import asyncio
@@ -367,6 +392,32 @@ async def unit_event(event: AvlEvent):
 ```
 
 
+#### Timeout for API call
+Some API calls requires special timeouts, cause them are processing long. 
+Default timeout for aiohttp request is 5 seconds.
+You can set custom timeout on some call executing.
+It mostly usefull with `@Wialon.session_lock`
+```python
+@wialon.avl_event_handler()
+@wialon.session_lock
+async def unit_event(event: AvlEvent):
+    try:
+        await wialon.wait(wialon.messages_load_last(
+            itemId=event.data.i,
+            lastTime=event.tm,
+            lastCount=10000,
+            flags=0x0000,
+            flagsMask=0xFF00,
+            loadCount=10000
+        ), 10)
+    except (TimeoutError, WialonError) as err:
+        print(err)
+    for i in range(5):
+        print("Waiting exclusive operation", i, "item:", event.data.i)
+        await asyncio.sleep(1)
+```
+
+
 ### Extending AIO Wialon
 Inherit from `Wialon` class to add your custom logic and behaviour
 * You can directly use `Wialon.request` to make requests to special endpoints

aiowialon/__init__.py

@@ -16,7 +16,7 @@
     "Mike Turchunovich",
     "Dmytro Yaroshenko",
 ]
-__version__ = "1.3.2"
+__version__ = "1.3.3"
 
 from aiowialon.logger import *
 from aiowialon.utils import *

aiowialon/api.py

@@ -7,6 +7,7 @@
 import json
 import warnings
 from contextlib import suppress
+from functools import wraps
 from typing import Callable, Coroutine, Dict, Optional, Any, Union, Literal, List
 from urllib.parse import urljoin
 
@@ -167,6 +168,19 @@ def wrapper(callback: AvlEventCallback):
 
         return wrapper
 
+    def avl_event_once(self, func: Optional[Callable[..., Coroutine[Any, Any, Any]]] = None
+                       ) -> Callable[..., Coroutine[Any, Any, Any]]:
+        """Be certain that handler will be removed after single execution"""
+
+        @wraps(func)
+        async def wrapper(*args, **kwargs) -> Any:
+            try:
+                return await func(*args, **kwargs)
+            finally:
+                self.remove_avl_event_handler(func)
+
+        return wrapper
+
     def remove_avl_event_handler(self, callback: Union[str, AvlEventCallback]):
         """
         Manually remove AVL event handler
@@ -402,6 +416,16 @@ async def request(self, action_name: str, url: str, payload: Any) -> Any:
                         logger.exception(e)
                         raise
 
+    async def wait(self, call: Coroutine[Any, Any, Any], timeout: Optional[float] = None) -> Any:
+        """Decorate a Call with specified request timeout"""
+        prev_timeout = self.timeout
+        if timeout:
+            self.timeout = timeout
+        try:
+            return await call
+        finally:
+            self.timeout = prev_timeout
+
     @staticmethod
     def help(service_name: str, action_name: str) -> None:
         """

aiowialon/api.pyi

@@ -19,6 +19,7 @@ class Wialon:
     def on_session_open(self, callback: LoginCallback | None = None) -> LoginCallback | None: ...
     def on_session_close(self, callback: LogoutCallback | None = None) -> LogoutCallback | None: ...
     def avl_event_handler(self, filter_: AvlEventFilter | None = None) -> Callable: ...
+    def avl_event_once(self, func: Callable[..., Coroutine[Any, Any, Any]] | None = None) -> Callable[..., Coroutine[Any, Any, Any]]: ...
     def remove_avl_event_handler(self, callback: str | AvlEventCallback): ...
     async def start_polling(self, timeout: int | float = 2, logout_finally: bool = True, **params: Unpack[LoginParams]) -> None: ...
     async def stop_polling(self, logout: bool = False) -> None: ...
@@ -371,4 +372,6 @@ class Wialon:
     References to requests method
     https://sdk.wialon.com/wiki/en/sidebar/remoteapi/apiref/requests/requests
     """
+
+    async def apps_list(self, *args: Any, **params: Any) -> Any: ...
     # TODO:

examples/aiolock.py

@@ -1,7 +1,8 @@
 import asyncio
 import logging
+from datetime import datetime
 
-from aiowialon import Wialon, flags, AvlEvent
+from aiowialon import Wialon, flags, AvlEvent, WialonError
 
 logging.basicConfig(level=logging.INFO)
 
@@ -14,6 +15,7 @@ async def locked_task():
             for i in range(5):
                 print("Waiting lock release", i)
                 await asyncio.sleep(1)
+
         return await locked_task()
 
 
@@ -37,15 +39,22 @@ async def register_avl_events(session_login):
 
 
 @wialon.avl_event_handler()
-@wialon.session_lock  # exclusive session lock for callback's frame
+@wialon.session_lock
 async def unit_event(event: AvlEvent):
-    await wialon.core_search_item(id=event.data.i, flags=1)
-    print("Handler got event:", event)
+    try:
+        await wialon.wait(wialon.messages_load_last(
+            itemId=event.data.i,
+            lastTime=event.tm,
+            lastCount=10000,
+            flags=0x0000,
+            flagsMask=0xFF00,
+            loadCount=10000
+        ), 10)
+    except (TimeoutError, WialonError) as err:
+        print(err)
     for i in range(5):
         print("Waiting exclusive operation", i, "item:", event.data.i)
         await asyncio.sleep(1)
-    # remove handler
-    # wialon.remove_avl_event_handler(unit_event)
 
 
 if __name__ == "__main__":

test/aiowait.py

@@ -0,0 +1,29 @@
+import asyncio
+
+
+class A:
+
+    def __init__(self):
+        self.timeout = 2
+
+    async def wait(self, call, timeout):
+        prev_timeout = self.timeout
+        if timeout:
+            self.timeout = timeout
+        try:
+            return await call
+        finally:
+            self.timeout = prev_timeout
+
+a = A()
+
+async def c():
+    print(a.timeout)
+    await asyncio.sleep(3)
+
+async def f():
+    print(a.timeout)
+    await a.wait(c(), 10)
+    print(a.timeout)
+
+asyncio.run(f())