ez-a-sync 0.22.16__tar.gz → 0.23.0__tar.gz

{ez_a_sync-0.22.16 → ez_a_sync-0.23.0}/.github/workflows/pytest.yaml

@@ -38,10 +38,12 @@ jobs:
           python-version: ${{ matrix.pyversion }}
 
       - name: Install dependencies
+        run: pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Install ez-a-sync
         run: |
-          pip install pytest
-          pip install -r requirements.txt
-          pip install -r requirements-dev.txt
+          python setup.py build_ext --inplace
+          python setup.py install
       
       - name: Run test suite
         run: pytest

{ez_a_sync-0.22.16 → ez_a_sync-0.23.0}/.github/workflows/release.yaml

@@ -21,11 +21,11 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install setuptools wheel twine
+        pip install setuptools wheel twine cython
     - name: Build and publish
       env:
         TWINE_USERNAME: __token__
         TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
       run: |
-        python setup.py sdist bdist_wheel
+        python setup.py sdist
         twine upload dist/*

{ez_a_sync-0.22.16 → ez_a_sync-0.23.0}/.gitignore

@@ -8,4 +8,8 @@ dist/
 .eggs/
 *.egg-info
 cache/**/*.json
-cache/**/*.pkl
+cache/**/*.pkl
+mypy_plugin_tests/mypy
+mypy_plugin_tests/venv
+*.c
+*.so

{ez_a_sync-0.22.16 → ez_a_sync-0.23.0}/Makefile

@@ -6,3 +6,6 @@ docs:
 	rm -r ./docs/_templates -f
 	rm -r ./docs/_build -f
 	sphinx-apidoc --private -o ./docs/source ./a_sync
+
+cython:
+	python csetup.py build_ext --inplace

