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

a_sync/a_sync/_descriptor.py

@@ -9,17 +9,20 @@ import functools
 
 from a_sync._typing import *
 from a_sync.a_sync import decorator
-from a_sync.a_sync.function import ASyncFunction, ModifiedMixin, ModifierManager
+from a_sync.a_sync.function import ASyncFunction, ModifierManager, _ModifiedMixin
 
 if TYPE_CHECKING:
     from a_sync import TaskMapping
 
-class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
+
+class ASyncDescriptor(_ModifiedMixin, Generic[I, P, T]):
     """
-    A descriptor base class for asynchronous methods and properties.
+    A descriptor base class for dual-function ASync methods and properties.
 
     This class provides functionality for mapping operations across multiple instances
-    and includes utility methods for common operations.
+    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.
     """
 
     __wrapped__: AnyFn[Concatenate[I, P], T]
@@ -28,9 +31,9 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
     __slots__ = "field_name", "_fget"
 
     def __init__(
-        self, 
-        _fget: AnyFn[Concatenate[I, P], T], 
-        field_name: Optional[str] = None, 
+        self,
+        _fget: AnyFn[Concatenate[I, P], T],
+        field_name: Optional[str] = None,
         **modifiers: ModifierKwargs,
     ) -> None:
         """
@@ -45,19 +48,21 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
             ValueError: If _fget is not callable.
         """
         if not callable(_fget):
-            raise ValueError(f'Unable to decorate {_fget}')
+            raise ValueError(f"Unable to decorate {_fget}")
         self.modifiers = ModifierManager(modifiers)
         if isinstance(_fget, ASyncFunction):
             self.modifiers.update(_fget.modifiers)
             self.__wrapped__ = _fget
         elif asyncio.iscoroutinefunction(_fget):
-            self.__wrapped__: AsyncUnboundMethod[I, P, T] = self.modifiers.apply_async_modifiers(_fget)
+            self.__wrapped__: AsyncUnboundMethod[I, P, T] = (
+                self.modifiers.apply_async_modifiers(_fget)
+            )
         else:
             self.__wrapped__ = _fget
 
         self.field_name = field_name or _fget.__name__
         """The name of the field the {cls} is bound to."""
-        
+
         functools.update_wrapper(self, self.__wrapped__)
 
     def __repr__(self) -> str:
@@ -73,7 +78,9 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         """
         self.field_name = name
 
-    def map(self, *instances: AnyIterable[I], **bound_method_kwargs: P.kwargs) -> "TaskMapping[I, T]":
+    def map(
+        self, *instances: AnyIterable[I], **bound_method_kwargs: P.kwargs
+    ) -> "TaskMapping[I, T]":
         """
         Create a TaskMapping for the given instances.
 
@@ -85,6 +92,7 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
             A TaskMapping object.
         """
         from a_sync.task import TaskMapping
+
         return TaskMapping(self, *instances, **bound_method_kwargs)
 
     @functools.cached_property
@@ -137,7 +145,13 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         """
         return decorator.a_sync(default=self.default)(self._sum)
 
-    async def _all(self, *instances: AnyIterable[I], concurrency: Optional[int] = None, name: str = "", **kwargs: P.kwargs) -> bool:
+    async def _all(
+        self,
+        *instances: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        name: str = "",
+        **kwargs: P.kwargs,
+    ) -> bool:
         """
         Check if all results are truthy.
 
@@ -150,9 +164,17 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         Returns:
             A boolean indicating if all results are truthy.
         """
-        return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).all(pop=True, sync=False)
-
-    async def _any(self, *instances: AnyIterable[I], concurrency: Optional[int] = None, name: str = "", **kwargs: P.kwargs) -> bool:
+        return await self.map(
+            *instances, concurrency=concurrency, name=name, **kwargs
+        ).all(pop=True, sync=False)
+
+    async def _any(
+        self,
+        *instances: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        name: str = "",
+        **kwargs: P.kwargs,
+    ) -> bool:
         """
         Check if any result is truthy.
 
@@ -165,9 +187,17 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         Returns:
             A boolean indicating if any result is truthy.
         """
-        return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).any(pop=True, sync=False)
-
-    async def _min(self, *instances: AnyIterable[I], concurrency: Optional[int] = None, name: str = "", **kwargs: P.kwargs) -> T:
+        return await self.map(
+            *instances, concurrency=concurrency, name=name, **kwargs
+        ).any(pop=True, sync=False)
+
+    async def _min(
+        self,
+        *instances: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        name: str = "",
+        **kwargs: P.kwargs,
+    ) -> T:
         """
         Find the minimum result.
 
@@ -180,9 +210,17 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         Returns:
             The minimum result.
         """
