ez-a-sync 0.22.14__py3-none-any.whl → 0.22.16__py3-none-any.whl

a_sync/primitives/_loggable.py

@@ -9,22 +9,45 @@ from logging import Logger, getLogger, DEBUG
 class _LoggerMixin:
     """
     A mixin class that adds logging capabilities to other classes.
-    
+
     This mixin provides a cached property for accessing a logger instance and a property to check if debug logging is enabled.
+
+    See Also:
+        - :func:`logging.getLogger`
+        - :class:`logging.Logger`
     """
+
     @cached_property
     def logger(self) -> Logger:
         """
-        Returns a logger instance specific to the class using this mixin.
-        
+        Provides a logger instance specific to the class using this mixin.
+
         The logger ID is constructed from the module and class name, and optionally includes an instance name if available.
 
-        Returns:
-            Logger: A logger instance for the class.
+        Examples:
+            >>> class MyClass(_LoggerMixin):
+            ...     _name = "example"
+            ...
+            >>> instance = MyClass()
+            >>> logger = instance.logger
+            >>> logger.name
+            '__main__.MyClass.example'
+
+            >>> class AnotherClass(_LoggerMixin):
+            ...     pass
+            ...
+            >>> another_instance = AnotherClass()
+            >>> another_logger = another_instance.logger
+            >>> another_logger.name
+            '__main__.AnotherClass'
+
+        See Also:
+            - :func:`logging.getLogger`
+            - :class:`logging.Logger`
         """
-        logger_id = type(self).__qualname__
-        if hasattr(self, '_name') and self._name:
-            logger_id += f'.{self._name}'
+        logger_id = f"{type(self).__module__}.{type(self).__qualname__}"
+        if hasattr(self, "_name") and self._name:
+            logger_id += f".{self._name}"
         return getLogger(logger_id)
 
     @property
@@ -32,7 +55,15 @@ class _LoggerMixin:
         """
         Checks if debug logging is enabled for the logger.
 
-        Returns:
-            bool: True if debug logging is enabled, False otherwise.
+        Examples:
+            >>> class MyClass(_LoggerMixin):
+            ...     pass
+            ...
+            >>> instance = MyClass()
+            >>> instance.debug_logs_enabled
+            False
+
+        See Also:
+            - :attr:`logging.Logger.isEnabledFor`
         """
         return self.logger.isEnabledFor(DEBUG)

a_sync/primitives/locks/__init__.py

@@ -1,5 +1,8 @@
-
 from a_sync.primitives.locks.counter import CounterLock
 from a_sync.primitives.locks.event import Event
-from a_sync.primitives.locks.semaphore import DummySemaphore, Semaphore, ThreadsafeSemaphore
+from a_sync.primitives.locks.semaphore import (
+    DummySemaphore,
+    Semaphore,
+    ThreadsafeSemaphore,
+)
 from a_sync.primitives.locks.prio_semaphore import PrioritySemaphore

a_sync/primitives/locks/counter.py

@@ -1,7 +1,7 @@
 """
-This module provides two specialized async flow management classes, CounterLock and CounterLockCluster.
+This module provides two specialized async flow management classes, :class:`CounterLock` and :class:`CounterLockCluster`.
 
-These primitives manages :class:`asyncio.Task` objects that must wait for an internal counter to reach a specific value.
+These primitives manage :class:`asyncio.Task` objects that must wait for an internal counter to reach a specific value.
 """
 
 import asyncio
@@ -15,23 +15,32 @@ from a_sync.primitives.locks.event import Event
 
 class CounterLock(_DebugDaemonMixin):
     """
-    An async primitive that blocks until the internal counter has reached a specific value.
-    
-    A coroutine can `await counter.wait_for(3)` and it will block until the internal counter >= 3.
-    If some other task executes `counter.value = 5` or `counter.set(5)`, the first coroutine will unblock as 5 >= 3.
-    
-    The internal counter can only increase.
+    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.
     """
+
     __slots__ = "is_ready", "_name", "_value", "_events"
+
     def __init__(self, start_value: int = 0, name: Optional[str] = None):
         """
-        Initializes the CounterLock with a starting value and an optional name.
+        Initializes the :class:`CounterLock` with a starting value and an optional name.
 
         Args:
             start_value: The initial value of the counter.
-            name (optional): An optional name for the counter, used in debug logs.
-        """
+            name: An optional name for the counter, used in debug logs.
 
+        Examples:
+            >>> counter = CounterLock(start_value=0, name="example_counter")
+            >>> counter.value
+            0
+        """
         self._name = name
         """An optional name for the counter, used in debug logs."""
 
@@ -43,7 +52,7 @@ class CounterLock(_DebugDaemonMixin):
 
         self.is_ready = lambda v: self._value >= v
         """A lambda function that indicates whether a given value has already been surpassed."""
-        
+
     async def wait_for(self, value: int) -> bool:
         """
         Waits until the counter reaches or exceeds the specified value.
@@ -51,40 +60,67 @@ class CounterLock(_DebugDaemonMixin):
         Args:
             value: The value to wait for.
 
-        Returns:
-            True when the counter reaches or exceeds the specified value.
+        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.
         """
         if not self.is_ready(value):
             self._ensure_debug_daemon()
             await self._events[value].wait()
         return True
-    
+
     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 >= the current value.
-        
+            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 the current value.
+            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.
         """
         self.value = value
-    
+
     def __repr__(self) -> str:
