ez-a-sync 0.22.13__py3-none-any.whl → 0.22.15__py3-none-any.whl

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)
+                )

a_sync/primitives/locks/prio_semaphore.py

@@ -1,3 +1,8 @@
+"""
+This module provides priority-based semaphore implementations. These semaphores allow 
+waiters to be assigned priorities, ensuring that higher priority waiters are 
+processed before lower priority ones.
+"""
 
 import asyncio
 import heapq
@@ -12,84 +17,155 @@ logger = logging.getLogger(__name__)
 
 
 class Priority(Protocol):
-    def __lt__(self, other) -> bool:
-        ...
+    def __lt__(self, other) -> bool: ...
+
+
+PT = TypeVar("PT", bound=Priority)
+
+CM = TypeVar("CM", bound="_AbstractPrioritySemaphoreContextManager[Priority]")
 
-PT = TypeVar('PT', bound=Priority)
-    
-CM = TypeVar('CM', bound="_AbstractPrioritySemaphoreContextManager[Priority]")
 
 class _AbstractPrioritySemaphore(Semaphore, Generic[PT, CM]):
+    """
+    A semaphore that allows prioritization of waiters.
+
+    This semaphore manages waiters with associated priorities, ensuring that waiters with higher
+    priorities are processed before those with lower priorities. If no priority is specified,
+    the semaphore uses a default top priority.
+    """
+
     name: Optional[str]
     _value: int
     _waiters: List["_AbstractPrioritySemaphoreContextManager[PT]"]  # type: ignore [assignment]
-    __slots__ = "name", "_value", "_waiters", "_context_managers", "_capacity", "_potential_lost_waiters"
+    _context_managers: Dict[PT, "_AbstractPrioritySemaphoreContextManager[PT]"]
+    __slots__ = (
+        "name",
+        "_value",
+        "_waiters",
+        "_context_managers",
+        "_capacity",
+        "_potential_lost_waiters",
+    )
 
     @property
-    def _context_manager_class(self) -> Type["_AbstractPrioritySemaphoreContextManager[PT]"]:
+    def _context_manager_class(
+        self,
+    ) -> Type["_AbstractPrioritySemaphoreContextManager[PT]"]:
         raise NotImplementedError
-    
+
     @property
     def _top_priority(self) -> PT:
         # You can use this so you can set priorities with non numeric comparable values
         raise NotImplementedError
 
     def __init__(self, value: int = 1, *, name: Optional[str] = None) -> None:
-        self._context_managers: Dict[PT, _AbstractPrioritySemaphoreContextManager[PT]] = {}
+        """Initializes the priority semaphore.
+
+        Args:
+            value: The initial capacity of the semaphore.
+            name: An optional name for the semaphore, used for debugging.
+        """
+
+        self._context_managers = {}
+        """A dictionary mapping priorities to their context managers."""
+
         self._capacity = value
+        """The initial capacity of the semaphore."""
+
         super().__init__(value, name=name)
         self._waiters = []
+        """A heap queue of context managers, sorted by priority."""
+
         # NOTE: This should (hopefully) be temporary
         self._potential_lost_waiters: List["asyncio.Future[None]"] = []
+        """A list of futures representing waiters that might have been lost."""
 
     def __repr__(self) -> str:
+        """Returns a string representation of the semaphore."""
         return f"<{self.__class__.__name__} name={self.name} capacity={self._capacity} value={self._value} waiters={self._count_waiters()}>"
 
     async def __aenter__(self) -> None:
+        """Enters the semaphore context, acquiring it with the top priority."""
         await self[self._top_priority].acquire()
 
     async def __aexit__(self, *_) -> None:
+        """Exits the semaphore context, releasing it with the top priority."""
         self[self._top_priority].release()
-    
+
     async def acquire(self) -> Literal[True]:
+        """Acquires the semaphore with the top priority."""
         return await self[self._top_priority].acquire()
-    
-    def __getitem__(self, priority: Optional[PT]) -> "_AbstractPrioritySemaphoreContextManager[PT]":
+
+    def __getitem__(
+        self, priority: Optional[PT]
+    ) -> "_AbstractPrioritySemaphoreContextManager[PT]":
+        """Gets the context manager for a given priority.
+
+        Args:
+            priority: The priority for which to get the context manager. If None, uses the top priority.
+
+        Returns:
+            The context manager associated with the given priority.
+        """
         priority = self._top_priority if priority is None else priority
         if priority not in self._context_managers:
