initial documentation effort

Author: mikeshardmind

async_utils/__init__.py

@@ -1,16 +1,12 @@
-#   Copyright 2020-present Michael Hall
-#
-#   Licensed under the Apache License, Version 2.0 (the "License");
-#   you may not use this file except in compliance with the License.
-#   You may obtain a copy of the License at
-#
-#       http://www.apache.org/licenses/LICENSE-2.0
-#
-#   Unless required by applicable law or agreed to in writing, software
-#   distributed under the License is distributed on an "AS IS" BASIS,
-#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-#   See the License for the specific language governing permissions and
-#   limitations under the License.
+"""A Collection of async and other concurrency utilities.
 
+:copyright: (c) 2020-present Michael Hall
+:license: Apache License, Version 2.0, see LICENSE for more details.
 
+"""
+
+__title__ = "async_utils"
+__author__ = "Michael Hall"
+__license__ = "Apache-2.0"
+__copyright__ = "Copyright 2020-Present Michael Hall"
 __version__ = "2024.11.23"

async_utils/_cpython_stuff.py

@@ -25,7 +25,7 @@ def __init__(
         self,
         tup: tuple[Any, ...],
         hash: Callable[[object], int] = hash,  # noqa: A002
-    ):
+    ) -> None:
         self[:] = tup
         self.hashvalue: int = hash(tup)
 

async_utils/_lru.py

@@ -12,30 +12,58 @@
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
 
+"""LRU Implementation.
+
+This is currently re-exported in task_cache.py
+"""
+
 from __future__ import annotations
 
 __all__ = ("LRU",)
 
 
 class LRU[K, V]:
-    def __init__(self, maxsize: int, /):
-        self.cache: dict[K, V] = {}
-        self.maxsize = maxsize
+    """An LRU implementation.
+
+    Parameters
+    ----------
+    maxsize: int
+        The maximum number of items to retain
+    """
+
+    def __init__(self, maxsize: int, /) -> None:
+        self._cache: dict[K, V] = {}
+        self._maxsize = maxsize
 
     def get[T](self, key: K, default: T, /) -> V | T:
+        """Get a value by key or default value.
+
+        You should only use this when you have a default.
+        Otherwise, use index into the LRU by key.
+
+        Args:
+            key: The key to lookup a value for
+            default: A default value
+
+        Returns
+        -------
+            Either the value associated to a key-value pair in the LRU
+            or the specified default
+
+        """
         try:
             return self[key]
         except KeyError:
             return default
 
     def __getitem__(self, key: K, /) -> V:
-        val = self.cache[key] = self.cache.pop(key)
+        val = self._cache[key] = self._cache.pop(key)
         return val
 
-    def __setitem__(self, key: K, value: V, /):
-        self.cache[key] = value
-        if len(self.cache) > self.maxsize:
-            self.cache.pop(next(iter(self.cache)))
+    def __setitem__(self, key: K, value: V, /) -> None:
+        self._cache[key] = value
+        if len(self._cache) > self._maxsize:
+            self._cache.pop(next(iter(self._cache)))
 
     def remove(self, key: K, /) -> None:
-        self.cache.pop(key, None)
+        self._cache.pop(key, None)

async_utils/bg_loop.py

@@ -12,6 +12,8 @@
 #   See the License for the specific language governing permissions and
 #   limitations under the License.
 
+"""Background loop management."""
+
 from __future__ import annotations
 
 import asyncio
@@ -21,26 +23,44 @@
 from contextlib import contextmanager
 from typing import Any, TypeVar
 
-_T = TypeVar("_T")
+T = TypeVar("T")
 
-type _FutureLike[_T] = asyncio.Future[_T] | Awaitable[_T]
+type _FutureLike[T] = asyncio.Future[T] | Awaitable[T]
 
 __all__ = ["threaded_loop"]
 
 
 class LoopWrapper:
-    def __init__(self, loop: asyncio.AbstractEventLoop):
+    def __init__(self, loop: asyncio.AbstractEventLoop) -> None:
         self._loop = loop
 
-    def stop(self) -> None:
-        self._loop.call_soon_threadsafe(self._loop.stop)
+    def schedule(self, coro: _FutureLike[T], /) -> Future[T]:
+        """Schedule a coroutine to run on the wrapped event loop.
+
+        Parameters
+        ----------
+        coro:
+            A thread-safe coroutine-like object
 
-    def schedule(self, coro: _FutureLike[_T]) -> Future[_T]:
-        """Schedule a coroutine to run on the wrapped event loop."""
+        Returns
+        -------
+        asyncio.Future:
+            A Future wrapping the result.
+        """
         return asyncio.run_coroutine_threadsafe(coro, self._loop)
 
