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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: async-timer
-Version: 1.0.3
+Version: 1.1.1
 Summary: The missing Python async timer.
 License: MIT
 Keywords: async,timer
@@ -45,6 +45,7 @@ This package is particularly useful for tasks like automatically updating caches
   * Asynchronous generators
 * **Wait for the Next Tick**: You can set it up so your program waits for the timer to do its thing, and then continues.
 * **Keep Getting Updates**: You can use it in a loop to keep getting updates every time the timer goes off.
+* **Cancel anytime**: The timer object can be stopped at any time either explicitly by calling `stop()`/`cancel()` method OR it can stop automatically on an awaitable resolving (the `cancel_aws` constructor artument)
 
 ## Example Usage
 

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

@@ -23,6 +23,7 @@ This package is particularly useful for tasks like automatically updating caches
   * Asynchronous generators
 * **Wait for the Next Tick**: You can set it up so your program waits for the timer to do its thing, and then continues.
 * **Keep Getting Updates**: You can use it in a loop to keep getting updates every time the timer goes off.
+* **Cancel anytime**: The timer object can be stopped at any time either explicitly by calling `stop()`/`cancel()` method OR it can stop automatically on an awaitable resolving (the `cancel_aws` constructor artument)
 
 ## Example Usage
 

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

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "async-timer"
-version = "v1.0.3"
+version = "v1.1.1"
 description = "The missing Python async timer."
 authors = ["Ilya O. <vrghost@gmail.com>"]
 license = "MIT"

async_timer-1.1.1/src/async_timer/__init__.py

@@ -0,0 +1,2 @@
+from . import pacemaker, timer, traget_caller
+from .timer import Timer

async_timer-1.1.1/src/async_timer/pacemaker.py

@@ -0,0 +1,71 @@
+import asyncio
+import dataclasses
+import typing
+
+
+@dataclasses.dataclass()
+class ConfigurationChanged:
+    """An internal object that is returned when internal pacemaker state has changed"""
+
+
+class TimerPacemaker:
+    """A helper object that controls the timers' iterations."""
+
+    delay: float
+    _first_iter: bool = True
+    _running: bool = True
+    _cancel_futs: typing.List[asyncio.futures.Future]
+    _cancel_evt: asyncio.Event
+
+    def __init__(self, delay: float):
+        self.delay = delay
+        self._cancel_futs = []
+        self._cancel_evt = asyncio.Event()
+
+    def stop_on(self, aws: typing.Sequence[asyncio.Future]):
+        for el in aws:
+            fut = asyncio.ensure_future(el)
+            fut.add_done_callback(lambda _fut: self.stop())
+            self._cancel_futs.append(fut)
+
+    def stop(self):
+        """Stop the iterator."""
+        for fut in self._cancel_futs:
+            fut.cancel()
+        self._cancel_futs.clear()
+        self._cancel_evt.set()
+        self._running = False
+
+    def __aiter__(self):
+        """The core funtionality - return the iterator"""
+        return self
+
+    async def __anext__(self):
+        # Do not sleep at the first iter
+        # (so the timer hits the target function at startup)
+        if not self._running:
+            raise StopAsyncIteration()
+        elif self._first_iter:
+            self._first_iter = False
+        else:
+            try:
+                await self._try_wait(self.delay)
+            except StopAsyncIteration:
+                self.stop()
+                raise
+        return None
+
+    async def _try_wait(self, delay: float):
+        """Try waiting for the `delay`.
+
+        Raises `StopAsyncIteration` if the sleep was cancelled
+        """
+        try:
+            await asyncio.wait_for(self._cancel_evt.wait(), timeout=delay)
+        except asyncio.TimeoutError:
+            # Sleep succeeded
+            return None
+        # the cancel event was triggered if no timout was raised
+        assert self._cancel_evt.is_set()
+        # So, raise StopIteration
+        raise StopAsyncIteration()

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

@@ -1,9 +1,11 @@
 """Utility async io functions"""
 import asyncio
-import inspect
 import logging
+import time
 import typing
 
+import async_timer
+
 logger = logging.getLogger(__name__)
 T = typing.TypeVar("T")
 TimerMainTaskT = typing.Union[
@@ -11,6 +13,8 @@ TimerMainTaskT = typing.Union[
     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]],