-        return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).min(pop=True, sync=False)
-
-    async def _max(self, *instances: AnyIterable[I], concurrency: Optional[int] = None, name: str = "", **kwargs: P.kwargs) -> T:
+        return await self.map(
+            *instances, concurrency=concurrency, name=name, **kwargs
+        ).min(pop=True, sync=False)
+
+    async def _max(
+        self,
+        *instances: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        name: str = "",
+        **kwargs: P.kwargs,
+    ) -> T:
         """
         Find the maximum result.
 
@@ -195,9 +233,17 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         Returns:
             The maximum result.
         """
-        return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).max(pop=True, sync=False)
-
-    async def _sum(self, *instances: AnyIterable[I], concurrency: Optional[int] = None, name: str = "", **kwargs: P.kwargs) -> T:
+        return await self.map(
+            *instances, concurrency=concurrency, name=name, **kwargs
+        ).max(pop=True, sync=False)
+
+    async def _sum(
+        self,
+        *instances: AnyIterable[I],
+        concurrency: Optional[int] = None,
+        name: str = "",
+        **kwargs: P.kwargs,
+    ) -> T:
         """
         Calculate the sum of results.
 
@@ -210,10 +256,12 @@ class ASyncDescriptor(ModifiedMixin, Generic[I, P, T]):
         Returns:
             The sum of the results.
         """
-        return await self.map(*instances, concurrency=concurrency, name=name, **kwargs).sum(pop=True, sync=False)
+        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__()
+        return super().__init_subclass__()

a_sync/a_sync/_flags.py

@@ -2,24 +2,31 @@
 This module provides functionality for handling synchronous and asynchronous flags
 in the ez-a-sync library.
 
-ez-a-sync uses 'flags' to indicate whether objects / function calls will be sync or async.
+ez-a-sync uses 'flags' to indicate whether objects or function calls will be synchronous or asynchronous.
 
-You can use any of the provided flags, whichever makes most sense for your use case.
+You can use any of the provided flags, whichever makes the most sense for your use case.
+
+AFFIRMATIVE_FLAGS: Set of flags indicating synchronous behavior. Currently includes "sync".
+
+NEGATIVE_FLAGS: Set of flags indicating asynchronous behavior. Currently includes "asynchronous".
+
+VIABLE_FLAGS: Set of all valid flags, combining both synchronous and asynchronous indicators.
 """
 
 from typing import Any
 
 from a_sync import exceptions
 
-AFFIRMATIVE_FLAGS = {'sync'}
+AFFIRMATIVE_FLAGS = {"sync"}
 """Set of flags indicating synchronous behavior."""
 
-NEGATIVE_FLAGS = {'asynchronous'}
+NEGATIVE_FLAGS = {"asynchronous"}
 """Set of flags indicating asynchronous behavior."""
 
 VIABLE_FLAGS = AFFIRMATIVE_FLAGS | NEGATIVE_FLAGS
 """Set of all valid flags."""
 
+
 def negate_if_necessary(flag: str, flag_value: bool) -> bool:
     """Negate the flag value if necessary based on the flag type.
 
@@ -31,7 +38,7 @@ def negate_if_necessary(flag: str, flag_value: bool) -> bool:
         The potentially negated flag value.
 
     Raises:
-        :class:`exceptions.InvalidFlag`: If the flag is not recognized.
+        exceptions.InvalidFlag: If the flag is not recognized.
     """
     validate_flag_value(flag, flag_value)
     if flag in AFFIRMATIVE_FLAGS:
@@ -40,6 +47,7 @@ def negate_if_necessary(flag: str, flag_value: bool) -> bool:
         return bool(not flag_value)
     raise exceptions.InvalidFlag(flag)
 
+
 def validate_flag_value(flag: str, flag_value: Any) -> bool:
     """
     Validate that the flag value is a boolean.
@@ -52,7 +60,7 @@ def validate_flag_value(flag: str, flag_value: Any) -> bool:
         The validated flag value.
 
     Raises:
