ez-a-sync 0.22.6__tar.gz → 0.22.8__tar.gz

{ez_a_sync-0.22.6 → ez_a_sync-0.22.8}/.sourcery.yaml

@@ -31,7 +31,11 @@ ignore: # A list of paths or files which Sourcery will ignore.
 rule_settings:
   enable:
   - default
-  disable: [no-conditionals-in-tests, no-loop-in-tests]  # A list of rule IDs Sourcery will never suggest.
+  disable: [
+    no-conditionals-in-tests, 
+    no-loop-in-tests, 
+    dict-assign-update-to-union, # we want to be backward compatible with many pythons
+  ]  # A list of rule IDs Sourcery will never suggest.
   rule_types:
   - refactoring
   - suggestion

{ez_a_sync-0.22.6 → ez_a_sync-0.22.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ez-a-sync
-Version: 0.22.6
+Version: 0.22.8
 Summary: A library that makes it easy to define objects that can be used for both sync and async use cases.
 Home-page: https://github.com/BobTheBuidler/a-sync
 Author: BobTheBuidler

{ez_a_sync-0.22.6 → ez_a_sync-0.22.8}/a_sync/_typing.py

@@ -25,9 +25,13 @@ T = TypeVar("T")
 K = TypeVar("K")
 V = TypeVar("V")
 I = TypeVar("I")
+"""A :class:`TypeVar` that is used to represent instances of a common class."""
+
 E = TypeVar('E', bound=Exception)
 TYPE = TypeVar("TYPE", bound=Type)
+
 P = ParamSpec("P")
+"""A :class:`ParamSpec` used everywhere in the lib."""
 
 Numeric = Union[int, float, Decimal]
 """Type alias for numeric values of types int, float, or Decimal."""

{ez_a_sync-0.22.6 → ez_a_sync-0.22.8}/a_sync/a_sync/_descriptor.py

@@ -34,7 +34,7 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         **modifiers: ModifierKwargs,
     ) -> None:
         """
-        Initialize the ASyncDescriptor.
+        Initialize the {cls}.
 
         Args:
             _fget: The function to be wrapped.
@@ -56,7 +56,7 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
             self.__wrapped__ = _fget
 
         self.field_name = field_name or _fget.__name__
-        """The name of the field this descriptor is bound to."""
+        """The name of the field the {cls} is bound to."""
         
         functools.update_wrapper(self, self.__wrapped__)
 
@@ -65,7 +65,7 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
 
     def __set_name__(self, owner, name):
         """
-        Set the field name when the descriptor is assigned to a class.
+        Set the field name when the {cls} is assigned to a class.
 
         Args:
             owner: The class owning this descriptor.
@@ -211,3 +211,9 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
             The sum of the results.
         """
         return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).sum(pop=True, sync=False)
+
+    def __init_subclass__(cls) -> None:
+        for attr in cls.__dict__.values():
+            if attr.__doc__ and "{cls}" in attr.__doc__:
+                attr.__doc__ = attr.__doc__.replace("{cls}", f":class:`{cls.__name__}`")
+        return super().__init_subclass__()

{ez_a_sync-0.22.6 → ez_a_sync-0.22.8}/a_sync/a_sync/method.py

@@ -31,7 +31,7 @@ class ASyncMethodDescriptor(ASyncDescriptor[I, P, T]):
     """
 
     __wrapped__: AnyFn[P, T]
