ez-a-sync 0.22.14__py3-none-any.whl → 0.22.16__py3-none-any.whl

tests/executor.py

@@ -1,11 +1,252 @@
-def work():
-    import time
-    time.sleep(5)
+import asyncio
+import time
 
-from a_sync import ProcessPoolExecutor
+import pytest
 
-@pytest.marks.asyncio
-async def test_executor():
-    executor = ProcessPoolExecutor(6)
-    await executor.run(work())
-    await executor.submit(work())
+from a_sync import ProcessPoolExecutor, ThreadPoolExecutor, PruningThreadPoolExecutor
+
+
+@pytest.mark.asyncio
+async def test_process_pool_executor_run():
+    """Tests the :class:`ProcessPoolExecutor` by running and submitting the work function asynchronously.
+
+    This test ensures that the `run` method of the `ProcessPoolExecutor` returns a coroutine
+    when executed with a synchronous function.
+
+    See Also:
+        - :meth:`ProcessPoolExecutor.run`
+        - :func:`asyncio.iscoroutine`
+
+    """
+    executor = ProcessPoolExecutor(1)
+    coro = executor.run(time.sleep, 0.1)
+    assert asyncio.iscoroutine(coro)
+    await coro
+
+
+@pytest.mark.asyncio
+async def test_thread_pool_executor_run():
+    """Tests the :class:`ThreadPoolExecutor` by running and submitting the work function asynchronously.
+
+    This test ensures that the `run` method of the `ThreadPoolExecutor` returns a coroutine
+    when executed with a synchronous function.
+
+    See Also:
+        - :meth:`ThreadPoolExecutor.run`
+        - :func:`asyncio.iscoroutine`
+
+    """
+    executor = ThreadPoolExecutor(1)
+    coro = executor.run(time.sleep, 0.1)
+    assert asyncio.iscoroutine(coro)
+    await coro
+
+
+@pytest.mark.asyncio
+async def test_pruning_thread_pool_executor_run():
+    """Tests the :class:`PruningThreadPoolExecutor` by running and submitting the work function asynchronously.
+
+    This test ensures that the `run` method of the `PruningThreadPoolExecutor` returns a coroutine
+    when executed with a synchronous function.
+
+    See Also:
+        - :meth:`PruningThreadPoolExecutor.run`
+        - :func:`asyncio.iscoroutine`
+
+    """
+    executor = PruningThreadPoolExecutor(1)
+    coro = executor.run(time.sleep, 0.1)
+    assert asyncio.iscoroutine(coro)
+    await coro
+
+
+@pytest.mark.asyncio
+async def test_process_pool_executor_submit():
+    """Tests the :class:`ProcessPoolExecutor` by submitting the work function.
+
+    This test ensures that the `submit` method of the `ProcessPoolExecutor` returns an
+    :class:`asyncio.Future` when executed with a synchronous function.
+
+    Note:
+        The `submit` method in this context returns an `asyncio.Future`, not a `concurrent.futures.Future`.
+        This is specific to the implementation of the executors in the `a_sync` library, which adapts the
+        behavior to integrate with the asyncio event loop.
+
+    See Also:
+        - :meth:`ProcessPoolExecutor.submit`
+        - :class:`asyncio.Future`
+
+    """
+    executor = ProcessPoolExecutor(1)
+    fut = executor.submit(time.sleep, 0.1)
+    assert isinstance(fut, asyncio.Future)
+    await fut
+
+
+@pytest.mark.asyncio
+async def test_thread_pool_executor_submit():
+    """Tests the :class:`ThreadPoolExecutor` by submitting the work function.
+
+    This test ensures that the `submit` method of the `ThreadPoolExecutor` returns an
+    :class:`asyncio.Future` when executed with a synchronous function.
+
+    Note:
+        The `submit` method in this context returns an `asyncio.Future`, not a `concurrent.futures.Future`.
+        This is specific to the implementation of the executors in the `a_sync` library, which adapts the
+        behavior to integrate with the asyncio event loop.
+
+    See Also:
+        - :meth:`ThreadPoolExecutor.submit`
+        - :class:`asyncio.Future`
+
+    """
+    executor = ThreadPoolExecutor(1)
+    fut = executor.submit(time.sleep, 0.1)
+    assert isinstance(fut, asyncio.Future)
+    await fut
+
+
+@pytest.mark.asyncio
+async def test_pruning_thread_pool_executor_submit():
+    """Tests the :class:`PruningThreadPoolExecutor` by submitting the work function.
+
+    This test ensures that the `submit` method of the `PruningThreadPoolExecutor` returns an
+    :class:`asyncio.Future` when executed with a synchronous function.
+
+    Note:
+        The `submit` method in this context returns an `asyncio.Future`, not a `concurrent.futures.Future`.
+        This is specific to the implementation of the executors in the `a_sync` library, which adapts the
+        behavior to integrate with the asyncio event loop.
+
+    See Also:
+        - :meth:`PruningThreadPoolExecutor.submit`
+        - :class:`asyncio.Future`
+
+    """
+    executor = PruningThreadPoolExecutor(1)
+    fut = executor.submit(time.sleep, 0.1)
+    assert isinstance(fut, asyncio.Future)
+    await fut
+
+
+@pytest.mark.asyncio
+async def test_process_pool_executor_sync_run():
+    """Tests the :class:`ProcessPoolExecutor` by running and submitting the work function synchronously.
+
+    This test ensures that the `run` method of the `ProcessPoolExecutor` returns a coroutine
+    when executed with a synchronous function.
+
+    See Also:
+        - :meth:`ProcessPoolExecutor.run`
+        - :func:`asyncio.iscoroutine`
+
+    """
+    executor = ProcessPoolExecutor(0)
+    coro = executor.run(time.sleep, 0.1)
+    assert asyncio.iscoroutine(coro)
+    await coro
+
+
+@pytest.mark.asyncio
+async def test_thread_pool_executor_sync_run():
+    """Tests the :class:`ThreadPoolExecutor` by running and submitting the work function synchronously.
+
+    This test ensures that the `run` method of the `ThreadPoolExecutor` returns a coroutine
+    when executed with a synchronous function.
+
+    See Also:
+        - :meth:`ThreadPoolExecutor.run`
+        - :func:`asyncio.iscoroutine`
+
+    """
+    executor = ThreadPoolExecutor(0)
+    coro = executor.run(time.sleep, 0.1)
+    assert asyncio.iscoroutine(coro)
+    await coro
+
+
+@pytest.mark.asyncio
+async def test_pruning_thread_pool_executor_sync_run():
+    """Tests the :class:`PruningThreadPoolExecutor` by running and submitting the work function synchronously.
+
+    This test ensures that the `run` method of the `PruningThreadPoolExecutor` returns a coroutine
+    when executed with a synchronous function.
+
+    See Also:
+        - :meth:`PruningThreadPoolExecutor.run`
+        - :func:`asyncio.iscoroutine`
+
+    """
+    executor = PruningThreadPoolExecutor(0)
+    coro = executor.run(time.sleep, 0.1)
+    assert asyncio.iscoroutine(coro)
+    await coro
+
+
+@pytest.mark.asyncio
+async def test_process_pool_executor_sync_submit():
+    """Tests the :class:`ProcessPoolExecutor` by submitting the work function synchronously.
+
+    This test ensures that the `submit` method of the `ProcessPoolExecutor` returns an
+    :class:`asyncio.Future` when executed with a synchronous function.
+
+    Note:
+        The `submit` method in this context returns an `asyncio.Future`, not a `concurrent.futures.Future`.
+        This is specific to the implementation of the executors in the `a_sync` library, which adapts the
+        behavior to integrate with the asyncio event loop.
+
+    See Also:
+        - :meth:`ProcessPoolExecutor.submit`
+        - :class:`asyncio.Future`
+
+    """
+    executor = ProcessPoolExecutor(0)
+    fut = executor.submit(time.sleep, 0.1)
+    assert isinstance(fut, asyncio.Future)
+    await fut
+
+
+@pytest.mark.asyncio
+async def test_thread_pool_executor_sync_submit():
+    """Tests the :class:`ThreadPoolExecutor` by submitting the work function synchronously.
+
+    This test ensures that the `submit` method of the `ThreadPoolExecutor` returns an
+    :class:`asyncio.Future` when executed with a synchronous function.
+
+    Note:
+        The `submit` method in this context returns an `asyncio.Future`, not a `concurrent.futures.Future`.
+        This is specific to the implementation of the executors in the `a_sync` library, which adapts the
+        behavior to integrate with the asyncio event loop.
+
+    See Also:
+        - :meth:`ThreadPoolExecutor.submit`
+        - :class:`asyncio.Future`
+
+    """
+    executor = ThreadPoolExecutor(0)
+    fut = executor.submit(time.sleep, 0.1)
+    assert isinstance(fut, asyncio.Future)
+    await fut
+
+
+@pytest.mark.asyncio
+async def test_pruning_thread_pool_executor_sync_submit():
+    """Tests the :class:`PruningThreadPoolExecutor` by submitting the work function synchronously.
+
+    This test ensures that the `submit` method of the `PruningThreadPoolExecutor` returns an
+    :class:`asyncio.Future` when executed with a synchronous function.
+
+    Note:
+        The `submit` method in this context returns an `asyncio.Future`, not a `concurrent.futures.Future`.
+        This is specific to the implementation of the executors in the `a_sync` library, which adapts the
+        behavior to integrate with the asyncio event loop.
+
+    See Also:
+        - :meth:`PruningThreadPoolExecutor.submit`
+        - :class:`asyncio.Future`
+
+    """
+    executor = PruningThreadPoolExecutor(0)
+    fut = executor.submit(time.sleep, 0.1)
+    assert isinstance(fut, asyncio.Future)
+    await fut