-        :class:`exceptions.InvalidFlagValue`: If the flag value is not a boolean.
+        exceptions.InvalidFlagValue: If the flag value is not a boolean.
     """
     if not isinstance(flag_value, bool):
         raise exceptions.InvalidFlagValue(flag, flag_value)

a_sync/a_sync/_helpers.py

@@ -19,11 +19,8 @@ def _await(awaitable: Awaitable[T]) -> T:
     Args:
         awaitable: The awaitable object to be awaited.
 
-    Returns:
-        The result of the awaitable.
-
     Raises:
-        :class:`exceptions.SyncModeInAsyncContextError`: If the event loop is already running.
+        exceptions.SyncModeInAsyncContextError: If the event loop is already running.
     """
     try:
         return a_sync.asyncio.get_event_loop().run_until_complete(awaitable)
@@ -32,27 +29,31 @@ def _await(awaitable: Awaitable[T]) -> T:
             raise exceptions.SyncModeInAsyncContextError from None
         raise
 
+
 def _asyncify(func: SyncFn[P, T], executor: Executor) -> CoroFn[P, T]:  # type: ignore [misc]
     """
     Convert a synchronous function to a coroutine function.
 
     Args:
         func: The synchronous function to be converted.
-        executor: The executor to run the synchronous function.
+        executor: The executor used to run the synchronous function.
 
     Returns:
         A coroutine function wrapping the input function.
 
     Raises:
-        :class:`exceptions.FunctionNotSync`: If the input function is already asynchronous.
+        exceptions.FunctionNotSync: If the input function is a coroutine function or an instance of ASyncFunction.
     """
     from a_sync.a_sync.function import ASyncFunction
+
     if asyncio.iscoroutinefunction(func) or isinstance(func, ASyncFunction):
         raise exceptions.FunctionNotSync(func)
+
     @functools.wraps(func)
     async def _asyncify_wrap(*args: P.args, **kwargs: P.kwargs) -> T:
         return await asyncio.futures.wrap_future(
-            executor.submit(func, *args, **kwargs), 
+            executor.submit(func, *args, **kwargs),
             loop=a_sync.asyncio.get_event_loop(),
         )
+
     return _asyncify_wrap

a_sync/a_sync/_kwargs.py

@@ -25,9 +25,10 @@ def get_flag_name(kwargs: dict) -> Optional[str]:
     if len(present_flags) == 0:
         return None
     if len(present_flags) != 1:
-        raise exceptions.TooManyFlags('kwargs', present_flags)
+        raise exceptions.TooManyFlags("kwargs", present_flags)
     return present_flags[0]
 
+
 def is_sync(flag: str, kwargs: dict, pop_flag: bool = False) -> bool:
     """
     Determine if the operation should be synchronous based on the flag value.
@@ -41,4 +42,4 @@ def is_sync(flag: str, kwargs: dict, pop_flag: bool = False) -> bool:
         True if the operation should be synchronous, False otherwise.
     """
     flag_value = kwargs.pop(flag) if pop_flag else kwargs[flag]
-    return _flags.negate_if_necessary(flag, flag_value)
+    return _flags.negate_if_necessary(flag, flag_value)

a_sync/a_sync/_meta.py

@@ -1,4 +1,3 @@
-
 import inspect
 import logging
 import threading
@@ -7,56 +6,124 @@ from typing import Any, Dict, Tuple
 
 from a_sync import ENVIRONMENT_VARIABLES
 from a_sync.a_sync import modifiers
-from a_sync.a_sync.function import ASyncFunction, ModifiedMixin
+from a_sync.a_sync.function import ASyncFunction, _ModifiedMixin
 from a_sync.a_sync.method import ASyncMethodDescriptor
-from a_sync.a_sync.property import ASyncPropertyDescriptor, ASyncCachedPropertyDescriptor
+from a_sync.a_sync.property import (
+    ASyncCachedPropertyDescriptor,
+    ASyncPropertyDescriptor,
+)
 from a_sync.future import _ASyncFutureWrappedFn  # type: ignore [attr-defined]
 from a_sync.iter import ASyncGeneratorFunction
 from a_sync.primitives.locks.semaphore import Semaphore
 
 logger = logging.getLogger(__name__)
 
+
 class ASyncMeta(ABCMeta):
-    """Any class with metaclass ASyncMeta will have its functions wrapped with a_sync upon class instantiation."""
+    """Metaclass for wrapping class attributes with asynchronous capabilities.
+
+    Any class with `ASyncMeta` as its metaclass will have its functions and properties
+    wrapped with asynchronous capabilities upon class instantiation. This includes
+    wrapping functions with `ASyncMethodDescriptor` and properties with
+    `ASyncPropertyDescriptor` or `ASyncCachedPropertyDescriptor`. Additionally, it handles
+    `_ModifiedMixin` objects (# TODO replace this with the actual subclasses of _modifiedMixin, which is just an internal use mixin class that has no meaning ot the user),
+    which are used when functions are decorated with a_sync decorators
+    to apply specific modifiers to those functions.
+    """
+
     def __new__(cls, new_class_name, bases, attrs):
         _update_logger(new_class_name)
