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

a_sync/iter.py

@@ -125,7 +125,19 @@ class ASyncIterable(_AwaitableAsyncIterableMixin[T], Iterable[T]):
 
     This class allows objects to be iterated over using either a standard `for` loop or an `async for` loop, making it versatile in scenarios where the mode of iteration (synchronous or asynchronous) needs to be flexible or is determined at runtime.
 
-    The class achieves this by implementing both `__iter__` and `__aiter__` methods, enabling it to return appropriate iterator objects that can handle synchronous and asynchronous iteration, respectively. This dual functionality is particularly useful in codebases that are transitioning between synchronous and asynchronous code, or in libraries that aim to support both synchronous and asynchronous usage patterns without requiring the user to manage different types of iterable objects.
+    The class achieves this by implementing both `__iter__` and `__aiter__` methods, enabling it to return appropriate iterator objects that can handle synchronous and asynchronous iteration, respectively. However, note that synchronous iteration relies on the :class:`ASyncIterator` class, which uses `asyncio.get_event_loop().run_until_complete` to fetch items. This can raise a `RuntimeError` if the event loop is already running, resulting in a :class:`SyncModeInAsyncContextError`.
+
+    Example:
+        >>> async_iterable = ASyncIterable(some_async_iterable)
+        >>> async for item in async_iterable:
+        ...     print(item)
+        >>> for item in async_iterable:
+        ...     print(item)
+
+    See Also:
+        - :class:`ASyncIterator`
+        - :class:`ASyncFilter`
+        - :class:`ASyncSorter`
     """
 
     @classmethod
@@ -178,7 +190,20 @@ class ASyncIterator(_AwaitableAsyncIterableMixin[T], Iterator[T]):
 
     By implementing both `__next__` and `__anext__` methods, ASyncIterator enables objects to be iterated using standard iteration protocols while internally managing the complexities of asynchronous iteration. This design simplifies the use of asynchronous iterables in environments or frameworks that are not inherently asynchronous, such as standard synchronous functions or older codebases being gradually migrated to asynchronous IO.
 
-    This class is particularly useful for library developers seeking to provide a consistent iteration interface across synchronous and asynchronous code, reducing the cognitive load on users and promoting code reusability and simplicity.
+    Note:
+        Synchronous iteration with `ASyncIterator` uses `asyncio.get_event_loop().run_until_complete`, which can raise a `RuntimeError` if the event loop is already running. In such cases, a :class:`SyncModeInAsyncContextError` is raised, indicating that synchronous iteration is not possible in an already running event loop.
+
+    Example:
+        >>> async_iterator = ASyncIterator(some_async_iterator)
+        >>> async for item in async_iterator:
+        ...     print(item)
+        >>> for item in async_iterator:
+        ...     print(item)
+
+    See Also:
+        - :class:`ASyncIterable`
+        - :class:`ASyncFilter`
+        - :class:`ASyncSorter`
     """
 
     def __next__(self) -> T:
@@ -270,6 +295,18 @@ class ASyncGeneratorFunction(Generic[P, T]):
     The ASyncGeneratorFunction class supports dynamic binding to instances, enabling it to be used as a method on class instances. When accessed as a descriptor, it automatically handles the binding to the instance, thereby allowing the wrapped async generator function to be invoked with instance context ('self') automatically provided. This feature is invaluable for designing classes that need to expose asynchronous generators as part of their interface while maintaining the ease of use and calling semantics similar to regular methods.
 
     By providing a unified interface to asynchronous generator functions, this class facilitates the creation of APIs that are flexible and easy to use in a wide range of asynchronous programming scenarios. It abstracts away the complexities involved in managing asynchronous generator lifecycles and invocation semantics, making it easier for developers to integrate asynchronous iteration patterns into their applications.
