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

a_sync/exceptions.py

@@ -14,16 +14,14 @@ if TYPE_CHECKING:
 class ASyncFlagException(ValueError):
     """
     Base exception class for flag-related errors in the a_sync library.
-    """
-
-    viable_flags = VIABLE_FLAGS
-    """
-    The set of viable flags.
 
-    A-Sync uses 'flags' to indicate whether objects / fn calls will be sync or async.
+    A-Sync uses 'flags' to indicate whether objects or function calls will be sync or async.
     You can use any of the provided flags, whichever makes most sense for your use case.
     """
 
+    viable_flags = VIABLE_FLAGS
+    """The set of viable flags."""
+
     def desc(self, target) -> str:
         """
         Returns a description of the target for the flag error message.
@@ -31,8 +29,13 @@ class ASyncFlagException(ValueError):
         Args:
             target: The target object or string to describe.
 
-        Returns:
-            A string description of the target.
+        Examples:
+            >>> exception = ASyncFlagException()
+            >>> exception.desc("kwargs")
+            "flags present in 'kwargs'"
+
+            >>> exception.desc("some_target")
+            'flag attributes defined on some_target'
         """
         if target == "kwargs":
             return "flags present in 'kwargs'"
@@ -43,6 +46,15 @@ class ASyncFlagException(ValueError):
 class NoFlagsFound(ASyncFlagException):
     """
     Raised when no viable flags are found in the target.
+
+    Examples:
+        >>> try:
+        ...     raise NoFlagsFound("some_target")
+        ... except NoFlagsFound as e:
+        ...     print(e)
+        There are no viable a_sync flag attributes defined on some_target:
+        Viable flags: {'sync', 'asynchronous'}
+        This is likely an issue with a custom subclass definition.
     """
 
     def __init__(self, target, kwargs_keys=None):
@@ -64,6 +76,15 @@ class NoFlagsFound(ASyncFlagException):
 class TooManyFlags(ASyncFlagException):
     """
     Raised when multiple flags are found, but only one was expected.
+
+    Examples:
+        >>> try:
+        ...     raise TooManyFlags("some_target", ["flag1", "flag2"])
+        ... except TooManyFlags as e:
+        ...     print(e)
+        There are multiple a_sync flag attributes defined on some_target and there should only be one.
+        Present flags: ['flag1', 'flag2']
+        This is likely an issue with a custom subclass definition.
     """
 
     def __init__(self, target, present_flags):
@@ -73,8 +94,11 @@ class TooManyFlags(ASyncFlagException):
         Args:
             target: The target object where flags were found.
             present_flags: The flags that were found.
+
+        See Also:
+            - :class:`ASyncFlagException`
         """
-        err = f"There are multiple a_sync {self.__get_desc(target)} and there should only be one.\n"
+        err = f"There are multiple a_sync {self.desc(target)} and there should only be one.\n"
         err += f"Present flags: {present_flags}\n"
         err += "This is likely an issue with a custom subclass definition."
         super().__init__(err)
@@ -83,6 +107,14 @@ class TooManyFlags(ASyncFlagException):
 class InvalidFlag(ASyncFlagException):
     """
     Raised when an invalid flag is encountered.
+
+    Examples:
+        >>> try:
+        ...     raise InvalidFlag("invalid_flag")
+        ... except InvalidFlag as e:
+        ...     print(e)
+        'flag' must be one of: {'sync', 'asynchronous'}. You passed invalid_flag.
+        This code should not be reached and likely indicates an issue with a custom subclass definition.
     """
 
     def __init__(self, flag: Optional[str]):
@@ -91,6 +123,9 @@ class InvalidFlag(ASyncFlagException):
 
         Args:
             flag: The invalid flag.
+
+        See Also:
+            - :class:`ASyncFlagException`
         """
         err = f"'flag' must be one of: {self.viable_flags}. You passed {flag}."
         err += "\nThis code should not be reached and likely indicates an issue with a custom subclass definition."
@@ -100,6 +135,13 @@ class InvalidFlag(ASyncFlagException):
 class InvalidFlagValue(ASyncFlagException):
     """
     Raised when a flag has an invalid value.
+
+    Examples:
+        >>> try:
+        ...     raise InvalidFlagValue("some_flag", "not_a_boolean")
+        ... except InvalidFlagValue as e:
+        ...     print(e)
+        'some_flag' should be boolean. You passed not_a_boolean.
     """
 
     def __init__(self, flag: str, flag_value: Any):
@@ -109,6 +151,9 @@ class InvalidFlagValue(ASyncFlagException):
         Args:
             flag: The flag with an invalid value.
             flag_value: The invalid value of the flag.