-    """The wrapped function."""
+    """The unbound function which will be bound to an instance when :meth:`__get__` is called."""
 
     async def __call__(self, instance: I, *args: P.args, **kwargs: P.kwargs) -> T:
         """
@@ -267,6 +267,9 @@ class ASyncBoundMethod(ASyncFunction[P, T], Generic[I, P, T]):
     __weakself__: "weakref.ref[I]"
     "A weak reference to the instance the function is bound to."
 
+    __wrapped__: AnyFn[Concatenate[I, P], T]
+    """The original unbound method that was wrapped."""
+
     __slots__ = "_is_async_def", "__weakself__"
 
     def __init__(

{ez_a_sync-0.22.6 → ez_a_sync-0.22.8}/a_sync/a_sync/property.py

@@ -3,6 +3,7 @@ import functools
 import logging
 
 import async_property as ap  # type: ignore [import]
+from typing_extensions import Unpack
 
 from a_sync import _smart, exceptions
 from a_sync._typing import *
@@ -29,7 +30,7 @@ class _ASyncPropertyDescriptorBase(ASyncDescriptor[I, Tuple[()], T]):
         self, 
         _fget: AsyncGetterFunction[I, T], 
         field_name: Optional[str] = None,
-        **modifiers: config.ModifierKwargs,
+        **modifiers: Unpack[ModifierKwargs],
     ) -> None:
         super().__init__(_fget, field_name, **modifiers)
         self.hidden_method_name = f"__{self.field_name}__"
@@ -390,7 +391,14 @@ def a_sync_cached_property(  # type: ignore [misc]
 
 @final
 class HiddenMethod(ASyncBoundMethodAsyncDefault[I, Tuple[()], T]):
-    def __init__(self, instance: I, unbound: AnyFn[Concatenate[I, P], T], async_def: bool, field_name: str, **modifiers: _helpers.ModifierKwargs) -> None:
+    def __init__(
+        self, 
+        instance: I, 
+        unbound: AnyFn[Concatenate[I, P], T], 
+        async_def: bool,
+        field_name: str,
+        **modifiers: Unpack[ModifierKwargs],
+    ) -> None:
         super().__init__(instance, unbound, async_def, **modifiers)
         self.__name__ = field_name
     def __repr__(self) -> str:
@@ -406,6 +414,30 @@ class HiddenMethod(ASyncBoundMethodAsyncDefault[I, Tuple[()], T]):
 
 @final
 class HiddenMethodDescriptor(ASyncMethodDescriptorAsyncDefault[I, Tuple[()], T]):
+    def __init__(
+        self, 
+        _fget: AnyFn[Concatenate[I, P], Awaitable[T]], 
+        field_name: Optional[str] = None, 
+        **modifiers: Unpack[ModifierKwargs],
+    ) -> None:
+        """
+        Initialize the HiddenMethodDescriptor.
+
+        Args:
+            _fget: The function to be wrapped.
+            field_name: Optional name for the field. If not provided, the function's name will be used.
+            **modifiers: Additional modifier arguments.
+
+        Raises:
+            ValueError: If _fget is not callable.
+        """
+        super().__init__(_fget, field_name, **modifiers)
+        if self.__doc__ is None:
+            self.__doc__ = f"A :class:`HiddenMethodDescriptor` for :meth:`{self.__wrapped__.__qualname__}`."
+        elif not self.__doc__:
+            self.__doc__ += f"A :class:`HiddenMethodDescriptor` for :meth:`{self.__wrapped__.__qualname__}`."
+        if self.__wrapped__.__doc__:
+            self.__doc__ += f"\n\nThe original docstring for :meth:`~{self.__wrapped__.__qualname__}` is shown below:\n\n{self.__wrapped__.__doc__}"
     def __get__(self, instance: I, owner: Type[I]) -> HiddenMethod[I, T]:
         if instance is None:
             return self

{ez_a_sync-0.22.6 → ez_a_sync-0.22.8}/a_sync/iter.py

@@ -43,27 +43,29 @@ class _AwaitableAsyncIterableMixin(AsyncIterable[T]):
         ```
     """
     __wrapped__: AsyncIterable[T]
-
-    def __init_subclass__(cls, **kwargs) -> None:
-        new = "When awaited, a list of all elements will be returned."
-        if cls.__doc__ is None:
-            cls.__doc__ = new
-        else:
-            cls.__doc__ += f"\n\n{new}"
-        return super().__init_subclass__(**kwargs)
     
     def __await__(self) -> Generator[Any, Any, List[T]]:
-        """Asynchronously iterates through all contents of ``Self`` and returns a ``list`` containing the results."""
+        """
+        Asynchronously iterate through the {cls} and return all objects.
+        
+        Returns:
+            A list of the objects yielded by the {cls}.
+        """
         return self._materialized.__await__()
 
     @property
     def materialized(self) -> List[T]:
-        """Iterates through all contents of ``Self`` and returns a ``list`` containing the results."""
+        """
+        Synchronously iterate through the {cls} and return all objects.
+        
+        Returns:
+            A list of the objects yielded by the {cls}.
+        """
         return _helpers._await(self._materialized)
 
     def sort(self, *, key: SortKey[T] = None, reverse: bool = False) -> "ASyncSorter[T]":
         """
-        Sorts the contents of the {cls}.
+        Sort the contents of the {cls}.
 
         Args:
             key (optional): A function of one argument that is used to extract a comparison key from each list element. If None, the elements themselves will be sorted. Defaults to None.
@@ -76,21 +78,43 @@ class _AwaitableAsyncIterableMixin(AsyncIterable[T]):
 
     def filter(self, function: ViewFn[T]) -> "ASyncFilter[T]":
         """