+
+    Example:
+        >>> async def my_async_gen():
+        ...     yield 1
+        ...     yield 2
+        >>> async_gen_func = ASyncGeneratorFunction(my_async_gen)
+        >>> for item in async_gen_func():
+        ...     print(item)
+
+    See Also:
+        - :class:`ASyncIterator`
+        - :class:`ASyncIterable`
     """
 
     _cache_handle: asyncio.TimerHandle
@@ -310,9 +347,6 @@ class ASyncGeneratorFunction(Generic[P, T]):
         Args:
             *args: Positional arguments for the function.
             **kwargs: Keyword arguments for the function.
-
-        Returns:
-            An :class:`ASyncIterator` wrapping the :class:`AsyncIterator` returned from the wrapped function call.
         """
         if self.__weakself__ is None:
             return ASyncIterator(self.__wrapped__(*args, **kwargs))
@@ -393,7 +427,19 @@ class ASyncFilter(_ASyncView[T]):
 
     This class inherits from :class:`~_ASyncView` and provides the functionality to asynchronously
     iterate over items, applying the filter function to each item to determine if it should be
-    included in the result.
+    included in the result. The filter function can be either synchronous or asynchronous.
+
+    Example:
+        >>> async def is_even(x):
+        ...     return x % 2 == 0
+        >>> filtered_iterable = ASyncFilter(is_even, some_async_iterable)
+        >>> async for item in filtered_iterable:
+        ...     print(item)
+
+    See Also:
+        - :class:`ASyncIterable`
+        - :class:`ASyncIterator`
+        - :class:`ASyncSorter`
     """
 
     def __repr__(self) -> str:
@@ -445,7 +491,18 @@ class ASyncSorter(_ASyncView[T]):
     An async sorter class that sorts items of an async iterable based on a provided key function.
 
     This class inherits from :class:`~_ASyncView` and provides the functionality to asynchronously
-    iterate over items, applying the key function to each item for sorting.
+    iterate over items, applying the key function to each item for sorting. The key function can be
+    either synchronous or asynchronous. Note that the ASyncSorter instance can only be consumed once.
+
+    Example:
+        >>> sorted_iterable = ASyncSorter(some_async_iterable, key=lambda x: x.value)
+        >>> async for item in sorted_iterable:
+        ...     print(item)
+
+    See Also:
+        - :class:`ASyncIterable`
+        - :class:`ASyncIterator`
+        - :class:`ASyncFilter`
     """
 
     reversed: bool = False

a_sync/primitives/_debug.py

@@ -1,7 +1,7 @@
 """
-This module provides a mixin class used to provide helpful information to developers during the debugging process.
+This module provides a mixin class used to facilitate the creation of debugging daemons in subclasses.
 
-The mixin ensures that rich debug logs are automagically emitted from subclass instances whenever debug logging is enabled.
+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
@@ -13,9 +13,12 @@ from a_sync.primitives._loggable import _LoggerMixin
 
 class _DebugDaemonMixin(_LoggerMixin, metaclass=abc.ABCMeta):
     """
-    A mixin class that provides debugging capabilities using a daemon task.
+    A mixin class that provides a framework for debugging capabilities using a daemon task.
 
-    This mixin ensures that rich debug logs are automagically emitted from subclass instances whenever debug logging is enabled.
+    This mixin sets up the structure for managing a debug daemon task. Subclasses are responsible for implementing the specific behavior of the daemon, including any logging functionality.
+
+    See Also:
+        :class:`_LoggerMixin` for logging capabilities.
     """
 
     __slots__ = ("_daemon",)
@@ -25,39 +28,77 @@ class _DebugDaemonMixin(_LoggerMixin, metaclass=abc.ABCMeta):
         """
         Abstract method to define the debug daemon's behavior.
 
+        Subclasses must implement this method to specify what the debug daemon should do, including any logging or monitoring tasks.
+
         Args:
             fut: The future associated with the daemon.
             fn: The function to be debugged.
             *args: Positional arguments for the function.
             **kwargs: Keyword arguments for the function.