+
+        See Also:
+            - :class:`ASyncFlagException`
         """
         super().__init__(f"'{flag}' should be boolean. You passed {flag_value}.")
 
@@ -116,6 +161,16 @@ class InvalidFlagValue(ASyncFlagException):
 class FlagNotDefined(ASyncFlagException):
     """
     Raised when a flag is not defined on an object.
+
+    Examples:
+        >>> class SomeClass:
+        ...     pass
+        ...
+        >>> try:
+        ...     raise FlagNotDefined(SomeClass, "some_flag")
+        ... except FlagNotDefined as e:
+        ...     print(e)
+        <class '__main__.SomeClass'> flag some_flag is not defined.
     """
 
     def __init__(self, obj: Type, flag: str):
@@ -125,6 +180,9 @@ class FlagNotDefined(ASyncFlagException):
         Args:
             obj: The object where the flag is not defined.
             flag: The undefined flag.
+
+        See Also:
+            - :class:`ASyncFlagException`
         """
         super().__init__(f"{obj} flag {flag} is not defined.")
 
@@ -132,12 +190,26 @@ class FlagNotDefined(ASyncFlagException):
 class ImproperFunctionType(ValueError):
     """
     Raised when a function that should be sync is async or vice-versa.
+
+    See Also:
+        - :class:`FunctionNotAsync`
+        - :class:`FunctionNotSync`
     """
 
 
 class FunctionNotAsync(ImproperFunctionType):
     """
     Raised when a function expected to be async is not.
+
+    Examples:
+        >>> def some_function():
+        ...     pass
+        ...
+        >>> try:
+        ...     raise FunctionNotAsync(some_function)
+        ... except FunctionNotAsync as e:
+        ...     print(e)
+        `coro_fn` must be a coroutine function defined with `async def`. You passed <function some_function at 0x...>.
     """
 
     def __init__(self, fn):
@@ -146,6 +218,9 @@ class FunctionNotAsync(ImproperFunctionType):
 
         Args:
             fn: The function that is not async.
+
+        See Also:
+            - :class:`ImproperFunctionType`
         """
         super().__init__(
             f"`coro_fn` must be a coroutine function defined with `async def`. You passed {fn}."
@@ -154,7 +229,17 @@ class FunctionNotAsync(ImproperFunctionType):
 
 class FunctionNotSync(ImproperFunctionType):
     """