+        """
+        Returns a string representation of the :class:`CounterLock` instance.
+
+        The representation includes the name, current value, and the number of waiters for each awaited value.
+
+        Examples:
+            >>> counter = CounterLock(start_value=0, name="example_counter")
+            >>> repr(counter)
+            '<CounterLock name=example_counter value=0 waiters={}>'
+        """
         waiters = {v: len(self._events[v]._waiters) for v in sorted(self._events)}
         return f"<CounterLock name={self._name} value={self._value} waiters={waiters}>"
-        
+
     @property
     def value(self) -> int:
         """
         Gets the current value of the counter.
 
-        Returns:
-            The current value of the counter.
+        Examples:
+            >>> counter = CounterLock(start_value=0)
+            >>> counter.value
+            0
         """
         return self._value
-    
+
     @value.setter
     def value(self, value: int) -> None:
         """
@@ -95,50 +131,83 @@ class CounterLock(_DebugDaemonMixin):
 
         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.
         """
         if value > self._value:
             self._value = value
-            ready = [self._events.pop(key) for key in list(self._events.keys()) if key <= self._value]
+            ready = [
+                self._events.pop(key)
+                for key in list(self._events.keys())
+                if key <= self._value
+            ]
             for event in ready:
                 event.set()
         elif value < self._value:
             raise ValueError("You cannot decrease the value.")
-    
+
     async def _debug_daemon(self) -> None:
         """
         Periodically logs debug information about the counter state and waiters.
+
+        This method is used internally to provide debugging information when debug logging is enabled.
         """
         start = time()
         while self._events:
-            self.logger.debug("%s is still locked after %sm", self, round(time() - start / 60, 2))
+            self.logger.debug(
+                "%s is still locked after %sm", self, round(time() - start / 60, 2)
+            )
             await asyncio.sleep(300)
 
+
 class CounterLockCluster:
     """
-    An asyncio primitive that represents 2 or more CounterLock objects.
-    
-    `wait_for(i)` will block until the value of all CounterLock objects is >= i.
+    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.
     """
-    __slots__ = "locks", 
+
+    __slots__ = ("locks",)
+
     def __init__(self, counter_locks: Iterable[CounterLock]) -> None:
         """
-        Initializes the CounterLockCluster with a collection of CounterLock objects.
+        Initializes the :class:`CounterLockCluster` with a collection of :class:`CounterLock` objects.
 
         Args:
-            counter_locks: The CounterLock objects to manage.
+            counter_locks: The :class:`CounterLock` objects to manage.
+
+        Examples:
+            >>> lock1 = CounterLock(start_value=0)
+            >>> lock2 = CounterLock(start_value=0)
+            >>> cluster = CounterLockCluster([lock1, lock2])
         """
         self.locks = list(counter_locks)
-    
+
     async def wait_for(self, value: int) -> bool:
         """
-        Waits until the value of all CounterLock objects in the cluster reaches or exceeds the specified value.
+        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.
 
-        Returns:
-            True when the value of all CounterLock objects reach or exceed the specified value.
+        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
         """
-        await asyncio.gather(*[counter_lock.wait_for(value) for counter_lock in self.locks])
+        await asyncio.gather(
+            *[counter_lock.wait_for(value) for counter_lock in self.locks]
+        )
         return True
-    

a_sync/primitives/locks/event.py

@@ -8,14 +8,16 @@ import sys
 from a_sync._typing import *
 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 
+    detailed information about the event state and waiters, which can be useful for
     diagnosing and debugging potential deadlocks.
     """
+
     _value: bool
     _loop: asyncio.AbstractEventLoop
     _waiters: Deque["asyncio.Future[None]"]
@@ -23,7 +25,14 @@ class Event(asyncio.Event, _DebugDaemonMixin):
         __slots__ = "_value", "_waiters", "_debug_daemon_interval"
     else:
         __slots__ = "_value", "_loop", "_waiters", "_debug_daemon_interval"
-    def __init__(self, name: str = "", debug_daemon_interval: int = 300, *, loop: Optional[asyncio.AbstractEventLoop] = None):
+
+    def __init__(
+        self,
+        name: str = "",
+        debug_daemon_interval: int = 300,
+        *,
+        loop: Optional[asyncio.AbstractEventLoop] = None,
+    ):
         """
         Initializes the Event.
 
@@ -41,12 +50,14 @@ class Event(asyncio.Event, _DebugDaemonMixin):
         if hasattr(self, "_loop"):
             self._loop = self._loop or asyncio.get_event_loop()
         self._debug_daemon_interval = debug_daemon_interval
+
     def __repr__(self) -> str:
-        label = f'name={self._name}' if self._name else 'object'
-        status = 'set' if self._value else 'unset'
+        label = f"name={self._name}" if self._name else "object"
+        status = "set" if self._value else "unset"
         if self._waiters:
-            status += f', waiters:{len(self._waiters)}'
+            status += f", waiters:{len(self._waiters)}"
         return f"<{self.__class__.__module__}.{self.__class__.__name__} {label} at {hex(id(self))} [{status}]>"
+
     async def wait(self) -> Literal[True]:
         """
         Wait until the event is set.
@@ -58,6 +69,7 @@ class Event(asyncio.Event, _DebugDaemonMixin):
             return True
         self._ensure_debug_daemon()
         return await super().wait()
+
     async def _debug_daemon(self) -> None:
         """
         Periodically logs debug information about the event state and waiters.
@@ -68,4 +80,6 @@ class Event(asyncio.Event, _DebugDaemonMixin):
             del self  # no need to hold a reference here
             await asyncio.sleep(self._debug_daemon_interval)
             if (self := weakself()) and not self.is_set():
-                self.logger.debug("Waiting for %s for %sm", self, round((time() - start) / 60, 2))
+                self.logger.debug(
+                    "Waiting for %s for %sm", self, round((time() - start) / 60, 2)
+                )