tests/fixtures.py

@@ -1,4 +1,3 @@
-
 import asyncio
 import time
 from threading import current_thread, main_thread
@@ -11,97 +10,124 @@ from a_sync import ASyncBase
 from a_sync.a_sync._meta import ASyncMeta, ASyncSingletonMeta
 from a_sync.a_sync.singleton import ASyncGenericSingleton
 
-increment = pytest.mark.parametrize('i', range(10))
+increment = pytest.mark.parametrize("i", range(10))
+
+
+class WrongThreadError(Exception): ...
 
-class WrongThreadError(Exception):
-    ...
 
 class TestClass(ASyncBase):
     def __init__(self, v: int, sync: bool = False):
         self.v = v
         self.sync = sync
-    
+
     async def test_fn(self) -> int:
         if self.sync == False and main_thread() != current_thread():
-            raise WrongThreadError('This should be running on an event loop in the main thread.')
+            raise WrongThreadError(
+                "This should be running on an event loop in the main thread."
+            )
         elif self.sync == True and main_thread() != current_thread():
-            raise WrongThreadError('This should be awaited in the main thread')
+            raise WrongThreadError("This should be awaited in the main thread")
         return self.v
-    
+
     @a_sync.aka.property
     async def test_property(self) -> int:
         if self.sync == False and main_thread() != current_thread():