+    typing.AsyncGenerator[T, typing.Any],
+    typing.Generator[T, typing.Any, typing.Any],
 ]
 TimerCallbackT = typing.Callable[["Timer[T]", TimerMainTaskT[T]], None]
 
@@ -57,10 +61,13 @@ def _noop_cb(*_, **__):
 
 def _default_main_loop_exception_callback(*_, **__):
     logger.exception("An unexpected exception in the timer loop.")
+    raise
 
 
 class Timer(typing.Generic[T]):
-    delay: float
+    """The main Timer object"""
+
+    iterator: "async_timer.pacemaker.TimerPacemaker"
     hit_count: int = 0  # Number of times the timer has run so far
     target: TimerMainTaskT[T]
 
@@ -75,12 +82,33 @@ class Timer(typing.Generic[T]):
         target: TimerMainTaskT[T],
         exc_cb: TimerCallbackT[T] = _default_main_loop_exception_callback,
         cancel_cb: TimerCallbackT[T] = _noop_cb,
+        cancel_aws: typing.Union[typing.Sequence[typing.Awaitable], None] = None,
+        start: bool = False,
     ):
-        self.delay = delay
-        self.target = target
+        """Create the Timer object.
+
+        Parameters:
+            `delay` - number of seconds between timer incovations
+            `target` - the callable the timer will be invoking at the `delay` period
+            `exc_cb` - a callback that the timer will call on exception
+            `cancel_cb` - callback the timer will call at cancellation
+            `cancel_aws` - a list of awaitables, where any
+                            one resolving cancels the timer
+        """
+        self.iterator = async_timer.pacemaker.TimerPacemaker(delay)
+        self.target_caller = async_timer.traget_caller.Caller(target)
         self.result_fanout = FanoutRv()
         self.exception_callback = exc_cb
         self.cancel_callback = cancel_cb
+        if cancel_aws:
+            self.iterator.stop_on(list(cancel_aws))
+        if start:
+            self.start()
+
+    @property
+    def delay(self) -> float:
+        """A shorthand to access timer firing delay"""
+        return self.iterator.delay
 
     def start(self):
         """Schedule the timer to run."""
@@ -113,26 +141,47 @@ class Timer(typing.Generic[T]):
         )  # this can raise `asyncio.CancelledError`
 
     async def wait(
-        self, /, hit_count: int = None, hits: int = None
+        self, /, hit_count: int = None, hits: int = None, timeout: float = None
     ) -> typing.Optional[T]:
         """
         Wait for the timer to reach certain hit count
             or wait for a certain number of hits.
 
+        Can raise `asyncio.TimeoutError` if there was a wait condition
+            and timeout specified and the wait did not manage to hit
+            the condition in time
+
+        Waits for the timer to stop if neither parameter is present.
+
         Returns the last generated result IF there was a need to wait.
         Returns `None` otherwise.
         """