{ez_a_sync-0.22.16 → ez_a_sync-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ez-a-sync
-Version: 0.22.16
+Version: 0.23.0
 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
@@ -11,5 +11,6 @@ License-File: LICENSE.txt
 Requires-Dist: aiolimiter==1.0.0
 Requires-Dist: async_lru_threadsafe==2.0.4
 Requires-Dist: async_property==0.2.1
+Requires-Dist: Cython>=3.0.11
 Requires-Dist: typed_envs>=0.0.2
 Requires-Dist: typing_extensions>=4.1.0

{ez_a_sync-0.22.16 → ez_a_sync-0.23.0}/a_sync/ENVIRONMENT_VARIABLES.py

@@ -26,7 +26,7 @@ DEBUG_MODE = envs.create_env(
 """bool: Enables debug mode on all classes.
 
 Set this environment variable to `True` to enable debug mode on all classes. 
-If `DEBUG_CLASS_NAME` is set to a truthy value other than an empty string, 
+If `DEBUG_CLASS_NAME` is set to a non-empty string, 
 `DEBUG_MODE` will default to `True`.
 
 Examples:

{ez_a_sync-0.22.16 → ez_a_sync-0.23.0}/a_sync/__init__.py

@@ -8,14 +8,14 @@ that can operate in both synchronous and asynchronous contexts. Additionally, it
 such as queues and locks, with extra functionality.
 
 Modules and components included:
-- :mod:`~aliases`, :mod:`~exceptions`, :mod:`~iter`, :mod:`~task`: Core modules of the library.
-- :class:`~ASyncGenericBase`, :class:`~ASyncGenericSingleton`, :func:`~a_sync`: Base classes and decorators for dual-context execution.
-- :class:`~ASyncCachedPropertyDescriptor`, :class:`~ASyncPropertyDescriptor`, `cached_property`, `property`: Property descriptors for async properties.
-- :func:`~as_completed`, :func:`~create_task`, :func:`~gather`: Enhanced asyncio functions.
-- Executors: :class:`~AsyncThreadPoolExecutor`, :class:`~AsyncProcessPoolExecutor`, :class:`~PruningThreadPoolExecutor` for async execution.
-- Iterators: :class:`~ASyncFilter`, :class:`~ASyncSorter`, :class:`~ASyncIterable`, :class:`~ASyncIterator` for async iteration.
-- Utilities: :func:`~all`, :func:`~any`, :func:`~as_yielded`, :func:`~exhaust_iterator`, :func:`~exhaust_iterators` for async utilities.
-- :func:`~apply_semaphore`: Function to apply semaphores to coroutines.
+    - :mod:`~a_sync.aliases`, :mod:`~a_sync.exceptions`, :mod:`~a_sync.iter`, :mod:`~a_sync.task`: Core modules of the library.
+    - :class:`~ASyncGenericBase`, :class:`~ASyncGenericSingleton`, :func:`~a_sync`: Base classes and decorators for dual-context execution.
+    - :class:`~ASyncCachedPropertyDescriptor`, :class:`~ASyncPropertyDescriptor`, `cached_property`, `property`: Property descriptors for async properties.
+    - :func:`~as_completed`, :func:`~create_task`, :func:`~gather`: Enhanced asyncio functions.
+    - Executors: :class:`~AsyncThreadPoolExecutor`, :class:`~AsyncProcessPoolExecutor`, :class:`~PruningThreadPoolExecutor` for async execution.
+    - Iterators: :class:`~ASyncIterable`, :class:`~ASyncIterator`, :class:`~filter`, :class:`~sorted` for async iteration.
+    - Utilities: :func:`~all`, :func:`~any`, :func:`~as_yielded` for async utilities.
+    - :func:`~a_sync.a_sync.modifiers.semaphores.apply_semaphore`: Function to apply semaphores to coroutines.
 
 Alias for backward compatibility:
 - :class:`~ASyncBase` is an alias for :class:`~ASyncGenericBase`, which will be removed eventually, probably in version 0.1.0.
@@ -91,8 +91,6 @@ __all__ = [
     "all",
     "any",
     "as_yielded",
-    "exhaust_iterator",
-    "exhaust_iterators",
     "map",
     # classes
     "ASyncIterable",

{ez_a_sync-0.22.16 → ez_a_sync-0.23.0}/a_sync/_smart.py

@@ -29,6 +29,26 @@ class _SmartFutureMixin(Generic[T]):
     Mixin class that provides common functionality for smart futures and tasks.
 
     This mixin provides methods for managing waiters and integrating with a smart processing queue.
+    It uses weak references to manage resources efficiently.
+
+    Example:
+        Creating a SmartFuture and awaiting it:
+
+        ```python
+        future = SmartFuture()
+        result = await future
+        ```
+
+        Creating a SmartTask and awaiting it:
+
+        ```python
+        task = SmartTask(coro=my_coroutine())
+        result = await task
+        ```
+
+    See Also:
+        - :class:`SmartFuture`
+        - :class:`SmartTask`
     """
 
     _queue: Optional["SmartProcessingQueue[Any, Any, T]"] = None
@@ -73,18 +93,22 @@ class _SmartFutureMixin(Generic[T]):
 
     @property
     def num_waiters(self: Union["SmartFuture", "SmartTask"]) -> int:
-        # NOTE: we check .done() because the callback may not have ran yet and its very lightweight
         """
         Get the number of waiters currently awaiting the future or task.
 
+        This property checks if the future or task is done to ensure accurate counting
+        of waiters, as the callback may not have run yet.
+
         Example:
             ```python
             future = SmartFuture()
             print(future.num_waiters)
             ```
+
+        See Also:
+            - :meth:`_waiter_done_cleanup_callback`
         """
         if self.done():
-            # if there are any waiters left, there won't be once the event loop runs once
             return 0
         return sum(getattr(waiter, "num_waiters", 1) or 1 for waiter in self._waiters)
 
@@ -94,10 +118,13 @@ class _SmartFutureMixin(Generic[T]):
         """
         Callback to clean up waiters when a waiter task is done.
 
-        Removes the waiter from _waiters, and _queue._futs if applicable
+        Removes the waiter from _waiters, and _queue._futs if applicable.
 
         Args:
             waiter: The waiter task to clean up.
+
+        Example:
+            Automatically called when a waiter task completes.
         """
         if not self.done():
             self._waiters.remove(waiter)
@@ -105,6 +132,8 @@ class _SmartFutureMixin(Generic[T]):
     def _self_done_cleanup_callback(self: Union["SmartFuture", "SmartTask"]) -> None:
         """
         Callback to clean up waiters and remove the future from the queue when done.
+
+        This method clears all waiters and removes the future from the associated queue.
         """
         self._waiters.clear()
         if queue := self._queue:
@@ -125,6 +154,10 @@ class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
         future = SmartFuture()
         await future
         ```
+
+    See Also:
+        - :class:`_SmartFutureMixin`
+        - :class:`asyncio.Future`
     """
 
     _queue = None
@@ -149,6 +182,9 @@ class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
             ```python
             future = SmartFuture(queue=my_queue, key=my_key)
             ```
+
+        See Also:
+            - :class:`SmartProcessingQueue`
         """
         super().__init__(loop=loop)
         if queue:
@@ -175,6 +211,9 @@ class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
             future2 = SmartFuture()
             print(future1 < future2)
             ```
+
+        See Also:
+            - :meth:`num_waiters`
         """
         return self.num_waiters > other.num_waiters
 
@@ -202,6 +241,9 @@ def create_future(
         ```python
         future = create_future(queue=my_queue, key=my_key)
         ```
+
+    See Also:
+        - :class:`SmartFuture`
     """
     return SmartFuture(queue=queue, key=key, loop=loop or asyncio.get_event_loop())
 
@@ -220,6 +262,10 @@ class SmartTask(_SmartFutureMixin[T], asyncio.Task):
         task = SmartTask(coro=my_coroutine())
         await task
         ```
+
+    See Also:
+        - :class:`_SmartFutureMixin`
+        - :class:`asyncio.Task`
     """
 
     def __init__(
@@ -241,6 +287,9 @@ class SmartTask(_SmartFutureMixin[T], asyncio.Task):
             ```python
             task = SmartTask(coro=my_coroutine(), name="my_task")
             ```
+
+        See Also:
+            - :func:`asyncio.create_task`
         """
         super().__init__(coro, loop=loop, name=name)
         self._waiters: Set["asyncio.Task[T]"] = set()
@@ -272,6 +321,7 @@ def smart_task_factory(
 
     See Also:
         - :func:`set_smart_task_factory`
+        - :class:`SmartTask`
     """
     return SmartTask(coro, loop=loop)
 
@@ -300,7 +350,7 @@ def set_smart_task_factory(loop: asyncio.AbstractEventLoop = None) -> None:
 
 def shield(
     arg: Awaitable[T], *, loop: Optional[asyncio.AbstractEventLoop] = None
-) -> SmartFuture[T]:
+) -> Union[SmartFuture[T], asyncio.Future]:
     """
     Wait for a future, shielding it from cancellation.
 
@@ -331,6 +381,9 @@ def shield(
         arg: The awaitable to shield from cancellation.
         loop: Optional; the event loop. Deprecated since Python 3.8.
 
+    Returns:
+        A :class:`SmartFuture` or :class:`asyncio.Future` instance.
+
     Example:
         Using shield to protect a coroutine from cancellation:
 

{ez_a_sync-0.22.16 → ez_a_sync-0.23.0}/a_sync/_typing.py

@@ -30,10 +30,14 @@ Examples:
     asyncio.run(main())
     ```
 
-    Example of defining a coroutine function type:
+    Example of defining a coroutine function type using `CoroFn` with `ParamSpec`:
 
     ```python
     from a_sync._typing import CoroFn
+    from typing_extensions import ParamSpec
+    from typing import Awaitable
+
+    P = ParamSpec("P")
 
     async def async_function(x: int) -> str:
         return str(x)
@@ -41,10 +45,13 @@ Examples:
     coro_fn: CoroFn[[int], str] = async_function
     ```
 
-    Example of defining a synchronous function type:
+    Example of defining a synchronous function type using `SyncFn` with `ParamSpec`:
 
     ```python
     from a_sync._typing import SyncFn
+    from typing_extensions import ParamSpec
+
+    P = ParamSpec("P")
 
     def sync_function(x: int) -> str:
         return str(x)

{ez_a_sync-0.22.16 → ez_a_sync-0.23.0}/a_sync/a_sync/_descriptor.py

@@ -2,13 +2,15 @@
 This module contains the :class:`ASyncDescriptor` class, which is used to create dual-function sync/async methods
 and properties.
 
-The :class:`ASyncDescriptor` class provides functionality for mapping operations across multiple instances
-and includes utility methods for common operations such as checking if all or any results are truthy, 
-and finding the minimum, maximum, or sum of results of the method or property mapped across multiple instances.
+The :class:`ASyncDescriptor` class provides a base for creating descriptors that can handle both synchronous and asynchronous
+operations. It includes utility methods for mapping operations across multiple instances and provides access to common
+operations such as checking if all or any results are truthy, and finding the minimum, maximum, or sum of results of the
+method or property mapped across multiple instances through the use of :class:`~a_sync.a_sync.function.ASyncFunction`.
 
 See Also:
     - :class:`~a_sync.a_sync.function.ASyncFunction`
     - :class:`~a_sync.a_sync.method.ASyncMethodDescriptor`
+    - :class:`~a_sync.a_sync.property.ASyncPropertyDescriptor`
 """
 
 import functools
@@ -28,7 +30,7 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
     This class provides functionality for mapping operations across multiple instances
     and includes utility methods for common operations such as checking if all or any
     results are truthy, and finding the minimum, maximum, or sum of results of the method
-    or property mapped across multiple instances.
+    or property mapped across multiple instances through the use of :class:`~a_sync.a_sync.function.ASyncFunction`.
 
     Examples:
         To create a dual-function method or property, subclass :class:`ASyncDescriptor` and implement
@@ -36,12 +38,10 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
         across multiple instances.
 
         ```python
-        class MyDescriptor(ASyncDescriptor):
-            def __init__(self, func):
-                super().__init__(func)
-
         class MyClass:
-            my_method = MyDescriptor(lambda x: x * 2)
+            @ASyncDescriptor
+            def my_method(self, x):
+                return x * 2
 
         instance = MyClass()
         result = instance.my_method.map([1, 2, 3])
@@ -119,12 +119,10 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
             A :class:`TaskMapping` object.
 
         Examples:
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x * 2)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x * 2
 
             instance = MyClass()
             result = instance.my_method.map([1, 2, 3])
@@ -142,12 +140,10 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
             An :class:`ASyncFunction` object.
 
         Examples:
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x > 0)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x > 0
 
             instance = MyClass()
             result = await instance.my_method.all([1, 2, 3])