-        logger.debug("woah, you're defining a new ASync class `%s`! let's walk thru it together", new_class_name)
-        logger.debug("first, I check whether you've defined any modifiers on `%s`", new_class_name)
+        logger.debug(
+            "woah, you're defining a new ASync class `%s`! let's walk thru it together",
+            new_class_name,
+        )
+        logger.debug(
+            "first, I check whether you've defined any modifiers on `%s`",
+            new_class_name,
+        )
         # NOTE: Open quesion: what do we do when a parent class and subclass define the same modifier differently?
-        #       Currently the parent value is used for functions defined on the parent, 
+        #       Currently the parent value is used for functions defined on the parent,
         #       and the subclass value is used for functions defined on the subclass.
         class_defined_modifiers = modifiers.get_modifiers_from(attrs)
-        logger.debug('found modifiers: %s', class_defined_modifiers)
-        logger.debug("now I inspect the class definition to figure out which attributes need to be wrapped")
+
+        logger.debug("found modifiers: %s", class_defined_modifiers)
+        logger.debug(
+            "now I inspect the class definition to figure out which attributes need to be wrapped"
+        )
         for attr_name, attr_value in list(attrs.items()):
             if attr_name.startswith("_"):
-                logger.debug("`%s.%s` starts with an underscore, skipping", new_class_name, attr_name)
+                logger.debug(
+                    "`%s.%s` starts with an underscore, skipping",
+                    new_class_name,
+                    attr_name,
+                )
                 continue
             elif "__" in attr_name:
-                logger.debug("`%s.%s` incluldes a double-underscore, skipping", new_class_name, attr_name)
+                logger.debug(
+                    "`%s.%s` incluldes a double-underscore, skipping",
+                    new_class_name,
+                    attr_name,
+                )
                 continue
             elif isinstance(attr_value, (_ASyncFutureWrappedFn, Semaphore)):
-                logger.debug("`%s.%s` is a %s, skipping", new_class_name, attr_name, attr_value.__class__.__name__)
+                logger.debug(
+                    "`%s.%s` is a %s, skipping",
+                    new_class_name,
+                    attr_name,
+                    attr_value.__class__.__name__,
+                )
                 continue
-            logger.debug(f"inspecting `{new_class_name}.{attr_name}` of type {attr_value.__class__.__name__}")
+            logger.debug(
+                f"inspecting `{new_class_name}.{attr_name}` of type {attr_value.__class__.__name__}"
+            )
             fn_modifiers = dict(class_defined_modifiers)
             # Special handling for functions decorated with a_sync decorators
-            if isinstance(attr_value, ModifiedMixin):
-                logger.debug("`%s.%s` is a `ModifiedMixin` object, which means you decorated it with an a_sync decorator even though `%s` is an ASyncABC class", new_class_name, attr_name, new_class_name)
-                logger.debug("you probably did this so you could apply some modifiers to `%s` specifically", attr_name)
-                modified_modifiers = attr_value.modifiers._modifiers
-                if modified_modifiers:
-                    logger.debug("I found `%s.%s` is modified with %s", new_class_name, attr_name, modified_modifiers)
+            if isinstance(attr_value, _ModifiedMixin):
+                logger.debug(
+                    "`%s.%s` is a `%s` object, which means you decorated it with an a_sync decorator even though `%s` is an ASyncABC class",
+                    new_class_name,
+                    attr_name,
+                    type(attr_value).__name__,
+                    new_class_name,
+                )
+                logger.debug(
+                    "you probably did this so you could apply some modifiers to `%s` specifically",
+                    attr_name,
+                )
+                if modified_modifiers := attr_value.modifiers._modifiers:
+                    logger.debug(
+                        "I found `%s.%s` is modified with %s",
+                        new_class_name,
+                        attr_name,
+                        modified_modifiers,
+                    )
                     fn_modifiers.update(modified_modifiers)
                 else:
                     logger.debug("I did not find any modifiers")
