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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: async-timer
-Version: 1.0.2
+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.2 → 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.2 → async_timer-1.0.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "async-timer"
-version = "v1.0.2"
+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.2 → async_timer-1.0.3}/src/async_timer/timer.py

@@ -61,6 +61,7 @@ def _default_main_loop_exception_callback(*_, **__):
 
 class Timer(typing.Generic[T]):
     delay: float
+    hit_count: int = 0  # Number of times the timer has run so far
     target: TimerMainTaskT[T]
 
     result_fanout: FanoutRv[T]
@@ -111,6 +112,29 @@ class Timer(typing.Generic[T]):
             await self.result_fanout.wait()
         )  # this can raise `asyncio.CancelledError`
 
+    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()
@@ -169,6 +193,7 @@ class Timer(typing.Generic[T]):
                 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