-    async def run(self, coro: _FutureLike[_T]) -> _T:
-        """Schedule and await a coroutine to run on the background loop."""
+    async def run(self, coro: _FutureLike[T], /) -> T:
+        """Schedule and await a coroutine to run on the background loop.
+
+        Parameters
+        ----------
+        coro:
+            A thread-safe coroutine-like object
+
+        Returns
+        -------
+        The returned value of the coroutine run in the background
+        """
         future = asyncio.run_coroutine_threadsafe(coro, self._loop)
         return await asyncio.wrap_future(future)
 
@@ -92,7 +112,12 @@ def threaded_loop(
     and yields an object with scheduling methods for interacting with
     the loop.
 
-    loop is scheduled for shutdown, and thread is joined at contextmanager exit
+    Loop is scheduled for shutdown, and thread is joined at contextmanager exit
+
+    Yields
+    ------
+    LoopWrapper
+        A wrapper with methods for interacting with the background loop.
     """
     loop = asyncio.new_event_loop()
     thread = None

async_utils/bg_tasks.py

@@ -27,7 +27,17 @@
 
 
 class BGTasks:
-    """An intentionally dumber task group."""
+    """An intentionally dumber task group.
+
+    Parameters
+    ----------
+    exit_timeout: int | None
+        Optionally, the number of seconds to wait before timing out tasks.
+        In applications that care about graceful shutdown, this should
+        usually not be set. When not providedd, the context manager
+        will not exit until all tasks have ended.
+
+    """
 
     def __init__(self, exit_timeout: float | None) -> None:
         self._tasks: set[asyncio.Task[Any]] = set()
@@ -40,15 +50,21 @@ def create_task(
         name: str | None = None,
         context: Context | None = None,
     ) -> asyncio.Task[_T]:
-        t = asyncio.create_task(coro)
+        """Create a task bound managed by this context manager.
+
+        Returns
+        -------
+        asyncio.Task: The task that was created.
+        """
+        t = asyncio.create_task(coro, name=name, context=context)
         self._tasks.add(t)
         t.add_done_callback(self._tasks.discard)
         return t
 
     async def __aenter__(self: Self) -> Self:
         return self
 
-    async def __aexit__(self, *_dont_care: object):
+    async def __aexit__(self, *_dont_care: object) -> None:
         while tsks := self._tasks.copy():
             _done, _pending = await asyncio.wait(tsks, timeout=self._etime)
             for task in _pending:

async_utils/corofunc_cache.py

@@ -36,7 +36,7 @@
 def corocache(
     ttl: float | None = None,
 ) -> Callable[[CoroLike[P, R]], CoroFunc[P, R]]:
-    """Decorator to cache coroutine functions.
+    """Cache the results of the decorated coroutine.
 
     This is less powerful than the version in task_cache.py but may work better
     for some cases where typing of libraries this interacts with is too
@@ -48,6 +48,15 @@ def corocache(
     feasible in cases where this may matter.
 
     The ordering of args and kwargs matters.
+
+    Parameters
+    ----------
+    ttl: float | None
+        The time to live in seconds for cached results. Defaults to None (forever)
+
+    Returns
+    -------
+    A decorator which wraps coroutine-like functions with preemptive caching.
     """
 
     def wrapper(coro: CoroLike[P, R]) -> CoroFunc[P, R]:
@@ -87,7 +96,7 @@ def _lru_evict(
 def lrucorocache(
     ttl: float | None = None, maxsize: int = 1024
 ) -> Callable[[CoroLike[P, R]], CoroFunc[P, R]]:
-    """Decorator to cache coroutine functions.
+    """Cache the results of the decorated coroutine.
 
     This is less powerful than the version in task_cache.py but may work better
     for some cases where typing of libraries this interacts with is too
@@ -101,6 +110,19 @@ def lrucorocache(
     The ordering of args and kwargs matters.
 
     Cached results are evicted by LRU and ttl.
+
+    Parameters
+    ----------
+    ttl: float | None
+        The time to live in seconds for cached results. Defaults to None (forever)
+    maxsize: int
+        The maximum number of items to retain no matter if they have reached
+        expiration by ttl or not.
+        Items evicted by this policy are evicted by least recent use.
+
+    Returns
+    -------
+    A decorator which wraps coroutine-like functions with preemptive caching.
     """
 
     def wrapper(coro: CoroLike[P, R]) -> CoroFunc[P, R]:

async_utils/gen_transform.py

@@ -84,6 +84,19 @@ def sync_to_async_gen(
     If your generator is actually a synchronous coroutine, that's super cool,
     but rewrite is as a native coroutine or use it directly then, you don't need
     what this function does.
+
+    Parameters
+    ----------
+    f:
+        The synchronous generator function to wrap.
+    *args:
+        The positional args to pass to the generator construction.
+    **kwargs:
+        The keyword arguments to pass to the generator construction.
+
+    Returns
+    -------
+    An asynchronous iterator which yields the results of the wrapped generator.
     """
     # Provides backpressure, ensuring the underlying sync generator in a thread
     # is lazy If the user doesn't want laziness, then using this method makes