-        Filters the contents of the async iterable based on a function.
+        Filters the contents of the {cls} based on a function.
 
         Args:
             function: A function that returns a boolean that indicates if an item should be included in the filtered result. Can be sync or async.
 
         Returns:
-            An instance of :class:`~ASyncFilter` that will yield the filtered objects yielded from this instance.
+            An instance of :class:`~ASyncFilter` that yields the filtered objects from the {cls}.
         """
         return ASyncFilter(function, self)
 
     @async_cached_property
     async def _materialized(self) -> List[T]:
-        """Asynchronously iterates through all contents of ``Self`` and returns a ``list`` containing the results."""
+        """
+        Asynchronously iterate through the {cls} and return all objects.
+        
+        Returns:
+            A list of the objects yielded by the {cls}.
+        """
         return [obj async for obj in self]
 
+    def __init_subclass__(cls, **kwargs) -> None:
+        new = "When awaited, a list of all elements will be returned."
+
+        # modify the class docstring
+        if cls.__doc__ is None:
+            cls.__doc__ = new
+        else:
+            cls.__doc__ += f"\n\n{new}"
+    
+        # format the member docstrings
+        for attr_name in dir(cls):
+            attr = getattr(cls, attr_name)
+            if attr.__doc__ and "{cls}" in attr.__doc__:
+                attr.__doc__ = attr.__doc__.replace("{cls}", f":class:`{cls.__name__}`")
+
+        return super().__init_subclass__(**kwargs)
+
     __slots__ = '__async_property__', 
     
 class ASyncIterable(_AwaitableAsyncIterableMixin[T], Iterable[T]):
@@ -116,11 +140,13 @@ class ASyncIterable(_AwaitableAsyncIterableMixin[T], Iterable[T]):
         return f"<{type(self).__name__} for {self.__wrapped__} at {hex(id(self))}>"
 
     def __aiter__(self) -> AsyncIterator[T]:
-        "Returns an async iterator for the wrapped async iterable."
+        """
+        Return an async iterator that yields :obj:`T` objects from the {cls}.
+        """
         return self.__wrapped__.__aiter__()
 
     def __iter__(self) -> Iterator[T]:
-        "Returns an iterator for the wrapped async iterable."
+        "Return an iterator that yields :obj:`T` objects from the {cls}."
         yield from ASyncIterator(self.__aiter__())
     __slots__ = "__wrapped__", 
 
@@ -128,14 +154,20 @@ AsyncGenFunc = Callable[P, Union[AsyncGenerator[T, None], AsyncIterator[T]]]
 
 class ASyncIterator(_AwaitableAsyncIterableMixin[T], Iterator[T]):
     """
-    Description:
-        A hybrid Iterator/AsyncIterator implementation that bridges the gap between synchronous and asynchronous iteration. This class provides a unified interface for iteration that can seamlessly operate in both synchronous (`for` loop) and asynchronous (`async for` loop) contexts. It allows the wrapping of asynchronous iterable objects or async generator functions, making them usable in synchronous code without explicitly managing event loops or asynchronous context switches.
+    A hybrid Iterator/AsyncIterator implementation that bridges the gap between synchronous and asynchronous iteration. This class provides a unified interface for iteration that can seamlessly operate in both synchronous (`for` loop) and asynchronous (`async for` loop) contexts. It allows the wrapping of asynchronous iterable objects or async generator functions, making them usable in synchronous code without explicitly managing event loops or asynchronous context switches.
 