-            raise WrongThreadError('This should be running on an event loop in the main thread.')
+            raise WrongThreadError(
+                "This should be running on an event loop in the main thread."
+            )
         elif self.sync == True and main_thread() != current_thread():
-            raise WrongThreadError('This should be awaited in the main thread')
+            raise WrongThreadError("This should be awaited in the main thread")
         return self.v * 2
-    
+
     @a_sync.alias.cached_property
     async def test_cached_property(self) -> int:
         if self.sync == False and main_thread() != current_thread():
-            raise WrongThreadError('This should be running on an event loop in the main thread.')
+            raise WrongThreadError(
+                "This should be running on an event loop in the main thread."
+            )
         elif self.sync == True and main_thread() != current_thread():
-            raise WrongThreadError('This should be awaited in the main thread')
+            raise WrongThreadError("This should be awaited in the main thread")
         await asyncio.sleep(2)
         return self.v * 3
 
+
 class TestSync(ASyncBase):
     main = main_thread()
+
     def __init__(self, v: int, sync: bool):
         self.v = v
         self.sync = sync
-    
+
     def test_fn(self) -> int:
         # Sync bound methods are actually async functions that are run in an executor and awaited
         if self.sync == False and main_thread() == current_thread():
-            raise WrongThreadError('This should be running in an executor, not the main thread.')
+            raise WrongThreadError(
+                "This should be running in an executor, not the main thread."
+            )
         elif self.sync == True and main_thread() != current_thread():