-            context_manager = self._context_manager_class(self, priority, name=self.name)
+            context_manager = self._context_manager_class(
+                self, priority, name=self.name
+            )
             heapq.heappush(self._waiters, context_manager)  # type: ignore [misc]
             self._context_managers[priority] = context_manager
         return self._context_managers[priority]
 
     def locked(self) -> bool:
-        """Returns True if semaphore cannot be acquired immediately."""
+        """Checks if the semaphore is locked.
+
+        Returns:
+            True if the semaphore cannot be acquired immediately, False otherwise.
+        """
         return self._value == 0 or (
             any(
-                cm._waiters and any(not w.cancelled() for w in cm._waiters) 
+                cm._waiters and any(not w.cancelled() for w in cm._waiters)
                 for cm in (self._context_managers.values() or ())
             )
         )
-    
+
     def _count_waiters(self) -> Dict[PT, int]:
-        return {manager._priority: len(manager.waiters) for manager in sorted(self._waiters, key=lambda m: m._priority)}
-    
+        """Counts the number of waiters for each priority.
+
+        Returns:
+            A dictionary mapping each priority to the number of waiters.
+        """
+        return {
+            manager._priority: len(manager.waiters)
+            for manager in sorted(self._waiters, key=lambda m: m._priority)
+        }
+
     def _wake_up_next(self) -> None:
+        """Wakes up the next waiter in line.
+
+        This method handles the waking of waiters based on priority. It includes an emergency
+        procedure to handle potential lost waiters, ensuring that no waiter is left indefinitely
+        waiting.
+        """
         while self._waiters:
             manager = heapq.heappop(self._waiters)
             if len(manager) == 0:
                 # There are no more waiters, get rid of the empty manager
-                logger.debug("manager %s has no more waiters, popping from %s", manager._repr_no_parent_(), self)
+                logger.debug(
+                    "manager %s has no more waiters, popping from %s",
+                    manager._repr_no_parent_(),
+                    self,
+                )
                 self._context_managers.pop(manager._priority)
                 continue
             logger.debug("waking up next for %s", manager._repr_no_parent_())
-            
+
             woke_up = False
             start_len = len(manager)
-        
+
             if not manager._waiters:
-                logger.debug('not manager._waiters')
-            
+                logger.debug("not manager._waiters")
+
             while manager._waiters:
                 waiter = manager._waiters.popleft()
                 self._potential_lost_waiters.remove(waiter)
@@ -98,15 +174,15 @@ class _AbstractPrioritySemaphore(Semaphore, Generic[PT, CM]):
                     logger.debug("woke up %s", waiter)
                     woke_up = True
                     break
-            
+
             if not woke_up:
                 self._context_managers.pop(manager._priority)
                 continue
-            
+
             end_len = len(manager)
-            
+
             assert start_len > end_len, f"start {start_len} end {end_len}"
-            
+
             if end_len:
                 # There are still waiters, put the manager back
                 heapq.heappush(self._waiters, manager)  # type: ignore [misc]
@@ -114,57 +190,94 @@ class _AbstractPrioritySemaphore(Semaphore, Generic[PT, CM]):
                 # There are no more waiters, get rid of the empty manager
                 self._context_managers.pop(manager._priority)
             return
-        
-        # emergency procedure (hopefully temporary): 
+
+        # emergency procedure (hopefully temporary):
         while self._potential_lost_waiters:
             waiter = self._potential_lost_waiters.pop(0)
-            logger.debug('we found a lost waiter %s', waiter)
+            logger.debug("we found a lost waiter %s", waiter)
             if not waiter.done():
                 waiter.set_result(None)
                 logger.debug("woke up lost waiter %s", waiter)
                 return
         logger.debug("%s has no waiters to wake", self)
 
+
 class _AbstractPrioritySemaphoreContextManager(Semaphore, Generic[PT]):
+    """
+    A context manager for priority semaphore waiters.
+
+    This context manager is associated with a specific priority and handles
+    the acquisition and release of the semaphore for waiters with that priority.
+    """
+
     _loop: asyncio.AbstractEventLoop
     _waiters: Deque[asyncio.Future]  # type: ignore [assignment]
     __slots__ = "_parent", "_priority"
-    
+
     @property
     def _priority_name(self) -> str:
         raise NotImplementedError