-        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.
+    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.
+    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.
     """
+    
     def __next__(self) -> T:
+        """
+        Synchronously fetch the next item from the {cls}.
+        
+        Raises:
+            :class:`StopIteration`: Once all items have been fetched from the {cls}.
+        """
         try:
             return asyncio.get_event_loop().run_until_complete(self.__anext__())
         except StopAsyncIteration as e:
@@ -164,24 +196,32 @@ class ASyncIterator(_AwaitableAsyncIterableMixin[T], Iterator[T]):
         if not isinstance(async_iterator, AsyncIterator):
             raise TypeError(f"`async_iterator` must be an AsyncIterator. You passed {async_iterator}")
         self.__wrapped__ = async_iterator
-        "The wrapped async iterator object."
+        "The wrapped :class:`AsyncIterator`."
 
     async def __anext__(self) -> T:
-        "Asynchronously fetches the next item from the async iterator."
+        """
+        Asynchronously fetch the next item from the {cls}.
+        
+        Raises:
+            :class:`StopAsyncIteration`: Once all items have been fetched from the {cls}.
+        """
         return await self.__wrapped__.__anext__()
 
-    def __aiter__(self) -> AsyncIterator[T]:
-        "Returns self."
+    def __iter__(self) -> Self:
+        "Return the {cls} for iteration."
+        return self
+
+    def __aiter__(self) -> Self:
+        "Return the {cls} for aiteration."
         return self
 
 class ASyncGeneratorFunction(Generic[P, T]):
     """
-    Description:
-        Encapsulates an asynchronous generator function, providing a mechanism to use it as an asynchronous iterator with enhanced capabilities. This class wraps an async generator function, allowing it to be called with parameters and return an :class:`~ASyncIterator` object. It is particularly useful for situations where an async generator function needs to be used in a manner that is consistent with both synchronous and asynchronous execution contexts.
+    Encapsulates an asynchronous generator function, providing a mechanism to use it as an asynchronous iterator with enhanced capabilities. This class wraps an async generator function, allowing it to be called with parameters and return an :class:`~ASyncIterator` object. It is particularly useful for situations where an async generator function needs to be used in a manner that is consistent with both synchronous and asynchronous execution contexts.
 
-        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.
+    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.
+    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.
     """
 
     _cache_handle: asyncio.TimerHandle
@@ -191,11 +231,20 @@ class ASyncGeneratorFunction(Generic[P, T]):
     "A weak reference to the instance the function is bound to, if any."
 
     def __init__(self, async_gen_func: AsyncGenFunc[P, T], instance: Any = None) -> None:
-        "Initializes the ASyncGeneratorFunction with the given async generator function and optionally an instance."
+        """
+        Initializes the ASyncGeneratorFunction with the given async generator function and optionally an instance.
+
+        Args:
+            async_gen_func: The async generator function to wrap.
+            instance (optional): The object to bind to the function, if applicable.
+        """
+        
         self.field_name = async_gen_func.__name__
         "The name of the async generator function."
+
         self.__wrapped__ = async_gen_func
         "The actual async generator function."
+
         if instance is not None:
             self._cache_handle = self.__get_cache_handle(instance)
             self.__weakself__ = weakref.ref(instance, self.__cancel_cache_handle)
@@ -205,7 +254,16 @@ class ASyncGeneratorFunction(Generic[P, T]):
         return f"<{type(self).__name__} for {self.__wrapped__} at {hex(id(self))}>"
 
     def __call__(self, *args: P.args, **kwargs: P.kwargs) -> ASyncIterator[T]:
-        "Calls the wrapped async generator function with the given arguments and keyword arguments, returning an ASyncIterator."
+        """
+        Calls the wrapped async generator function with the given arguments and keyword arguments, returning an :class:`ASyncIterator`.
+
+        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))
         return ASyncIterator(self.__wrapped__(self.__self__, *args, **kwargs))
@@ -257,7 +315,7 @@ class _ASyncView(ASyncIterator[T]):
         iterable: AnyIterable[T],
     ) -> None:
         """
-        Initializes the `_ASyncView` with a function and an iterable.
+        Initializes the {cls} with a function and an iterable.
 
         Args:
             function: A function to apply to the items in the iterable.
@@ -360,7 +418,7 @@ class ASyncSorter(_ASyncView[T]):
 
     def __aiter__(self) -> AsyncIterator[T]:
         """
-        Returns an async iterator for the sorted iterable.
+        Return an async iterator for the {cls}.
 
         Raises:
             RuntimeError: If the ASyncSorter instance has already been consumed.

{ez_a_sync-0.22.6 → ez_a_sync-0.22.8}/a_sync/utils/iterators.py