-            raise WrongThreadError('This should be running synchronously in the main thread')
+            raise WrongThreadError(
+                "This should be running synchronously in the main thread"
+            )
         return self.v
-    
+
     @a_sync.aka.property
     def test_property(self) -> int:
         if self.sync == False and main_thread() == current_thread():
-            raise WrongThreadError('This should be running in an executor, not the main thread.')
+            raise WrongThreadError(
+                "This should be running in an executor, not the main thread."
+            )
         if self.sync == True and main_thread() == current_thread():
             # Sync properties are actually async functions that are run in an executor and awaited
-            raise WrongThreadError('This should be running in an executor, not the main thread.')
+            raise WrongThreadError(
+                "This should be running in an executor, not the main thread."
+            )
         return self.v * 2
-    
+
     @a_sync.alias.cached_property
     def test_cached_property(self) -> int:
         if self.sync == False and main_thread() == current_thread():
-            raise WrongThreadError('This should be running in an executor, not the main thread.')
+            raise WrongThreadError(
+                "This should be running in an executor, not the main thread."
+            )
         if self.sync == True and main_thread() == current_thread():
             # Sync properties are actually async functions that are run in an executor and awaited
-            raise WrongThreadError('This should be running in an executor, not the main thread.')
+            raise WrongThreadError(
+                "This should be running in an executor, not the main thread."
+            )
         time.sleep(2)
         return self.v * 3
 
+
 class TestLimiter(TestClass):
     limiter = 1
-    
+
+
 class TestInheritor(TestClass):
     pass
 
+
 class TestMeta(TestClass, metaclass=ASyncMeta):
     pass
 
+
 class TestSingleton(ASyncGenericSingleton, TestClass):
     runs_per_minute = 100
     pass
 
+
 class TestSingletonMeta(TestClass, metaclass=ASyncSingletonMeta):
     semaphore = 1
     pass
 
+
 class TestSemaphore(ASyncBase):
-    #semaphore=1  # NOTE: this is detected propely by undecorated test_fn but not the properties
-    
+    # semaphore=1  # NOTE: this is detected propely by undecorated test_fn but not the properties
+
     def __init__(self, v: int, sync: bool):
         self.v = v
         self.sync = sync
-    
+
     # spec on class and function both working
     @a_sync.a_sync(semaphore=1)
     async def test_fn(self) -> int:
@@ -109,11 +135,11 @@ class TestSemaphore(ASyncBase):
         return self.v
 
     # spec on class, function, property all working
-    @a_sync.aka.property('async', semaphore=1)
+    @a_sync.aka.property("async", semaphore=1)
     async def test_property(self) -> int:
         await asyncio.sleep(1)
         return self.v * 2
-    
+
     # spec on class, function, property all working
     @a_sync.alias.cached_property(semaphore=50)
     async def test_cached_property(self) -> int:
@@ -121,7 +147,7 @@ class TestSemaphore(ASyncBase):
         return self.v * 3
 
 
-def _test_kwargs(fn, default: Literal['sync','async',None]):
+def _test_kwargs(fn, default: Literal["sync", "async", None]):
     # force async
     assert asyncio.get_event_loop().run_until_complete(fn(sync=False)) == 2
     assert asyncio.get_event_loop().run_until_complete(fn(asynchronous=True)) == 2
@@ -132,18 +158,21 @@ def _test_kwargs(fn, default: Literal['sync','async',None]):
         assert asyncio.get_event_loop().run_until_complete(fn(asynchronous=False)) == 2
     assert fn(sync=True) == 2
     assert fn(asynchronous=False) == 2