-                logger.debug("full modifier set for `%s.%s`: %s", new_class_name, attr_name, fn_modifiers)
-                if isinstance(attr_value, (ASyncPropertyDescriptor, ASyncCachedPropertyDescriptor)):
+                logger.debug(
+                    "full modifier set for `%s.%s`: %s",
+                    new_class_name,
+                    attr_name,
+                    fn_modifiers,
+                )
+                if isinstance(
+                    attr_value, (ASyncPropertyDescriptor, ASyncCachedPropertyDescriptor)
+                ):
                     # Wrap property
                     logger.debug("`%s is a property, now let's wrap it", attr_name)
-                    logger.debug("since `%s` is a property, we will add a hidden dundermethod so you can still access it both sync and async", attr_name)
-                    attrs[attr_value.hidden_method_name] = attr_value.hidden_method_descriptor
-                    logger.debug("`%s.%s` is now %s", new_class_name, attr_value.hidden_method_name, attr_value.hidden_method_descriptor)
+                    logger.debug(
+                        "since `%s` is a property, we will add a hidden dundermethod so you can still access it both sync and async",
+                        attr_name,
+                    )
+                    attrs[attr_value.hidden_method_name] = (
+                        attr_value.hidden_method_descriptor
+                    )
+                    logger.debug(
+                        "`%s.%s` is now %s",
+                        new_class_name,
+                        attr_value.hidden_method_name,
+                        attr_value.hidden_method_descriptor,
+                    )
                 elif isinstance(attr_value, ASyncFunction):
                     attrs[attr_name] = ASyncMethodDescriptor(attr_value, **fn_modifiers)
                 else:
@@ -67,15 +134,30 @@ class ASyncMeta(ABCMeta):
                 # NOTE We will need to improve this logic if somebody needs to use it with classmethods or staticmethods.
                 attrs[attr_name] = ASyncMethodDescriptor(attr_value, **fn_modifiers)
             else:
-                logger.debug("`%s.%s` is not callable, we will take no action with it", new_class_name, attr_name)
-        return super(ASyncMeta, cls).__new__(cls, new_class_name, bases, attrs)    
+                logger.debug(
+                    "`%s.%s` is not callable, we will take no action with it",
+                    new_class_name,
+                    attr_name,
+                )
+        return super(ASyncMeta, cls).__new__(cls, new_class_name, bases, attrs)
 
 
 class ASyncSingletonMeta(ASyncMeta):
-    def __init__(cls, name: str, bases: Tuple[type, ...], namespace: Dict[str, Any]) -> None:
+    """Metaclass for creating singleton instances with asynchronous capabilities.
+
+    This metaclass extends `ASyncMeta` to ensure that only one instance of a class
+    is created for each synchronous or asynchronous context.
+    """
+
+    def __init__(
+        cls, name: str, bases: Tuple[type, ...], namespace: Dict[str, Any]
+    ) -> None:
         cls.__instances: Dict[bool, object] = {}
+        """Dictionary to store singleton instances."""
         cls.__lock = threading.Lock()
+        """Lock to ensure thread-safe instance creation."""
         super().__init__(name, bases, namespace)
+
     def __call__(cls, *args: Any, **kwargs: Any):
         is_sync = cls.__a_sync_instance_will_be_sync__(args, kwargs)  # type: ignore [attr-defined]
         if is_sync not in cls.__instances:
@@ -85,8 +167,17 @@ class ASyncSingletonMeta(ASyncMeta):
                     cls.__instances[is_sync] = super().__call__(*args, **kwargs)
         return cls.__instances[is_sync]
 
+
 def _update_logger(new_class_name: str) -> None:
-    if ENVIRONMENT_VARIABLES.DEBUG_MODE or ENVIRONMENT_VARIABLES.DEBUG_CLASS_NAME == new_class_name:
+    """Update the logger configuration based on environment variables.
+
+    Args:
+        new_class_name: The name of the new class being created.
+    """
+    if (
+        ENVIRONMENT_VARIABLES.DEBUG_MODE
+        or ENVIRONMENT_VARIABLES.DEBUG_CLASS_NAME == new_class_name
+    ):
         logger.addHandler(_debug_handler)
         logger.setLevel(logging.DEBUG)
         logger.info("debug mode activated")
@@ -94,6 +185,7 @@ def _update_logger(new_class_name: str) -> None:
         logger.removeHandler(_debug_handler)
         logger.setLevel(logging.INFO)
 
+
 _debug_handler = logging.StreamHandler()
 
 __all__ = ["ASyncMeta", "ASyncSingletonMeta"]