@@ -13,10 +13,9 @@ logger = logging.getLogger(__name__)
 
 async def exhaust_iterator(iterator: AsyncIterator[T], *, queue: Optional[asyncio.Queue] = None) -> None:
     """
-    Description:
-        Asynchronously iterates over items from the given async iterator and optionally places them into a queue.
-    
-        This function is a utility to exhaust an async iterator, with an option to forward the iterated items to a provided asyncio.Queue. It's particularly useful when dealing with asynchronous operations that produce items to be consumed by other parts of an application, enabling a producer-consumer pattern.
+    Asynchronously iterates over items from the given async iterator and optionally places them into a queue.
+
+    This function is a utility to exhaust an async iterator, with an option to forward the iterated items to a provided asyncio.Queue. It's particularly useful when dealing with asynchronous operations that produce items to be consumed by other parts of an application, enabling a producer-consumer pattern.
 
     Args:
         iterator (AsyncIterator[T]): The async iterator to exhaust.
@@ -33,10 +32,9 @@ async def exhaust_iterator(iterator: AsyncIterator[T], *, queue: Optional[asynci
 
 async def exhaust_iterators(iterators, *, queue: Optional[asyncio.Queue] = None, join: bool = False) -> None:
     """    
-    Description:
-        Asynchronously iterates over multiple async iterators concurrently and optionally places their items into a queue.
-    
-        This function leverages asyncio.gather to concurrently exhaust multiple async iterators. It's useful in scenarios where items from multiple async sources need to be processed or collected together, supporting concurrent operations and efficient multitasking.
+    Asynchronously iterates over multiple async iterators concurrently and optionally places their items into a queue.
+
+    This function leverages asyncio.gather to concurrently exhaust multiple async iterators. It's useful in scenarios where items from multiple async sources need to be processed or collected together, supporting concurrent operations and efficient multitasking.
 
     Args:
         iterators: A sequence of async iterators to be exhausted concurrently.
@@ -93,12 +91,11 @@ def as_yielded(iterator0: AsyncIterator[T0], iterator1: AsyncIterator[T1]) -> As
 def as_yielded(iterator0: AsyncIterator[T0], iterator1: AsyncIterator[T1], iterator2: AsyncIterator[T2], *iterators: AsyncIterator[T]) -> AsyncIterator[Union[T0, T1, T2, T]]:...
 async def as_yielded(*iterators: AsyncIterator[T]) -> AsyncIterator[T]:  # type: ignore [misc]
     """
-    Description:
-        Merges multiple async iterators into a single async iterator that yields items as they become available from any of the source iterators.
+    Merges multiple async iterators into a single async iterator that yields items as they become available from any of the source iterators.
 
-        This function is designed to streamline the handling of multiple asynchronous data streams by consolidating them into a single asynchronous iteration context. It enables concurrent fetching and processing of items from multiple sources, improving efficiency and simplifying code structure when dealing with asynchronous operations.
+    This function is designed to streamline the handling of multiple asynchronous data streams by consolidating them into a single asynchronous iteration context. It enables concurrent fetching and processing of items from multiple sources, improving efficiency and simplifying code structure when dealing with asynchronous operations.
 
-        The merging process is facilitated by internally managing a queue where items from the source iterators are placed as they are fetched. This mechanism ensures that the merged stream of items is delivered in an order determined by the availability of items from the source iterators, rather than their original sequence.
+    The merging process is facilitated by internally managing a queue where items from the source iterators are placed as they are fetched. This mechanism ensures that the merged stream of items is delivered in an order determined by the availability of items from the source iterators, rather than their original sequence.
 
     Args:
         *iterators: Variable length list of AsyncIterator objects to be merged.

{ez_a_sync-0.22.6 → ez_a_sync-0.22.8}/docs/conf.py

@@ -65,6 +65,7 @@ autodoc_default_options = {
         '_ASyncSingletonMeta__lock',
         '_is_protocol',
         '_is_runtime_protocol',
+        '_materialized',
     ]),
 }
 
@@ -88,7 +89,7 @@ SKIP_MODULES = [
 
 def skip_undesired_members(app, what, name, obj, skip, options):
     # skip some submodules (not sure if this works right or if its even desired)
-    if what == "module" and obj.__name__ in SKIP_MODULES:
+    if what == "module" and getattr(obj, '__name__', None) in SKIP_MODULES:
         skip = True
     
     # Skip the __init__, __str__, __getattribute__, args, and with_traceback members of all Exceptions

{ez_a_sync-0.22.6 → ez_a_sync-0.22.8}/ez_a_sync.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ez-a-sync
-Version: 0.22.6
+Version: 0.22.8
 Summary: A library that makes it easy to define objects that can be used for both sync and async use cases.
 Home-page: https://github.com/BobTheBuidler/a-sync
 Author: BobTheBuidler