-    Raised when a function expected to be sync is not.
+    Raised when a function expected to be sync is actually async.
+
+    Examples:
+        >>> async def some_async_function():
+        ...     pass
+        ...
+        >>> try:
+        ...     raise FunctionNotSync(some_async_function)
+        ... except FunctionNotSync as e:
+        ...     print(e)
+        `func` must be a coroutine function defined with `def`. You passed <function some_async_function at 0x...>.
     """
 
     def __init__(self, fn):
@@ -163,6 +248,9 @@ class FunctionNotSync(ImproperFunctionType):
 
         Args:
             fn: The function that is not sync.
+
+        See Also:
+            - :class:`ImproperFunctionType`
         """
         super().__init__(
             f"`func` must be a coroutine function defined with `def`. You passed {fn}."
@@ -172,6 +260,13 @@ class FunctionNotSync(ImproperFunctionType):
 class ASyncRuntimeError(RuntimeError):
     """
     Raised for runtime errors in asynchronous operations.
+
+    Examples:
+        >>> try:
+        ...     raise ASyncRuntimeError(RuntimeError("Some runtime error"))
+        ... except ASyncRuntimeError as e:
+        ...     print(e)
+        Some runtime error
     """
 
     def __init__(self, e: RuntimeError):
@@ -180,6 +275,9 @@ class ASyncRuntimeError(RuntimeError):
 
         Args:
             e: The original runtime error.
+
+        See Also:
+            - :class:`RuntimeError`
         """
         super().__init__(str(e))
 
@@ -187,11 +285,23 @@ class ASyncRuntimeError(RuntimeError):
 class SyncModeInAsyncContextError(ASyncRuntimeError):
     """
     Raised when synchronous code is used within an asynchronous context.
+
+    Examples:
+        >>> try:
+        ...     raise SyncModeInAsyncContextError()
+        ... except SyncModeInAsyncContextError as e:
+        ...     print(e)
+        The event loop is already running, which means you're trying to use an `ASyncFunction` synchronously from within an async context.
+        Check your traceback to determine which, then try calling asynchronously instead with one of the following kwargs:
+        {'sync', 'asynchronous'}
     """
 
     def __init__(self, err: str = ""):
         """
         Initializes the SyncModeInAsyncContextError exception.
+
+        See Also:
+            - :class:`ASyncRuntimeError`
         """
         if not err:
             err = "The event loop is already running, which means you're trying to use an `ASyncFunction` synchronously from within an async context.\n"
@@ -203,6 +313,16 @@ class SyncModeInAsyncContextError(ASyncRuntimeError):
 class MappingError(Exception):
     """
     Base class for errors related to :class:`~TaskMapping`.
+
+    Examples:
+        >>> from a_sync import TaskMapping
+        >>> try:
+        ...     raise MappingError(TaskMapping(), "Some mapping error")
+        ... except MappingError as e:
+        ...     print(e)
+        Some mapping error:
+        <TaskMapping object at 0x...>
+        {}
     """
 
     _msg: str
@@ -214,8 +334,11 @@ class MappingError(Exception):
         Args:
             mapping: The TaskMapping where the error occurred.
             msg: An optional message describing the error.
+
+        See Also:
+            - :class:`TaskMapping`
         """
-        msg = msg or self._msg + f":\n{mapping}"
+        msg = (msg or self._msg) + f":\n{mapping}"
         if mapping:
             msg += f"\n{dict(mapping)}"
         super().__init__(msg)
@@ -225,6 +348,16 @@ class MappingError(Exception):
 class MappingIsEmptyError(MappingError):
     """
     Raised when a TaskMapping is empty and an operation requires it to have items.
+
+    Examples:
+        >>> from a_sync import TaskMapping
+        >>> try:
+        ...     raise MappingIsEmptyError(TaskMapping())
+        ... except MappingIsEmptyError as e:
+        ...     print(e)
+        TaskMapping does not contain anything to yield:
+        <TaskMapping object at 0x...>
+        {}
     """
 
     _msg = "TaskMapping does not contain anything to yield"
@@ -233,6 +366,18 @@ class MappingIsEmptyError(MappingError):
 class MappingNotEmptyError(MappingError):
     """
     Raised when a TaskMapping is not empty and an operation requires it to be empty.
+
+    Examples:
+        >>> from a_sync import TaskMapping
+        >>> task_mapping = TaskMapping()
+        >>> task_mapping['key'] = 'value'
+        >>> try:
+        ...     raise MappingNotEmptyError(task_mapping)
+        ... except MappingNotEmptyError as e:
+        ...     print(e)
+        TaskMapping already contains some data. In order to use `map`, you need a fresh one:
+        <TaskMapping object at 0x...>
+        {'key': 'value'}
     """
 
     _msg = "TaskMapping already contains some data. In order to use `map`, you need a fresh one"
@@ -241,6 +386,18 @@ class MappingNotEmptyError(MappingError):
 class PersistedTaskException(Exception):
     """
     Raised when an exception persists in an asyncio Task.
+
+    Examples:
+        >>> import asyncio
+        >>> async def some_task():
+        ...     raise ValueError("Some error")
+        ...
+        >>> task = asyncio.create_task(some_task())
+        >>> try:
+        ...     raise PersistedTaskException(ValueError("Some error"), task)
+        ... except PersistedTaskException as e:
+        ...     print(e)
+        ValueError: Some error
     """
 
     def __init__(self, exc: E, task: asyncio.Task) -> None:
@@ -250,6 +407,9 @@ class PersistedTaskException(Exception):
         Args:
             exc: The exception that persisted.
             task: The asyncio Task where the exception occurred.
+
+        See Also:
+            - :class:`asyncio.Task`
         """
         super().__init__(f"{exc.__class__.__name__}: {exc}", task)
         self.exception = exc
@@ -259,4 +419,11 @@ class PersistedTaskException(Exception):
 class EmptySequenceError(ValueError):
     """
     Raised when an operation is attempted on an empty sequence but items are required.
+
+    Examples:
+        >>> try:
+        ...     raise EmptySequenceError("Sequence is empty")
+        ... except EmptySequenceError as e:
+        ...     print(e)
+        Sequence is empty
     """

a_sync/executor.py

@@ -1,7 +1,7 @@
 """
 With these executors, you can simply run sync functions in your executor with `await executor.run(fn, *args)`.
 
-`executor.submit(fn, *args)` will work the same as the concurrent.futures implementation, but will return an asyncio.Future instead of a concurrent.futures.Future.
+`executor.submit(fn, *args)` will work the same as the `concurrent.futures` implementation, but will return an `asyncio.Future` instead of a `concurrent.futures.Future`.
 
 This module provides several executor classes:
 - _AsyncExecutorMixin: A mixin providing asynchronous run and submit methods, with support for synchronous mode.
@@ -45,12 +45,21 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
         A shorthand way to call `await asyncio.get_event_loop().run_in_executor(this_executor, fn, *args)`.
         Doesn't `await this_executor.run(fn, *args)` look so much better?
 
-        Oh, and you can also use kwargs!
+        In synchronous mode, the function is executed directly in the current thread.
+        In asynchronous mode, the function is submitted to the executor and awaited.
 
         Args:
             fn: The function to run.
             *args: Positional arguments for the function.
             **kwargs: Keyword arguments for the function.
+
+        Examples:
+            >>> async def example():
+            >>>     result = await executor.run(some_function, arg1, arg2, kwarg1=value1)
+            >>>     print(result)
+
+        See Also:
+            - :meth:`submit` for submitting functions to the executor.
         """
         return (
             fn(*args, **kwargs)
@@ -60,12 +69,20 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
 
     def submit(self, fn: Callable[P, T], *args: P.args, **kwargs: P.kwargs) -> "asyncio.Future[T]":  # type: ignore [override]
         """
-        Submits a job to the executor and returns an asyncio.Future that can be awaited for the result without blocking.
+        Submits a job to the executor and returns an `asyncio.Future` that can be awaited for the result without blocking.
 
         Args:
             fn: The function to submit.
             *args: Positional arguments for the function.
             **kwargs: Keyword arguments for the function.
+
+        Examples:
+            >>> future = executor.submit(some_function, arg1, arg2, kwarg1=value1)
+            >>> result = await future
+            >>> print(result)
+
+        See Also:
+            - :meth:`run` for running functions with the executor.
         """
         if self.sync_mode:
             fut = asyncio.get_event_loop().create_future()
@@ -89,6 +106,10 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
     def sync_mode(self) -> bool:
         """
         Indicates if the executor is in synchronous mode (max_workers == 0).
+
+        Examples:
+            >>> if executor.sync_mode:
+            >>>     print("Executor is in synchronous mode.")
         """
         return self._max_workers == 0
 
@@ -96,6 +117,9 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
     def worker_count_current(self) -> int:
         """
         Returns the current number of workers.
+
+        Examples:
+            >>> print(f"Current worker count: {executor.worker_count_current}")
         """
         return len(getattr(self, f"_{self._workers}"))
 
@@ -108,6 +132,9 @@ class _AsyncExecutorMixin(cf.Executor, _DebugDaemonMixin):
             fn: The function being executed.
             *args: Positional arguments for the function.
             **kwargs: Keyword arguments for the function.
+
+        See Also:
+            - :meth:`_start_debug_daemon` to start the debug daemon.
         """
         # TODO: make prettier strings for other types
         if type(fn).__name__ == "function":
@@ -171,6 +198,11 @@ class AsyncProcessPoolExecutor(_AsyncExecutorMixin, cf.ProcessPoolExecutor):
             mp_context: The multiprocessing context. Defaults to None.
             initializer: An initializer callable. Defaults to None.
             initargs: Arguments for the initializer. Defaults to ().
+
+        Examples:
+            >>> executor = AsyncProcessPoolExecutor(max_workers=4)
+            >>> future = executor.submit(some_function, arg1, arg2)
+            >>> result = await future
         """
         if max_workers == 0:
             super().__init__(1, mp_context, initializer, initargs)
@@ -213,6 +245,11 @@ class AsyncThreadPoolExecutor(_AsyncExecutorMixin, cf.ThreadPoolExecutor):
             thread_name_prefix: Prefix for thread names. Defaults to ''.
             initializer: An initializer callable. Defaults to None.
             initargs: Arguments for the initializer. Defaults to ().
+
+        Examples:
+            >>> executor = AsyncThreadPoolExecutor(max_workers=10, thread_name_prefix="MyThread")
+            >>> future = executor.submit(some_function, arg1, arg2)
+            >>> result = await future
         """
         if max_workers == 0:
             super().__init__(1, thread_name_prefix, initializer, initargs)
@@ -240,6 +277,9 @@ def _worker(
         initializer: The initializer function.
         initargs: Arguments for the initializer.
         timeout: Timeout duration for pruning inactive threads.
+
+    See Also:
+        - :class:`PruningThreadPoolExecutor` for more details on thread pruning.
     """
     if initializer is not None:
         try:
@@ -326,6 +366,11 @@ class PruningThreadPoolExecutor(AsyncThreadPoolExecutor):
             initializer: An initializer callable. Defaults to None.
             initargs: Arguments for the initializer. Defaults to ().
             timeout: Timeout duration for pruning inactive threads. Defaults to TEN_MINUTES.
+
+        Examples:
+            >>> executor = PruningThreadPoolExecutor(max_workers=5, timeout=300)
+            >>> future = executor.submit(some_function, arg1, arg2)
+            >>> result = await future
         """
 
         self._timeout = timeout
@@ -342,6 +387,9 @@ class PruningThreadPoolExecutor(AsyncThreadPoolExecutor):
     def _adjust_thread_count(self):
         """
         Adjusts the number of threads based on workload and idle threads.
+
+        See Also:
+            - :func:`_worker` for the worker function that handles thread pruning.
         """
         with self._adjusting_lock:
             # if idle threads are available, don't spin new threads