-    if default == 'sync':
+    if default == "sync":
         assert fn() == 2
-    elif default == 'async':
+    elif default == "async":
         assert asyncio.get_event_loop().run_until_complete(fn()) == 2
 
+
 async def sample_task(n):
     await asyncio.sleep(0.01)
     return n
 
+
 async def timeout_task(n):
     await asyncio.sleep(0.1)
     return n
 
+
 async def sample_exc(n):
-    raise ValueError("Sample error")
+    raise ValueError("Sample error")

tests/test_abstract.py

@@ -1,17 +1,35 @@
-
 import sys
 
 import pytest
 
 from a_sync.a_sync.abstract import ASyncABC
 
-_methods = '__a_sync_default_mode__', '__a_sync_flag_name__', '__a_sync_flag_value__'
+_methods = "__a_sync_default_mode__", "__a_sync_flag_name__", "__a_sync_flag_value__"
 if sys.version_info >= (3, 12):
     _MIDDLE = "without an implementation for abstract methods"
     _methods = (f"'{method}'" for method in _methods)
 else:
     _MIDDLE = "with abstract methods"
 
+
 def test_abc_direct_init():
-    with pytest.raises(TypeError, match=f"Can't instantiate abstract class ASyncABC {_MIDDLE} {', '.join(_methods)}"):
-        ASyncABC()
+    """Test that ASyncABC cannot be instantiated directly.
+
+    This test verifies that attempting to instantiate the abstract base class
+    `ASyncABC` raises a `TypeError`. This is expected behavior for abstract
+    base classes in Python, which require subclasses to implement all abstract
+    methods before instantiation.
+
+    Raises:
+        TypeError: If `ASyncABC` is instantiated without implementing abstract methods.
+
+    Example:
+        >>> from a_sync.a_sync.abstract import ASyncABC
+        >>> ASyncABC()
+        TypeError: Can't instantiate abstract class ASyncABC with abstract methods ...
+    """
+    with pytest.raises(
+        TypeError,
+        match=f"Can't instantiate abstract class ASyncABC {_MIDDLE} {', '.join(_methods)}",
+    ):
+        ASyncABC()

tests/test_as_completed.py

@@ -1,4 +1,3 @@
-
 import asyncio
 
 import a_sync
@@ -11,7 +10,10 @@ from tests.fixtures import sample_exc, sample_task, timeout_task
 async def test_as_completed_with_awaitables():
     tasks = [sample_task(i) for i in range(5)]
     results = [await result for result in a_sync.as_completed(tasks, aiter=False)]
-    assert sorted(results) == list(range(5)), "Results should be in ascending order from 0 to 4"
+    assert sorted(results) == list(
+        range(5)
+    ), "Results should be in ascending order from 0 to 4"
+
 
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_with_awaitables_aiter():
@@ -19,42 +21,61 @@ async def test_as_completed_with_awaitables_aiter():
     results = []
     async for result in a_sync.as_completed(tasks, aiter=True):
         results.append(result)
-    assert sorted(results) == list(range(5)), "Results should be in ascending order from 0 to 4"
+    assert sorted(results) == list(
+        range(5)
+    ), "Results should be in ascending order from 0 to 4"
+
 
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_with_mapping():
-    tasks = {'task1': sample_task(1), 'task2': sample_task(2)}
+    tasks = {"task1": sample_task(1), "task2": sample_task(2)}
     results = {}
     for result in a_sync.as_completed(tasks, aiter=False):
         key, value = await result
         results[key] = value
-    assert results == {'task1': 1, 'task2': 2}, "Results should match the input mapping"
+    assert results == {"task1": 1, "task2": 2}, "Results should match the input mapping"
+
 
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_with_mapping_aiter():
-    tasks = {'task1': sample_task(1), 'task2': sample_task(2)}
+    tasks = {"task1": sample_task(1), "task2": sample_task(2)}
     results = {}
     async for key, result in a_sync.as_completed(tasks, aiter=True):
         results[key] = result