@@ -163,12 +159,10 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
             An :class:`ASyncFunction` object.
 
         Examples:
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x > 0)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x > 0
 
             instance = MyClass()
             result = await instance.my_method.any([-1, 0, 1])
@@ -185,12 +179,10 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
 
         Examples:
             ```python
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x
 
             instance = MyClass()
             result = await instance.my_method.min([3, 1, 2])
@@ -207,12 +199,10 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
             An :class:`ASyncFunction` object.
 
         Examples:
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x
 
             instance = MyClass()
             result = await instance.my_method.max([3, 1, 2])
@@ -229,12 +219,10 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
 
         Examples:
             ```python
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x
 
             instance = MyClass()
             result = await instance.my_method.sum([1, 2, 3])
@@ -258,17 +246,12 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
             name: Optional name for the task.
             **kwargs: Additional keyword arguments.
 
-        Returns:
-            A boolean indicating if all results are truthy.
-
         Examples:
             ```python
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x > 0)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x > 0
 
             instance = MyClass()
             result = await instance.my_method._all([1, 2, 3])
@@ -294,17 +277,12 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
             name: Optional name for the task.
             **kwargs: Additional keyword arguments.
 
-        Returns:
-            A boolean indicating if any result is truthy.
-
         Examples:
             ```python
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x > 0)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x > 0
 
             instance = MyClass()
             result = await instance.my_method._any([-1, 0, 1])
@@ -330,17 +308,12 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
             name: Optional name for the task.
             **kwargs: Additional keyword arguments.
 
-        Returns:
-            The minimum result.
-
         Examples:
             ```python
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x
 
             instance = MyClass()
             result = await instance.my_method._min([3, 1, 2])
@@ -366,17 +339,12 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
             name: Optional name for the task.
             **kwargs: Additional keyword arguments.
 
-        Returns:
-            The maximum result.
-
         Examples:
             ```python
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x
 
             instance = MyClass()
             result = await instance.my_method._max([3, 1, 2])
@@ -402,17 +370,12 @@ class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
             name: Optional name for the task.
             **kwargs: Additional keyword arguments.
 
-        Returns:
-            The sum of the results.
-
         Examples:
             ```python
-            class MyDescriptor(ASyncDescriptor):
-                def __init__(self, func):
-                    super().__init__(func)
-
             class MyClass:
-                my_method = MyDescriptor(lambda x: x)
+                @ASyncDescriptor
+                def my_method(self, x):
+                    return x
 
             instance = MyClass()
             result = await instance.my_method._sum([1, 2, 3])