ez-a-sync 0.24.3__tar.gz → 0.24.4__tar.gz

{ez_a_sync-0.24.3 → ez_a_sync-0.24.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ez-a-sync
-Version: 0.24.3
+Version: 0.24.4
 Summary: A library that makes it easy to define objects that can be used for both sync and async use cases.
 Home-page: https://github.com/BobTheBuidler/a-sync
 Author: BobTheBuidler

{ez_a_sync-0.24.3 → ez_a_sync-0.24.4}/a_sync/a_sync/_helpers.pyi

@@ -2,6 +2,7 @@
 This module provides utility functions for handling asynchronous operations
 and converting synchronous functions to asynchronous ones.
 """
+
 from a_sync._typing import *
 from a_sync import exceptions as exceptions
 

{ez_a_sync-0.24.3 → ez_a_sync-0.24.4}/a_sync/a_sync/abstract.pyi

@@ -8,6 +8,7 @@ the execution mode based on flags and keyword arguments.
 Note: It is recommended to use :class:`ASyncGenericBase` for most use cases. This class
 is intended for more custom implementations if necessary.
 """
+
 from a_sync._typing import *
 import abc
 import functools

{ez_a_sync-0.24.3 → ez_a_sync-0.24.4}/a_sync/a_sync/method.pyi

@@ -5,6 +5,7 @@ It includes descriptors and bound methods that can be used to create flexible
 asynchronous interfaces, allowing methods to be called both synchronously and
 asynchronously based on various conditions and configurations.
 """
+
 from a_sync._typing import *
 import functools
 import weakref

{ez_a_sync-0.24.3 → ez_a_sync-0.24.4}/a_sync/primitives/_debug.c

@@ -5442,7 +5442,7 @@ static PyObject *__pyx_pf_6a_sync_10primitives_6_debug_17_DebugDaemonMixin_5_ens
  *                 self._daemon = self._start_debug_daemon(*args, **kwargs)
  *                 self._daemon.add_done_callback(self._stop_debug_daemon)             # <<<<<<<<<<<<<<
  *             else:
- *                 self._daemon = get_event_loop().create_future()
+ *                 self._daemon = self._c_get_loop().create_future()
  */
       __Pyx_TraceLine(160,0,__PYX_ERR(0, 160, __pyx_L1_error))
       __pyx_t_3 = __Pyx_PyObject_GetAttrStr(__pyx_v_self->_daemon, __pyx_n_s_add_done_callback); if (unlikely(!__pyx_t_3)) __PYX_ERR(0, 160, __pyx_L1_error)
@@ -5487,13 +5487,13 @@ static PyObject *__pyx_pf_6a_sync_10primitives_6_debug_17_DebugDaemonMixin_5_ens
     /* "a_sync/primitives/_debug.pyx":162
  *                 self._daemon.add_done_callback(self._stop_debug_daemon)
  *             else:
- *                 self._daemon = get_event_loop().create_future()             # <<<<<<<<<<<<<<
+ *                 self._daemon = self._c_get_loop().create_future()             # <<<<<<<<<<<<<<
  *         return self._daemon
  * 
  */
     __Pyx_TraceLine(162,0,__PYX_ERR(0, 162, __pyx_L1_error))
     /*else*/ {
-      __pyx_t_3 = __pyx_f_6a_sync_6a_sync_8_helpers_get_event_loop(0); if (unlikely(!__pyx_t_3)) __PYX_ERR(0, 162, __pyx_L1_error)
+      __pyx_t_3 = ((struct __pyx_vtabstruct_6a_sync_10primitives_6_debug__DebugDaemonMixin *)__pyx_v_self->__pyx_base.__pyx_base.__pyx_vtab)->__pyx_base._c_get_loop(((struct __pyx_obj_6a_sync_10primitives_6_debug__LoopBoundMixin *)__pyx_v_self)); if (unlikely(!__pyx_t_3)) __PYX_ERR(0, 162, __pyx_L1_error)
       __Pyx_GOTREF(__pyx_t_3);
       __pyx_t_1 = __Pyx_PyObject_GetAttrStr(__pyx_t_3, __pyx_n_s_create_future); if (unlikely(!__pyx_t_1)) __PYX_ERR(0, 162, __pyx_L1_error)
       __Pyx_GOTREF(__pyx_t_1);
@@ -5539,7 +5539,7 @@ static PyObject *__pyx_pf_6a_sync_10primitives_6_debug_17_DebugDaemonMixin_5_ens
 
   /* "a_sync/primitives/_debug.pyx":163
  *             else:
- *                 self._daemon = get_event_loop().create_future()
+ *                 self._daemon = self._c_get_loop().create_future()
  *         return self._daemon             # <<<<<<<<<<<<<<
  * 
  *     def _stop_debug_daemon(self, t: Optional[asyncio.Task] = None) -> None:

{ez_a_sync-0.24.3 → ez_a_sync-0.24.4}/a_sync/primitives/_debug.pyi

@@ -3,6 +3,7 @@ This module provides a mixin class used to facilitate the creation of debugging
 
 The mixin provides a framework for managing a debug daemon task, which can be used to emit rich debug logs from subclass instances whenever debug logging is enabled. Subclasses must implement the specific logging behavior.
 """
+
 import abc
 from a_sync.primitives._loggable import _LoggerMixin
 

{ez_a_sync-0.24.3 → ez_a_sync-0.24.4}/a_sync/primitives/_debug.pyx

@@ -159,7 +159,7 @@ cdef class _DebugDaemonMixin(_LoopBoundMixin):
                 self._daemon = self._start_debug_daemon(*args, **kwargs)
                 self._daemon.add_done_callback(self._stop_debug_daemon)
             else:
-                self._daemon = get_event_loop().create_future()
+                self._daemon = self._c_get_loop().create_future()
         return self._daemon
 
     def _stop_debug_daemon(self, t: Optional[asyncio.Task] = None) -> None:

{ez_a_sync-0.24.3 → ez_a_sync-0.24.4}/a_sync/primitives/_loggable.pyi

@@ -1,6 +1,7 @@
 """
 This module provides a mixin class to add debug logging capabilities to other classes.
 """
+
 from functools import cached_property as cached_property
 from logging import Logger
 

ez_a_sync-0.24.4/a_sync/primitives/locks/counter.pyi

@@ -0,0 +1,142 @@
+from _typeshed import Incomplete
+from a_sync.primitives._debug import _DebugDaemonMixin
+from a_sync.primitives.locks.event import Event as Event
+from typing import Iterable, Optional
+
+class CounterLock(_DebugDaemonMixin):
+    """
+    An async primitive that uses an internal counter to manage task synchronization.
+
+    A coroutine can `await counter.wait_for(3)` and it will wait until the internal counter >= 3.
+    If some other task executes `counter.value = 5` or `counter.set(5)`, the first coroutine will proceed as 5 >= 3.
+
+    The internal counter can only be set to a value greater than the current value.
+
+    See Also:
+        :class:`CounterLockCluster` for managing multiple :class:`CounterLock` instances.
+    """
+
+    is_ready: Incomplete
+    def __init__(self, start_value: int = 0, name: Optional[str] = None) -> None:
+        """
+        Initializes the :class:`CounterLock` with a starting value and an optional name.
+
+        Args:
+            start_value: The initial value of the counter.
+            name: An optional name for the counter, used in debug logs.
+
+        Examples:
+            >>> counter = CounterLock(start_value=0, name="example_counter")
+            >>> counter.value
+            0
+        """
+
+    async def wait_for(self, value: int) -> bool:
+        """
+        Waits until the counter reaches or exceeds the specified value.
+
+        This method will ensure the debug daemon is running if the counter is not ready.
+
+        Args:
+            value: The value to wait for.
+
+        Examples:
+            >>> counter = CounterLock(start_value=0)
+            >>> await counter.wait_for(5)  # This will block until counter.value >= 5
+
+        See Also:
+            :meth:`CounterLock.set` to set the counter value.
+        """
+
+    def set(self, value: int) -> None:
+        """
+        Sets the counter to the specified value.
+
+        This method internally uses the `value` property to enforce that the new value must be strictly greater than the current value.
+
+        Args:
+            value: The value to set the counter to. Must be strictly greater than the current value.
+
+        Raises:
+            ValueError: If the new value is less than or equal to the current value.
+
+        Examples:
+            >>> counter = CounterLock(start_value=0)
+            >>> counter.set(5)
+            >>> counter.value
+            5
+
+        See Also:
+            :meth:`CounterLock.value` for direct value assignment.
+        """
+
+    @property
+    def value(self) -> int:
+        """
+        Gets the current value of the counter.
+
+        Examples:
+            >>> counter = CounterLock(start_value=0)
+            >>> counter.value
+            0
+        """
+
+    @value.setter
+    def value(self, value: int) -> None:
+        """
+        Sets the counter to a new value, waking up any waiters if the value increases beyond the value they are awaiting.
+
+        Args:
+            value: The new value of the counter.
+
+        Raises:
+            ValueError: If the new value is less than the current value.
+
+        Examples:
+            >>> counter = CounterLock(start_value=0)
+            >>> counter.value = 5
+            >>> counter.value
+            5
+            >>> counter.value = 3
+            Traceback (most recent call last):
+            ...
+            ValueError: You cannot decrease the value.
+        """
+
+class CounterLockCluster:
+    """
+    An asyncio primitive that represents a collection of :class:`CounterLock` objects.
+
+    `wait_for(i)` will wait until the value of all :class:`CounterLock` objects is >= i.
+
+    See Also:
+        :class:`CounterLock` for managing individual counters.
+    """
+
+    locks: Incomplete
+    def __init__(self, counter_locks: Iterable[CounterLock]) -> None:
+        """
+        Initializes the :class:`CounterLockCluster` with a collection of :class:`CounterLock` objects.
+
+        Args:
+            counter_locks: The :class:`CounterLock` objects to manage.
+
+        Examples:
+            >>> lock1 = CounterLock(start_value=0)
+            >>> lock2 = CounterLock(start_value=0)
+            >>> cluster = CounterLockCluster([lock1, lock2])
+        """
+
+    async def wait_for(self, value: int) -> bool:
+        """
+        Waits until the value of all :class:`CounterLock` objects in the cluster reaches or exceeds the specified value.
+
+        Args:
+            value: The value to wait for.
+
+        Examples:
+            >>> lock1 = CounterLock(start_value=0)
+            >>> lock2 = CounterLock(start_value=0)
+            >>> cluster = CounterLockCluster([lock1, lock2])
+            >>> await cluster.wait_for(5)  # This will block until all locks have value >= 5
+        """

ez_a_sync-0.24.4/a_sync/primitives/locks/event.pyi

@@ -0,0 +1,36 @@
+from a_sync._typing import *
+import asyncio
+from a_sync.primitives._debug import _DebugDaemonMixin
+
+class Event(asyncio.Event, _DebugDaemonMixin):
+    """
+    An asyncio.Event with additional debug logging to help detect deadlocks.
+
+    This event class extends asyncio.Event by adding debug logging capabilities. It logs
+    detailed information about the event state and waiters, which can be useful for
+    diagnosing and debugging potential deadlocks.
+    """
+
+    def __init__(
+        self,
+        name: str = "",
+        debug_daemon_interval: int = 300,
+        *,
+        loop: Optional[asyncio.AbstractEventLoop] = None
+    ) -> None:
+        """
+        Initializes the Event.
+
+        Args:
+            name (str): An optional name for the event, used in debug logs.
+            debug_daemon_interval (int): The interval in seconds for the debug daemon to log information.
+            loop (Optional[asyncio.AbstractEventLoop]): The event loop to use.
+        """
+
+    async def wait(self) -> Literal[True]:
+        """
+        Wait until the event is set.
+
+        Returns:
+            True when the event is set.
+        """