From 07ac20cbcb262722c9fbdace35bc223953c89cb7 Mon Sep 17 00:00:00 2001
From: BobTheBuidler <70677534+BobTheBuidler@users.noreply.github.com>
Date: Thu, 21 Nov 2024 00:06:14 -0400
Subject: [PATCH] chore: copy module docstrings into python stub files (#411)

---
 a_sync/a_sync/_helpers.pyi      |  4 ++++
 a_sync/a_sync/abstract.pyi      | 10 ++++++++++
 a_sync/a_sync/method.pyi        |  7 +++++++
 a_sync/asyncio/create_task.pyi  |  5 +++++
 a_sync/asyncio/gather.pyi       |  4 ++++
 a_sync/primitives/_debug.pyi    |  5 +++++
 a_sync/primitives/_loggable.pyi |  3 +++
 a_sync/task.pyi                 |  9 +++++++++
 a_sync/task.pyx                 |  1 -
 9 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/a_sync/a_sync/_helpers.pyi b/a_sync/a_sync/_helpers.pyi
index dc1a2768..e6e236e7 100644
--- a/a_sync/a_sync/_helpers.pyi
+++ b/a_sync/a_sync/_helpers.pyi
@@ -1,3 +1,7 @@
+"""
+This module provides utility functions for handling asynchronous operations
+and converting synchronous functions to asynchronous ones.
+"""
 from a_sync._typing import *
 from a_sync import exceptions as exceptions
 
diff --git a/a_sync/a_sync/abstract.pyi b/a_sync/a_sync/abstract.pyi
index 7aab3d1a..4c2768bc 100644
--- a/a_sync/a_sync/abstract.pyi
+++ b/a_sync/a_sync/abstract.pyi
@@ -1,3 +1,13 @@
+"""
+This module provides an abstract base class for defining asynchronous and synchronous behavior.
+
+The :class:`ASyncABC` class uses the :class:`ASyncMeta` metaclass to facilitate the creation of classes
+that can operate in both asynchronous and synchronous contexts. It provides concrete methods to determine
+the execution mode based on flags and keyword arguments.
+
+Note: It is recommended to use :class:`ASyncGenericBase` for most use cases. This class
+is intended for more custom implementations if necessary.
+"""
 from a_sync._typing import *
 import abc
 import functools
diff --git a/a_sync/a_sync/method.pyi b/a_sync/a_sync/method.pyi
index 3cfe5bc3..f73ac1c2 100644
--- a/a_sync/a_sync/method.pyi
+++ b/a_sync/a_sync/method.pyi
@@ -1,3 +1,10 @@
+"""
+This module provides classes for implementing dual-functional sync/async methods in Python.
+
+It includes descriptors and bound methods that can be used to create flexible
+asynchronous interfaces, allowing methods to be called both synchronously and
+asynchronously based on various conditions and configurations.
+"""
 from a_sync._typing import *
 import functools
 import weakref
diff --git a/a_sync/asyncio/create_task.pyi b/a_sync/asyncio/create_task.pyi
index c9b250cd..d01d8159 100644
--- a/a_sync/asyncio/create_task.pyi
+++ b/a_sync/asyncio/create_task.pyi
@@ -1,3 +1,8 @@
+"""
+This module extends :func:`asyncio.create_task` to support any :class:`Awaitable`,
+manage task lifecycle, and enhance error handling.
+"""
+
 from a_sync._typing import *
 import asyncio
 
diff --git a/a_sync/asyncio/gather.pyi b/a_sync/asyncio/gather.pyi
index 712a5bbd..8252f742 100644
--- a/a_sync/asyncio/gather.pyi
+++ b/a_sync/asyncio/gather.pyi
@@ -1,3 +1,7 @@
+"""
+This module provides an enhanced version of :func:`asyncio.gather`.
+"""
+
 from a_sync._typing import *
 from typing import Any, Awaitable, Dict, List, Mapping, overload
 
diff --git a/a_sync/primitives/_debug.pyi b/a_sync/primitives/_debug.pyi
index 7d913243..00823583 100644
--- a/a_sync/primitives/_debug.pyi
+++ b/a_sync/primitives/_debug.pyi
@@ -1,3 +1,8 @@
+"""
+This module provides a mixin class used to facilitate the creation of debugging daemons in subclasses.
+
+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
 from a_sync.primitives._loggable import _LoggerMixin
 
diff --git a/a_sync/primitives/_loggable.pyi b/a_sync/primitives/_loggable.pyi
index 614db33f..7d2beb1a 100644
--- a/a_sync/primitives/_loggable.pyi
+++ b/a_sync/primitives/_loggable.pyi
@@ -1,3 +1,6 @@
+"""
+This module provides a mixin class to add debug logging capabilities to other classes.
+"""
 from functools import cached_property as cached_property
 from logging import Logger
 
diff --git a/a_sync/task.pyi b/a_sync/task.pyi
index 5ea557b4..14766f6e 100644
--- a/a_sync/task.pyi
+++ b/a_sync/task.pyi
@@ -1,3 +1,12 @@
+"""
+This module provides asynchronous task management utilities, specifically focused on creating and handling mappings of tasks.
+
+The main components include:
+- TaskMapping: A class for managing and asynchronously generating tasks based on input iterables.
+- TaskMappingKeys: A view to asynchronously iterate over the keys of a TaskMapping.
+- TaskMappingValues: A view to asynchronously iterate over the values of a TaskMapping.
+- TaskMappingItems: A view to asynchronously iterate over the items (key-value pairs) of a TaskMapping.
+"""
 from a_sync._typing import *
 import asyncio
 from _typeshed import Incomplete
diff --git a/a_sync/task.pyx b/a_sync/task.pyx
index c28eb072..b80b050b 100644
--- a/a_sync/task.pyx
+++ b/a_sync/task.pyx
@@ -19,7 +19,6 @@ import a_sync.asyncio
 from a_sync import exceptions
 from a_sync._typing import *
 from a_sync.a_sync._kwargs cimport get_flag_name
-from a_sync.a_sync.base import ASyncGenericBase
 from a_sync.a_sync.function import ASyncFunction
 from a_sync.a_sync.method import (
     ASyncBoundMethod,