+
+        Examples:
+            Implementing a simple debug daemon in a subclass:
+
+            .. code-block:: python
+
+                class MyDebugClass(_DebugDaemonMixin):
+                    async def _debug_daemon(self, fut, fn, *args, **kwargs):
+                        while not fut.done():
+                            self.logger.debug("Debugging...")
+                            await asyncio.sleep(1)
         """
 
     def _start_debug_daemon(self, *args, **kwargs) -> "asyncio.Future[None]":
         """
         Starts the debug daemon task if debug logging is enabled and the event loop is running.
 
+        This method checks if debug logging is enabled and if the event loop is running. If both conditions are met, it starts the debug daemon task.
+
         Args:
             *args: Positional arguments for the debug daemon.
             **kwargs: Keyword arguments for the debug daemon.
 
         Returns:
             The debug daemon task as an asyncio.Task, or a dummy future if debug logs are not enabled or if the daemon cannot be created.
+
+        Examples:
+            Starting the debug daemon:
+
+            .. code-block:: python
+
+                my_instance = MyDebugClass()
+                my_instance._start_debug_daemon()
+
+        See Also:
+            :meth:`_ensure_debug_daemon` for ensuring the daemon is running.
         """
         if self.debug_logs_enabled and asyncio.get_event_loop().is_running():
             return asyncio.create_task(self._debug_daemon(*args, **kwargs))
-        # else we return a blank Future since we shouldn't or can't create the daemon
         return asyncio.get_event_loop().create_future()
 
     def _ensure_debug_daemon(self, *args, **kwargs) -> "asyncio.Future[None]":
         """
         Ensures that the debug daemon task is running.
 
+        This method checks if the debug daemon is already running and starts it if necessary. It will only start the daemon if it is not already running.
+
         Args:
             *args: Positional arguments for the debug daemon.
             **kwargs: Keyword arguments for the debug daemon.
 
         Returns:
             Either the debug daemon task or a dummy future if debug logging is not enabled.
+
+        Examples:
+            Ensuring the debug daemon is running:
+
+            .. code-block:: python
+
+                my_instance = MyDebugClass()
+                my_instance._ensure_debug_daemon()
+
+        See Also:
+            :meth:`_start_debug_daemon` for starting the daemon.
         """
         if not self.debug_logs_enabled:
             self._daemon = asyncio.get_event_loop().create_future()
@@ -70,11 +111,24 @@ class _DebugDaemonMixin(_LoggerMixin, metaclass=abc.ABCMeta):
         """
         Stops the debug daemon task.
 
+        This method cancels the debug daemon task if it is running. Raises a ValueError if the task to be stopped is not the current daemon.
+
         Args:
             t (optional): The task to be stopped, if any.
 
         Raises:
             ValueError: If `t` is not the current daemon.
+
+        Examples:
+            Stopping the debug daemon:
+
+            .. code-block:: python
+
+                my_instance = MyDebugClass()
+                my_instance._stop_debug_daemon()
+
+        See Also:
+            :meth:`_ensure_debug_daemon` for ensuring the daemon is running.
         """
         if t and t != self._daemon:
             raise ValueError(f"{t} is not {self._daemon}")

a_sync/primitives/_loggable.py

@@ -11,19 +11,41 @@ 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__
+        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)
@@ -33,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/counter.py

@@ -1,5 +1,5 @@
 """
-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 manage :class:`asyncio.Task` objects that must wait for an internal counter to reach a specific value.
 """
@@ -21,17 +21,25 @@ class CounterLock(_DebugDaemonMixin):
     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: 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."""
@@ -51,6 +59,13 @@ class CounterLock(_DebugDaemonMixin):
 
         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.
         """
         if not self.is_ready(value):
             self._ensure_debug_daemon()
@@ -61,15 +76,36 @@ class CounterLock(_DebugDaemonMixin):
         """
         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.
         """
         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}>"
 
@@ -77,6 +113,11 @@ class CounterLock(_DebugDaemonMixin):
     def value(self) -> int:
         """
         Gets the current value of the counter.
