Remaining docstrings pre-prose docs

Author: mikeshardmind

pyproject.toml

@@ -39,6 +39,8 @@ select = [
 typing-modules = ["async_utils._typings"]
 
 ignore = [
+    "DOC201", # Not docing generic return types
+    "DOC501", # Not explicitly documenting raised exception types
     "ANN202", # implied return fine sometimes
     "ANN401",  # Any is the correct type in some cases
     "ASYNC116", # Long sleeps are fine

src/async_utils/_qs.py

@@ -28,11 +28,11 @@
 
 
 class QueueEmpty(Exception):
-    pass
+    """Raised when a queue is empty and attempting to get without waiting."""
 
 
 class QueueFull(Exception):
-    pass
+    """Raised when a queue is full and attempting to put without waiting."""
 
 
 class AsyncEvent:
@@ -190,7 +190,15 @@ def set(self, /) -> bool:
         return success
 
 
-class _BaseQueue[T]:
+class BaseQueue[T]:
+    """Base queue implementation.
+
+    Not meant for direct public use. You probably should use
+    one of the provided subclasses.
+
+    May make sense as a type annotation.
+    """
+
     __slots__ = ("__get_ws", "__put_ws", "__unlocked", "__unlocked", "__ws", "maxsize")
 
     def __init__(self, /, maxsize: int | None = None) -> None:
@@ -302,6 +310,7 @@ def _release(self, /) -> None:
             break
 
     async def async_put(self, item: T, /) -> None:
+        """Put an item into the queue."""
         waiters = self.__ws
         put_waiters = self.__put_ws
         success = self._acquire_nowait_put()
@@ -339,6 +348,15 @@ async def async_put(self, item: T, /) -> None:
     def sync_put(
         self, item: T, /, *, blocking: bool = True, timeout: float | None = None
     ) -> None:
+        """Put an item into the queue.
+
+        Parameters
+        ----------
+        blocking: bool
+            Whether or not to block until space in the queue is available.
+        timeout: float | None
+            The maximum time to wait if waiting on room in the queue.
+        """
         waiters = self.__ws
         put_waiters = self.__put_ws
         success = self._acquire_nowait_put()
@@ -377,6 +395,7 @@ def sync_put(
                 self._release()
 
     async def async_get(self, /) -> T:
+        """Get an item from the queue."""
         waiters = self.__ws
         get_waiters = self.__get_ws
         success = self._acquire_nowait_get()
@@ -414,6 +433,15 @@ async def async_get(self, /) -> T:
         return item
 
     def sync_get(self, /, *, blocking: bool = True, timeout: float | None = None) -> T:
+        """Get an item from the queue.
+
+        Parameters
+        ----------
+        blocking: bool
+            Whether or not to block until an item is available.
+        timeout: float | None
+            The maximum time to wait if waiting on an item.
+        """
         waiters = self.__ws
         get_waiters = self.__get_ws
 
@@ -479,7 +507,7 @@ def getting(self, /) -> int:
         return len(self.__get_ws)
 
 
-class Queue[T](_BaseQueue[T]):
+class Queue[T](BaseQueue[T]):
     """A thread-safe queue with both sync and async access methods."""
 
     __slots__ = ("_data",)
@@ -507,7 +535,7 @@ def _get(self, /) -> T:
         return self._data.popleft()
 
 
-class LIFOQueue[T](_BaseQueue[T]):
+class LIFOQueue[T](BaseQueue[T]):
     """A thread-safe queue with both sync and async access methods."""
 
     __slots__ = ("_data",)
@@ -535,7 +563,7 @@ def _get(self, /) -> T:
         return self._data.pop()
 
 
-class PriorityQueue[T](_BaseQueue[T]):
+class PriorityQueue[T](BaseQueue[T]):
     """A thread-safe queue with both sync and async access methods."""
 
     __slots__ = ("_data",)

src/async_utils/bg_loop.py

@@ -30,6 +30,11 @@
 
 
 class LoopWrapper:
+    """Provides managed access to an event loop created with ``threaded_loop``.
+
+    This is not meant to be constructed manually
+    """
+
     def __init_subclass__(cls) -> t.Never:
         msg = "Don't subclass this"
         raise RuntimeError(msg)
@@ -97,7 +102,7 @@ def wait_sync(self, timeout: float | None) -> bool:
         return not pending
 
 
-def run_forever(
+def _run_forever(
     loop: asyncio.AbstractEventLoop,
     /,
     *,
@@ -157,7 +162,7 @@ def threaded_loop(
     wrapper = None
     try:
         args, kwargs = (loop,), {"eager": use_eager_task_factory}
-        thread = threading.Thread(target=run_forever, args=args, kwargs=kwargs)
+        thread = threading.Thread(target=_run_forever, args=args, kwargs=kwargs)
         thread.start()
         wrapper = LoopWrapper(loop)
         yield wrapper

src/async_utils/dual_color.py

@@ -14,6 +14,6 @@
 
 from __future__ import annotations
 
-from ._qs import LIFOQueue, PriorityQueue, Queue, QueueEmpty, QueueFull
+from ._qs import BaseQueue, LIFOQueue, PriorityQueue, Queue, QueueEmpty, QueueFull
 
-__all__ = ("LIFOQueue", "PriorityQueue", "Queue", "QueueEmpty", "QueueFull")
+__all__ = ("BaseQueue", "LIFOQueue", "PriorityQueue", "Queue", "QueueEmpty", "QueueFull")

src/async_utils/priority_sem.py

@@ -31,7 +31,7 @@
 _priority: contextvars.ContextVar[int] = contextvars.ContextVar("_priority", default=0)
 
 
-class PriorityWaiter:
+class _PriorityWaiter:
     __slots__ = ("future", "ord")
 
     def __init__(self, priority: int, ts: float, future: asyncio.Future[None], /) -> None:
@@ -53,7 +53,7 @@ def __await__(self) -> Generator[t.Any, t.Any, None]:
         return (yield from self.future.__await__())
 
     def __lt__(self: t.Self, other: object) -> bool:
-        if not isinstance(other, PriorityWaiter):
+        if not isinstance(other, _PriorityWaiter):
             return NotImplemented
         return self.ord < other.ord
 
@@ -119,7 +119,7 @@ def __init__(self, value: int = 1) -> None:
         if value < 0:
             msg = "Semaphore initial value must be >= 0"
             raise ValueError(msg)
-        self._waiters: list[PriorityWaiter] | None = None
+        self._waiters: list[_PriorityWaiter] | None = None
         self._value: int = value
 
     def _get_loop(self) -> asyncio.AbstractEventLoop:
@@ -168,7 +168,7 @@ async def __acquire(self, priority: int = _default) -> bool:
 
         fut = loop.create_future()
         now = loop.time()
-        waiter = PriorityWaiter(priority, now, fut)
+        waiter = _PriorityWaiter(priority, now, fut)
 
         heapq.heappush(self._waiters, waiter)
 

src/async_utils/scheduler.py

@@ -20,12 +20,17 @@
 
 from . import _typings as t
 
-__all__ = ("Scheduler",)
+__all__ = ("CancellationToken", "Scheduler")
 
 MISSING: t.Any = object()
 
 
 class CancellationToken:
+    """An object to use for cancelation of a task.
+
+    Not meant for public construction.
+    """
+
     __slots__ = ()