-    assert results == {'task1': 1, 'task2': 2}, "Results should match the input mapping"
+    assert results == {"task1": 1, "task2": 2}, "Results should match the input mapping"
+
 
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_with_timeout():
     tasks = [timeout_task(i) for i in range(2)]
     with pytest.raises(asyncio.TimeoutError):
-        [await result for result in a_sync.as_completed(tasks, aiter=False, timeout=0.05)]
+        [
+            await result
+            for result in a_sync.as_completed(tasks, aiter=False, timeout=0.05)
+        ]
+
 
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_with_timeout_aiter():
     tasks = [timeout_task(i) for i in range(2)]
     with pytest.raises(asyncio.TimeoutError):
-        [result async for result in a_sync.as_completed(tasks, aiter=True, timeout=0.05)]
+        [
+            result
+            async for result in a_sync.as_completed(tasks, aiter=True, timeout=0.05)
+        ]
+
 
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_return_exceptions():
     tasks = [sample_exc(i) for i in range(1)]
-    results = [await result for result in a_sync.as_completed(tasks, aiter=False, return_exceptions=True)]
-    assert isinstance(results[0], ValueError), f"The result should be an exception {results}"
+    results = [
+        await result
+        for result in a_sync.as_completed(tasks, aiter=False, return_exceptions=True)
+    ]
+    assert isinstance(
+        results[0], ValueError
+    ), f"The result should be an exception {results}"
+
 
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_return_exceptions_aiter():
@@ -64,11 +85,17 @@ async def test_as_completed_return_exceptions_aiter():
         results.append(result)
     assert isinstance(results[0], ValueError), "The result should be an exception"
 
+
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_with_tqdm_disabled():
     tasks = [sample_task(i) for i in range(5)]
-    results = [await result for result in a_sync.as_completed(tasks, aiter=False, tqdm=False)]
-    assert sorted(results) == list(range(5)), "Results should be in ascending order from 0 to 4"
+    results = [
+        await result for result in a_sync.as_completed(tasks, aiter=False, tqdm=False)
+    ]
+    assert sorted(results) == list(
+        range(5)
+    ), "Results should be in ascending order from 0 to 4"
+
 
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_with_tqdm_disabled_aiter():
@@ -76,23 +103,29 @@ async def test_as_completed_with_tqdm_disabled_aiter():
     results = []
     async for result in a_sync.as_completed(tasks, aiter=True, tqdm=False):
         results.append(result)
-    assert sorted(results) == list(range(5)), "Results should be in ascending order from 0 to 4"
+    assert sorted(results) == list(
+        range(5)
+    ), "Results should be in ascending order from 0 to 4"
+
 
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_with_mapping_and_return_exceptions():
-    tasks = {'task1': sample_exc(1), 'task2': sample_task(2)}
+    tasks = {"task1": sample_exc(1), "task2": sample_task(2)}
     results = {}
     for result in a_sync.as_completed(tasks, return_exceptions=True, aiter=False):
         key, value = await result
         results[key] = value
-    assert isinstance(results['task1'], ValueError), "Result should be ValueError"
-    assert results['task2'] == 2, "Results should match the input mapping"
+    assert isinstance(results["task1"], ValueError), "Result should be ValueError"
+    assert results["task2"] == 2, "Results should match the input mapping"
+
 
 @pytest.mark.asyncio_cooperative
 async def test_as_completed_with_mapping_and_return_exceptions_aiter():
-    tasks = {'task1': sample_exc(1), 'task2': sample_task(2)}
+    tasks = {"task1": sample_exc(1), "task2": sample_task(2)}
     results = {}
-    async for key, result in a_sync.as_completed(tasks, return_exceptions=True, aiter=True):
+    async for key, result in a_sync.as_completed(
+        tasks, return_exceptions=True, aiter=True
+    ):
         results[key] = result
-    assert isinstance(results['task1'], ValueError), "Result should be ValueError"
-    assert results['task2'] == 2, "Results should match the input mapping"
+    assert isinstance(results["task1"], ValueError), "Result should be ValueError"
+    assert results["task2"] == 2, "Results should match the input mapping"