+        start_time = time.monotonic()
+        timeout_left = timeout
+        infinite_wait = False
         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`")
+            target_hit_count = 0
+            infinite_wait = True
         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
+        try:
+            while infinite_wait or need_to_wait_for > 0:
+                last_rv = await asyncio.wait_for(self.join(), timeout_left)
+                need_to_wait_for -= 1
+                if timeout is not None:
+                    time_passed = time.monotonic() - start_time
+                    timeout_left = timeout - time_passed
+        except (asyncio.CancelledError, asyncio.TimeoutError):
+            # Cancelled/Timeout error is what we were waiting
+            # for in the infinite wait mode
+            if infinite_wait:
+                pass
+            else:
+                raise
         return last_rv
 
     async def __anext__(self) -> T:
@@ -141,72 +190,43 @@ class Timer(typing.Generic[T]):
         except asyncio.CancelledError as err:
             raise StopAsyncIteration() from err
 
-    def _maybe_detect_generator(
-        self, target_rv
-    ) -> typing.Tuple[T, typing.Callable[[], T]]:
-        """Check if the value returned by the `self.target` call is a
-        kind of generator (sync or async).
-
-        Returns a (this_iter_rv, new_callable) tuple
-        """
-        if inspect.isgenerator(target_rv):
-
-            def _lock_sync_gen_ctx(gen_src):
-                return lambda: next(gen_src)
-
-            get_next_val = _lock_sync_gen_ctx(target_rv)
-            rv = (get_next_val(), get_next_val)
-        elif inspect.isasyncgen(target_rv):
-
-            def _lock_async_gen_ctx(gen_src):
-                return lambda: gen_src.__anext__()
-
-            get_next_val = _lock_async_gen_ctx(target_rv)
-            rv = (get_next_val(), get_next_val)
-        else:
-            rv = (target_rv, None)
-        return rv
-
     async def _loop_callback_routine(self):
-        get_next_val = self.target
-        first_iter = True
         try:
-            while True:
+            async for _ in self.iterator:
                 try:
-                    next_val = get_next_val()
-                    if first_iter:
-                        (next_val, updated_get_next_val) = self._maybe_detect_generator(
-                            next_val
-                        )
-                        if updated_get_next_val is not None:
-                            get_next_val = updated_get_next_val
-                    if inspect.isawaitable(next_val):
-                        rv = await next_val
-                    else:
-                        rv = next_val
-                except (StopIteration, StopAsyncIteration):
+                    rv = await self.target_caller.next()
+                except StopAsyncIteration:
                     break
                 except Exception as err:
                     await self.result_fanout.send_exception(err)
-                    self.exception_callback(self, self.target)
+                    self.exception_callback(self, self.target_caller.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)
+            self.cancel_callback(self, self.target_caller.target)
 
     async def cancel(self):
         """Unshedule the timer"""
         if self.main_task:
             self.main_task.cancel()
             await self.result_fanout.cancel()
+            self.iterator.stop()
             self.main_task = None
 
     async def stop(self):
         """An alias to `cancel()`"""
         return await self.cancel()
+
+    def __repr__(self) -> str:
+        return (
+            f"<{self.__class__.__name__} target={self.target_caller.target!r}"
+            f" delay={self.delay!r}"
+            f" hit_count={self.hit_count!r}"
+            f" exception_callback={self.exception_callback!r}"
+            f" cancel_callback={self.cancel_callback!r}"
+            ">"
+        )

async_timer-1.1.1/src/async_timer/traget_caller.py

@@ -0,0 +1,70 @@
+"""This module is responsible for the magic behaviour calling the `target` function."""
+
+import inspect
+from collections.abc import Iterator
+
+
+class Caller:
+    target = None
+    get_next_val = None
+    first_call: bool = True
+
+    def __init__(self, target):
+        self.target = target
+
+    def _wrap_generator(self, maybe_gen):
+        if inspect.isgenerator(maybe_gen):
+
+            def _lock_sync_gen_ctx():
+                return lambda: next(maybe_gen)
+
+            gen_next_val = _lock_sync_gen_ctx()
+        elif inspect.isasyncgen(maybe_gen):
+
+            def _lock_async_gen_ctx():
+                return lambda: maybe_gen.__anext__()
+
+            gen_next_val = _lock_async_gen_ctx()
+        elif isinstance(maybe_gen, Iterator):
+
+            def _lock_iterator_ctx():
+                return next(maybe_gen)
+
+            gen_next_val = _lock_iterator_ctx
+        else:
+            gen_next_val = None
+        return gen_next_val
+
+    def _setup(self, target):
+        """Configure `get_next_val` to return next value.
+
+        Return the first such next value.
+        """
+        self.get_next_val = self._wrap_generator(target)
+        if self.get_next_val:
+            # `target` is a generator and we now have the
+            # `get_next_val`
+            return self.get_next_val()
+        assert callable(target), "Otherwise target must be callable"
+        target_rv = target()
+        self.get_next_val = self._wrap_generator(target_rv)
+        if self.get_next_val:
+            # Tartget is a callable that returned a generator.
+            return self.get_next_val()
+        # Otherwise, target is just a callable that returns values
+        self.get_next_val = target
+        return target_rv
+
+    async def next(self):
+        """Call `target` one more time."""
+        try:
+            if self.first_call:
+                rv = self._setup(self.target)
+                self.first_call = False
+            else:
+                rv = self.get_next_val()
+        except StopIteration as _err:
+            raise StopAsyncIteration() from _err
+        if inspect.isawaitable(rv):
+            rv = await rv
+        return rv

async_timer-1.0.3/src/async_timer/__init__.py

@@ -1,2 +0,0 @@
-from . import timer
-from .timer import Timer