+
+        Examples:
+            >>> counter = CounterLock(start_value=0)
+            >>> counter.value
+            0
         """
         return self._value
 
@@ -90,6 +131,16 @@ 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
@@ -106,6 +157,8 @@ class CounterLock(_DebugDaemonMixin):
     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:
@@ -117,28 +170,42 @@ class CounterLock(_DebugDaemonMixin):
 
 class CounterLockCluster:
     """
-    An asyncio primitive that represents a collection of CounterLock objects.
+    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.
 
-    `wait_for(i)` will wait until the value of all CounterLock objects is >= i.
+    See Also:
+        :class:`CounterLock` for managing individual counters.
     """
 
     __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.
+
+        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]

a_sync/primitives/locks/prio_semaphore.py

@@ -30,8 +30,13 @@ 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.
+    priorities are processed before those with lower priorities. Subclasses must define the
+    `_top_priority` property to specify the default top priority behavior.
+
+    The `_context_manager_class` property should return the class used for managing semaphore contexts.
+
+    See Also:
+        :class:`PrioritySemaphore` for an implementation using numeric priorities.
     """
 
     name: Optional[str]
@@ -55,7 +60,13 @@ class _AbstractPrioritySemaphore(Semaphore, Generic[PT, CM]):
 
     @property
     def _top_priority(self) -> PT:
-        # You can use this so you can set priorities with non numeric comparable values
+        """Defines the top priority for the semaphore.
+
+        Subclasses must implement this property to specify the default top priority.
+
+        Raises:
+            NotImplementedError: If not implemented in a subclass.
+        """
         raise NotImplementedError
 
     def __init__(self, value: int = 1, *, name: Optional[str] = None) -> None:
@@ -64,6 +75,9 @@ class _AbstractPrioritySemaphore(Semaphore, Generic[PT, CM]):
         Args:
             value: The initial capacity of the semaphore.
             name: An optional name for the semaphore, used for debugging.
+
+        Examples:
+            >>> semaphore = _AbstractPrioritySemaphore(5, name="test_semaphore")
         """
 
         self._context_managers = {}
@@ -85,15 +99,36 @@ class _AbstractPrioritySemaphore(Semaphore, Generic[PT, CM]):
         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."""
+        """Enters the semaphore context, acquiring it with the top priority.
+
+        This method is part of the asynchronous context management protocol.
+
+        Examples:
+            >>> semaphore = _AbstractPrioritySemaphore(5)
+            >>> async with semaphore:
+            ...     await do_stuff()
+        """
         await self[self._top_priority].acquire()
 
     async def __aexit__(self, *_) -> None:
-        """Exits the semaphore context, releasing it with the top priority."""
+        """Exits the semaphore context, releasing it with the top priority.
+
+        This method is part of the asynchronous context management protocol.
+
+        Examples:
+            >>> semaphore = _AbstractPrioritySemaphore(5)
+            >>> async with semaphore:
+            ...     await do_stuff()
+        """
         self[self._top_priority].release()
 
     async def acquire(self) -> Literal[True]:
-        """Acquires the semaphore with the top priority."""
+        """Acquires the semaphore with the top priority.
+
+        Examples:
+            >>> semaphore = _AbstractPrioritySemaphore(5)
+            >>> await semaphore.acquire()
+        """
         return await self[self._top_priority].acquire()
 
     def __getitem__(
@@ -106,6 +141,10 @@ class _AbstractPrioritySemaphore(Semaphore, Generic[PT, CM]):
 
         Returns:
             The context manager associated with the given priority.
+
+        Examples:
+            >>> semaphore = _AbstractPrioritySemaphore(5)
+            >>> context_manager = semaphore[priority]
         """
         priority = self._top_priority if priority is None else priority
         if priority not in self._context_managers:
@@ -121,6 +160,10 @@ class _AbstractPrioritySemaphore(Semaphore, Generic[PT, CM]):
 
         Returns:
             True if the semaphore cannot be acquired immediately, False otherwise.
+
+        Examples:
+            >>> semaphore = _AbstractPrioritySemaphore(5)
+            >>> semaphore.locked()
         """
         return self._value == 0 or (
             any(
@@ -134,6 +177,10 @@ class _AbstractPrioritySemaphore(Semaphore, Generic[PT, CM]):
 
         Returns:
             A dictionary mapping each priority to the number of waiters.
+
+        Examples:
+            >>> semaphore = _AbstractPrioritySemaphore(5)
+            >>> semaphore._count_waiters()
         """
         return {
             manager._priority: len(manager.waiters)
@@ -146,6 +193,12 @@ class _AbstractPrioritySemaphore(Semaphore, Generic[PT, CM]):
         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.
+
+        The emergency procedure is a temporary measure to address potential issues with lost waiters.
+
+        Examples:
+            >>> semaphore = _AbstractPrioritySemaphore(5)
+            >>> semaphore._wake_up_next()
         """
         while self._waiters:
             manager = heapq.heappop(self._waiters)
@@ -230,6 +283,10 @@ class _AbstractPrioritySemaphoreContextManager(Semaphore, Generic[PT]):
             parent: The parent semaphore.
             priority: The priority associated with this context manager.
             name: An optional name for the context manager, used for debugging.
+
+        Examples:
+            >>> parent_semaphore = _AbstractPrioritySemaphore(5)
+            >>> context_manager = _AbstractPrioritySemaphoreContextManager(parent_semaphore, priority=1)
         """
 
         self._parent = parent
@@ -256,6 +313,14 @@ class _AbstractPrioritySemaphoreContextManager(Semaphore, Generic[PT]):
 
         Returns:
             True if this context manager has a lower priority than the other, False otherwise.
+
+        Raises:
+            TypeError: If the other object is not of the same type.
+
+        Examples:
+            >>> cm1 = _AbstractPrioritySemaphoreContextManager(parent, priority=1)
+            >>> cm2 = _AbstractPrioritySemaphoreContextManager(parent, priority=2)
+            >>> cm1 < cm2
         """
         if type(other) is not type(self):
             raise TypeError(f"{other} is not type {self.__class__.__name__}")
@@ -281,6 +346,10 @@ class _AbstractPrioritySemaphoreContextManager(Semaphore, Generic[PT]):
         zero on entry, block, waiting until some other coroutine has
         called release() to make it larger than 0, and then return
         True.
+
+        Examples:
+            >>> context_manager = _AbstractPrioritySemaphoreContextManager(parent, priority=1)
+            >>> await context_manager.acquire()
         """
         if self._parent._value <= 0:
             self._ensure_debug_daemon()
@@ -300,7 +369,12 @@ class _AbstractPrioritySemaphoreContextManager(Semaphore, Generic[PT]):
         return True
 
     def release(self) -> None:
-        """Releases the semaphore for this context manager."""
+        """Releases the semaphore for this context manager.
+
+        Examples:
+            >>> context_manager = _AbstractPrioritySemaphoreContextManager(parent, priority=1)
+            >>> context_manager.release()
+        """
         self._parent.release()
 
 
@@ -315,7 +389,9 @@ class _PrioritySemaphoreContextManager(
 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:
+    This class extends :class:`_AbstractPrioritySemaphore` and provides a concrete implementation
+    using numeric priorities. The `_context_manager_class` is set to :class:`_PrioritySemaphoreContextManager`,
+    and the `_top_priority` is set to -1, which is the highest priority.
 
     Examples:
         The primary way to use this semaphore is by specifying a priority.
@@ -329,6 +405,9 @@ class PrioritySemaphore(_AbstractPrioritySemaphore[Numeric, _PrioritySemaphoreCo
         >>> priority_semaphore = PrioritySemaphore(10)
         >>> async with priority_semaphore:
         ...     await do_stuff()
+
+    See Also:
+        :class:`_AbstractPrioritySemaphore` for the base class implementation.
     """
 
     _context_manager_class = _PrioritySemaphoreContextManager