async-timer 1.0.1__tar.gz → 1.0.3__tar.gz

{async_timer-1.0.1 → async_timer-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: async-timer
-Version: 1.0.1
+Version: 1.0.3
 Summary: The missing Python async timer.
 License: MIT
 Keywords: async,timer
@@ -48,16 +48,62 @@ This package is particularly useful for tasks like automatically updating caches
 
 ## Example Usage
 
+### FastAPI
+
+This snippet starts fastapi webserver with the `refresh_db` function being executed every 5 seconds, refresing a shared `DB_CACHE` object.
+
+```python
+
+import contextlib
+import time
+
+import uvicorn
+from fastapi import FastAPI
+
+import async_timer
+
+DB_CACHE = {"initialised": False}
+
+
+async def refresh_db():
+    global DB_CACHE
+    DB_CACHE |= {"initialised": True, "cur_value": time.time()}
+
+
+@contextlib.asynccontextmanager
+async def lifespan(_app: FastAPI):
+    async with async_timer.Timer(delay=5, target=refresh_db) as timer:
+        await timer.wait(hit_count=1)  # block until the timer triggers at least once
+        yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World", "db_cache": DB_CACHE}
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+```
+
+### join()
 ```python
 
 import async_timer
 
-# Simple timer example
 timer = async_timer.Timer(12, target=lambda: 42)
 timer.start()
-val = await timer.join()  # `val` will be 42 after 12 seconds
+val = await timer.join()  # `val` will be set to 42 after 12 seconds
+```
 
+### for loop
+```python
 # Async for loop example
+import async_timer
 import time
 with async_timer.Timer(14, target=time.time) as timer:
     async for time_rv in timer:

{async_timer-1.0.1 → async_timer-1.0.3}/README.md

@@ -26,16 +26,62 @@ This package is particularly useful for tasks like automatically updating caches
 
 ## Example Usage
 
+### FastAPI
+
+This snippet starts fastapi webserver with the `refresh_db` function being executed every 5 seconds, refresing a shared `DB_CACHE` object.
+
+```python
+
+import contextlib
+import time
+
+import uvicorn
+from fastapi import FastAPI
+
+import async_timer
+
+DB_CACHE = {"initialised": False}
+
+
+async def refresh_db():
+    global DB_CACHE
+    DB_CACHE |= {"initialised": True, "cur_value": time.time()}
+
+
+@contextlib.asynccontextmanager
+async def lifespan(_app: FastAPI):
+    async with async_timer.Timer(delay=5, target=refresh_db) as timer:
+        await timer.wait(hit_count=1)  # block until the timer triggers at least once
+        yield
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+@app.get("/")
+async def root():
+    return {"message": "Hello World", "db_cache": DB_CACHE}
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)
+
+```
+
+### join()
 ```python
 
 import async_timer
 
-# Simple timer example
 timer = async_timer.Timer(12, target=lambda: 42)
 timer.start()
-val = await timer.join()  # `val` will be 42 after 12 seconds
+val = await timer.join()  # `val` will be set to 42 after 12 seconds
+```
 
+### for loop
+```python
 # Async for loop example
+import async_timer
 import time
 with async_timer.Timer(14, target=time.time) as timer:
     async for time_rv in timer:

{async_timer-1.0.1 → async_timer-1.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "async-timer"
-version = "v1.0.1"
+version = "v1.0.3"
 description = "The missing Python async timer."
 authors = ["Ilya O. <vrghost@gmail.com>"]
 license = "MIT"
@@ -66,7 +66,7 @@ line-length = 88
 
 [tool.ruff.isort]
 order-by-type = true
-known-first-party = ["tc_rrf", ]
+known-first-party = ["async_timer", ]
 forced-separate = ["tests"]
 
 [tool.black]

{async_timer-1.0.1 → async_timer-1.0.3}/src/async_timer/timer.py

@@ -2,14 +2,20 @@
 import asyncio
 import inspect
 import logging
-import sys
 import typing
 
 logger = logging.getLogger(__name__)
 T = typing.TypeVar("T")
+TimerMainTaskT = typing.Union[
+    typing.Callable[[], T],
+    typing.Callable[[], typing.Coroutine[typing.Any, typing.Any, T]],
+    typing.Callable[[], typing.AsyncGenerator[T, typing.Any]],
+    typing.Callable[[], typing.Generator[T, typing.Any, typing.Any]],
+]
+TimerCallbackT = typing.Callable[["Timer[T]", TimerMainTaskT[T]], None]
 
 
-class FanoutRv:
+class FanoutRv(typing.Generic[T]):
     """An object that shares a result actoss all waiters"""
 
     lock: asyncio.Lock
@@ -19,20 +25,20 @@ class FanoutRv:
         self.futures = []
         self.lock = asyncio.Lock()
 
-    async def wait(self):
+    async def wait(self) -> T:
         """Wait for result to be posted"""
         future = asyncio.get_running_loop().create_future()
         async with self.lock:
             self.futures.append(future)
         return await future
 
-    async def send_result(self, result):
+    async def send_result(self, result: T):
         async with self.lock:
             for future in self.futures:
                 future.set_result(result)
             self.futures.clear()
 
-    async def send_exception(self, exc):
+    async def send_exception(self, exc: Exception):
         async with self.lock:
             for future in self.futures:
                 future.set_exception(exc)
@@ -45,30 +51,36 @@ class FanoutRv:
             self.futures.clear()
 
 
-def _default_main_loop_exception_callback(exc_type, exc_val, exc_tb):
+def _noop_cb(*_, **__):
+    pass
+
+
+def _default_main_loop_exception_callback(*_, **__):
     logger.exception("An unexpected exception in the timer loop.")
 
 
-class Timer:
+class Timer(typing.Generic[T]):
     delay: float
-    target: typing.Callable[[], T]
+    hit_count: int = 0  # Number of times the timer has run so far
+    target: TimerMainTaskT[T]
 
-    result_fanout: FanoutRv
+    result_fanout: FanoutRv[T]
     main_task: typing.Optional[asyncio.Task] = None
-    exception_callback: typing.Callable[[typing.Any, typing.Any, typing.Any], None]
+    exception_callback: TimerCallbackT[T]
+    cancel_callback: TimerCallbackT[T]
 
     def __init__(
         self,
         delay: float,
-        target: typing.Callable[[], T],
-        exc_cb: typing.Callable[
-            [typing.Any, typing.Any, typing.Any], None
-        ] = _default_main_loop_exception_callback,
+        target: TimerMainTaskT[T],
+        exc_cb: TimerCallbackT[T] = _default_main_loop_exception_callback,
+        cancel_cb: TimerCallbackT[T] = _noop_cb,
     ):
         self.delay = delay
         self.target = target
         self.result_fanout = FanoutRv()
         self.exception_callback = exc_cb
+        self.cancel_callback = cancel_cb
 
     def start(self):
         """Schedule the timer to run."""
@@ -82,17 +94,17 @@ class Timer:
         """Return `True` if the timer is currently scheduled"""
         return (self.main_task is not None) and (not self.main_task.done())
 
-    async def __aenter__(self):
+    async def __aenter__(self) -> "Timer[T]":
         self.start()
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
         await self.cancel()
 
-    def __aiter__(self):
+    def __aiter__(self) -> typing.AsyncIterator[T]:
         return self
 
-    async def join(self):
+    async def join(self) -> T:
         """Wait for the next tick of the timer"""
         if not self.is_running():
             raise asyncio.CancelledError("The timer is not running.")
@@ -100,7 +112,30 @@ class Timer:
             await self.result_fanout.wait()
         )  # this can raise `asyncio.CancelledError`
 
-    async def __anext__(self):
+    async def wait(
+        self, /, hit_count: int = None, hits: int = None
+    ) -> typing.Optional[T]:
+        """
+        Wait for the timer to reach certain hit count
+            or wait for a certain number of hits.
+
+        Returns the last generated result IF there was a need to wait.
+        Returns `None` otherwise.
+        """
+        if hit_count is not None:
+            target_hit_count = max(0, hit_count)
+        elif hits is not None:
+            target_hit_count = self.hit_count + max(0, hits)
+        else:
+            raise RuntimeError("Please provide either `hits` or `hit_count`")
+        need_to_wait_for = target_hit_count - self.hit_count
+        last_rv = None
+        while need_to_wait_for > 0:
+            last_rv = await self.join()
+            need_to_wait_for -= 1
+        return last_rv
+
+    async def __anext__(self) -> T:
         try:
             return await self.join()
         except asyncio.CancelledError as err:
@@ -108,7 +143,7 @@ class Timer:
 
     def _maybe_detect_generator(
         self, target_rv
-    ) -> typing.Tuple[typing.Any, typing.Callable[[], T]]:
+    ) -> typing.Tuple[T, typing.Callable[[], T]]:
         """Check if the value returned by the `self.target` call is a
         kind of generator (sync or async).
 
@@ -149,19 +184,21 @@ class Timer:
                         rv = await next_val
                     else:
                         rv = next_val
-                    if isinstance(rv, (StopIteration, StopAsyncIteration)):
-                        break
+                except (StopIteration, StopAsyncIteration):
+                    break
                 except Exception as err:
                     await self.result_fanout.send_exception(err)
-                    self.exception_callback(*sys.exc_info())
+                    self.exception_callback(self, self.target)
                     break
                 else:
                     await self.result_fanout.send_result(rv)
                 first_iter = False
+                self.hit_count += 1
                 await asyncio.sleep(self.delay)
         finally:
             # Main loop finished - cancel all watchers
             await self.result_fanout.cancel()
+            self.cancel_callback(self, self.target)
 
     async def cancel(self):
         """Unshedule the timer"""