-    
-    def __init__(self, parent: _AbstractPrioritySemaphore, priority: PT, name: Optional[str] = None) -> None:
+
+    def __init__(
+        self,
+        parent: _AbstractPrioritySemaphore,
+        priority: PT,
+        name: Optional[str] = None,
+    ) -> None:
+        """Initializes the context manager for a specific priority.
+
+        Args:
+            parent: The parent semaphore.
+            priority: The priority associated with this context manager.
+            name: An optional name for the context manager, used for debugging.
+        """
+
         self._parent = parent
+        """The parent semaphore."""
+
         self._priority = priority
+        """The priority associated with this context manager."""
+
         super().__init__(0, name=name)
 
     def __repr__(self) -> str:
+        """Returns a string representation of the context manager."""
         return f"<{self.__class__.__name__} parent={self._parent} {self._priority_name}={self._priority} waiters={len(self)}>"
-    
+
     def _repr_no_parent_(self) -> str:
+        """Returns a string representation of the context manager without the parent."""
         return f"<{self.__class__.__name__} parent_name={self._parent.name} {self._priority_name}={self._priority} waiters={len(self)}>"
-    
+
     def __lt__(self, other) -> bool:
+        """Compares this context manager with another based on priority.
+
+        Args:
+            other: The other context manager to compare with.
+
+        Returns:
+            True if this context manager has a lower priority than the other, False otherwise.
+        """
         if type(other) is not type(self):
             raise TypeError(f"{other} is not type {self.__class__.__name__}")
         return self._priority < other._priority
-    
+
     @cached_property
     def loop(self) -> asyncio.AbstractEventLoop:
+        """Gets the event loop associated with this context manager."""
         return self._loop or asyncio.get_event_loop()
-    
+
     @property
-    def waiters (self) -> Deque[asyncio.Future]:
+    def waiters(self) -> Deque[asyncio.Future]:
+        """Gets the deque of waiters for this context manager."""
         if self._waiters is None:
             self._waiters = deque()
         return self._waiters
-    
+
     async def acquire(self) -> Literal[True]:
-        """Acquire a semaphore.
+        """Acquires the semaphore for this context manager.
 
         If the internal counter is larger than zero on entry,
-        decrement it by one and return True immediately.  If it is
+        decrement it by one and return True immediately. If it is
         zero on entry, block, waiting until some other coroutine has
         called release() to make it larger than 0, and then return
         True.
@@ -185,31 +298,38 @@ class _AbstractPrioritySemaphoreContextManager(Semaphore, Generic[PT]):
                 raise
         self._parent._value -= 1
         return True
+
     def release(self) -> None:
+        """Releases the semaphore for this context manager."""
         self._parent.release()
-    
-class _PrioritySemaphoreContextManager(_AbstractPrioritySemaphoreContextManager[Numeric]):
+
+
+class _PrioritySemaphoreContextManager(
+    _AbstractPrioritySemaphoreContextManager[Numeric]
+):
+    """Context manager for numeric priority semaphores."""
+
     _priority_name = "priority"
 
+
 class PrioritySemaphore(_AbstractPrioritySemaphore[Numeric, _PrioritySemaphoreContextManager]):  # type: ignore [type-var]
+    """Semaphore that uses numeric priorities for waiters.
+
+    It's similar to a regular Semaphore but requires each waiter to have a priority:
+
+    Examples:
+        The primary way to use this semaphore is by specifying a priority.
+
+        >>> priority_semaphore = PrioritySemaphore(10)
+        >>> async with priority_semaphore[priority]:
+        ...     await do_stuff()
+
+        You can also enter and exit this semaphore without specifying a priority, and it will use the top priority by default:
+
+        >>> priority_semaphore = PrioritySemaphore(10)
+        >>> async with priority_semaphore:
+        ...     await do_stuff()
+    """
+
     _context_manager_class = _PrioritySemaphoreContextManager
     _top_priority = -1
-    """
-    It's kinda like a regular Semaphore but you must give each waiter a priority:
-
-    ```
-    priority_semaphore = PrioritySemaphore(10)
-
-    async with priority_semaphore[priority]:
-        await do_stuff()
-    ```
-    
-    You can aenter and aexit this semaphore without a priority and it will process those first. Like so:
-    
-    ```
-    priority_semaphore = PrioritySemaphore(10)
-    
-    async with priority_semaphore:
-        await do_stuff()
-    ```
-    """