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

a_sync/a_sync/abstract.py

@@ -1,3 +1,14 @@
+"""
+This module provides an abstract base class for defining asynchronous and synchronous behavior.
+
+The ASyncABC class uses the ASyncMeta metaclass to automatically wrap its methods
+with asynchronous or synchronous behavior based on flags. Subclasses must
+implement the abstract methods to define the flag name, flag value, and
+default mode for asynchronous or synchronous execution.
+
+Note: It is recommended to use ASyncGenericBase for most use cases. This class
+is intended for more custom implementations if necessary.
+"""
 
 import abc
 import functools
@@ -11,70 +22,133 @@ from a_sync.exceptions import NoFlagsFound
 
 logger = logging.getLogger(__name__)
 
+
 class ASyncABC(metaclass=ASyncMeta):
+    """Abstract Base Class for defining asynchronous and synchronous behavior.
+
+    This class uses the ASyncMeta metaclass to automatically wrap its methods
+    with asynchronous or synchronous behavior based on flags. Subclasses must
+    implement the abstract methods to define the flag name, flag value, and
+    default mode for asynchronous or synchronous execution.
+    """
 
     ##################################
     # Concrete Methods (overridable) #
     ##################################
 
     def __a_sync_should_await__(self, kwargs: dict) -> bool:
-        """Returns a boolean that indicates whether methods of 'instance' should be called as sync or async methods."""
+        """Determines if methods should be called asynchronously.
+
+        This method first checks the provided keyword arguments for flags
+        indicating the desired execution mode. If no flags are found, it
+        defaults to the instance's asynchronous flag.
+
+        Args:
+            kwargs: A dictionary of keyword arguments to check for flags.
+        """
         try:
-            # Defer to kwargs always
             return self.__a_sync_should_await_from_kwargs__(kwargs)
         except exceptions.NoFlagsFound:
-            # No flag found in kwargs, check for a flag attribute.
             return self.__a_sync_instance_should_await__
 
     @functools.cached_property
     def __a_sync_instance_should_await__(self) -> bool:
+        """Indicates if the instance should default to asynchronous execution.
+
+        This property can be overridden if dynamic behavior is needed. For
+        instance, to allow hot-swapping of instance modes, redefine this as a
+        non-cached property.
         """
-        A flag indicating whether the instance should default to asynchronous execution.
-        
-        You can override this if you want. 
-        If you want to be able to hotswap instance modes, you can redefine this as a non-cached property.
-        """
-        return _flags.negate_if_necessary(self.__a_sync_flag_name__, self.__a_sync_flag_value__)
-    
+        return _flags.negate_if_necessary(
+            self.__a_sync_flag_name__, self.__a_sync_flag_value__
+        )
+
     def __a_sync_should_await_from_kwargs__(self, kwargs: dict) -> bool:
-        """You can override this if you want."""
+        """Determines execution mode from keyword arguments.
+
+        This method can be overridden to customize how flags are extracted
+        from keyword arguments.
+
+        Args:
+            kwargs: A dictionary of keyword arguments to check for flags.
+
+        Raises:
+            NoFlagsFound: If no valid flags are found in the keyword arguments.
+        """
         if flag := _kwargs.get_flag_name(kwargs):
             return _kwargs.is_sync(flag, kwargs, pop_flag=True)  # type: ignore [arg-type]
         raise NoFlagsFound("kwargs", kwargs.keys())
-    
+
     @classmethod
     def __a_sync_instance_will_be_sync__(cls, args: tuple, kwargs: dict) -> bool:
-        """You can override this if you want."""
-        logger.debug("checking `%s.%s.__init__` signature against provided kwargs to determine a_sync mode for the new instance", cls.__module__, cls.__name__)
+        """Determines if a new instance will be synchronous.
+
+        This method checks the constructor's signature against provided
+        keyword arguments to determine the execution mode for the new instance.
+
+        Args:
+            args: A tuple of positional arguments for the instance.
+            kwargs: A dictionary of keyword arguments for the instance.
+        """
+        logger.debug(
+            "checking `%s.%s.__init__` signature against provided kwargs to determine a_sync mode for the new instance",
+            cls.__module__,
+            cls.__name__,
+        )
         if flag := _kwargs.get_flag_name(kwargs):
             sync = _kwargs.is_sync(flag, kwargs)  # type: ignore [arg-type]
-            logger.debug("kwargs indicate the new instance created with args %s %s is %ssynchronous", args, kwargs, 'a' if sync is False else '')
+            logger.debug(
+                "kwargs indicate the new instance created with args %s %s is %ssynchronous",
+                args,
+                kwargs,
+                "a" if sync is False else "",
+            )
             return sync
-        logger.debug("No valid flags found in kwargs, checking class definition for defined default")
+        logger.debug(
+            "No valid flags found in kwargs, checking class definition for defined default"
+        )
         return cls.__a_sync_default_mode__()  # type: ignore [arg-type]
 
     ######################################
     # Concrete Methods (non-overridable) #
     ######################################
-    
+
     @property
     def __a_sync_modifiers__(self: "ASyncABC") -> ModifierKwargs:
-        """You should not override this."""
+        """Retrieves modifiers for the instance.
+
+        This method should not be overridden. It returns the modifiers
+        associated with the instance, which are used to customize behavior.
+        """
         return modifiers.get_modifiers_from(self)
 
     ####################
     # Abstract Methods #
     ####################
 
-    @abc.abstractproperty
+    @property
+    @abc.abstractmethod
     def __a_sync_flag_name__(self) -> str:
-        pass
-    
-    @abc.abstractproperty
+        """Abstract property for the flag name.
+
+        Subclasses must implement this property to return the name of the flag
+        used to determine execution mode.
+        """
+
+    @property
+    @abc.abstractmethod
     def __a_sync_flag_value__(self) -> bool:
-        pass
-    
-    @abc.abstractclassmethod  # type: ignore [arg-type, misc]
-    def __a_sync_default_mode__(cls) -> bool:  # type: ignore [empty-body] 
-                                                # mypy doesnt recognize this abc member
-        pass
+        """Abstract property for the flag value.
+
+        Subclasses must implement this property to return the value of the flag
+        indicating the default execution mode.
+        """
+
+    @classmethod
+    @abc.abstractmethod  # type: ignore [arg-type, misc]
+    def __a_sync_default_mode__(cls) -> bool:  # type: ignore [empty-body]
+        """Abstract class method for the default execution mode.
+
+        Subclasses must implement this method to return the default execution
+        mode (synchronous or asynchronous) for instances of the class.
+        """

a_sync/a_sync/base.py

@@ -11,6 +11,7 @@ from a_sync.a_sync.abstract import ASyncABC
 
 logger = logging.getLogger(__name__)
 
+
 class ASyncGenericBase(ASyncABC):
     """
     Base class for creating dual-function sync/async-capable classes without writing all your code twice.
@@ -35,7 +36,7 @@ class ASyncGenericBase(ASyncABC):
             @a_sync
             async def my_method(self):
                 return await another_async_operation()
-        
+
         # Synchronous usage
         obj = MyClass(sync=True)
         sync_result = obj.my_property
@@ -56,8 +57,10 @@ class ASyncGenericBase(ASyncABC):
     def __init__(self):
         if type(self) is ASyncGenericBase:
             cls_name = type(self).__name__
-            raise NotImplementedError(f"You should not create instances of `{cls_name}` directly, you should subclass `ASyncGenericBase` instead.")
-                                  
+            raise NotImplementedError(
+                f"You should not create instances of `{cls_name}` directly, you should subclass `ASyncGenericBase` instead."
+            )
+
     @functools.cached_property
     def __a_sync_flag_name__(self) -> str:
         logger.debug("checking a_sync flag for %s", self)
@@ -67,8 +70,14 @@ class ASyncGenericBase(ASyncABC):
             # We can't get the flag name from the __init__ signature,
             # but maybe the implementation sets the flag somewhere else.
             # Let's check the instance's atributes
-            logger.debug("unable to find flag name using `%s.__init__` signature, checking for flag attributes defined on %s", self.__class__.__name__, self)
-            present_flags = [flag for flag in _flags.VIABLE_FLAGS if hasattr(self, flag)]
+            logger.debug(
+                "unable to find flag name using `%s.__init__` signature, checking for flag attributes defined on %s",
+                self.__class__.__name__,
+                self,
+            )
+            present_flags = [
+                flag for flag in _flags.VIABLE_FLAGS if hasattr(self, flag)
+            ]
             if not present_flags:
                 raise exceptions.NoFlagsFound(self) from None
             if len(present_flags) > 1:
@@ -77,7 +86,7 @@ class ASyncGenericBase(ASyncABC):
         if not isinstance(flag, str):
             raise exceptions.InvalidFlag(flag)
         return flag
-        
+
     @functools.cached_property
     def __a_sync_flag_value__(self) -> bool:
         """If you wish to be able to hotswap default modes, just duplicate this def as a non-cached property."""
@@ -85,7 +94,7 @@ class ASyncGenericBase(ASyncABC):
         flag_value = getattr(self, flag)
         if not isinstance(flag_value, bool):
             raise exceptions.InvalidFlagValue(flag, flag_value)
-        logger.debug('`%s.%s` is currently %s', self, flag, flag_value)
+        logger.debug("`%s.%s` is currently %s", self, flag, flag_value)
         return flag_value
 
     @classmethod  # type: ignore [misc]
@@ -97,14 +106,21 @@ class ASyncGenericBase(ASyncABC):
             flag = cls.__get_a_sync_flag_name_from_class_def()
             flag_value = cls.__get_a_sync_flag_value_from_class_def(flag)
         sync = _flags.negate_if_necessary(flag, flag_value)  # type: ignore [arg-type]
-        logger.debug("`%s.%s` indicates default mode is %ssynchronous", cls, flag, 'a' if sync is False else '')
+        logger.debug(
+            "`%s.%s` indicates default mode is %ssynchronous",
+            cls,
+            flag,
+            "a" if sync is False else "",
+        )
         return sync
-    
+
     @classmethod
     def __get_a_sync_flag_name_from_signature(cls) -> Optional[str]:
         logger.debug("Searching for flags defined on %s.__init__", cls)
         if cls.__name__ == "ASyncGenericBase":
-            logger.debug("There are no flags defined on the base class, this is expected. Skipping.")
+            logger.debug(
+                "There are no flags defined on the base class, this is expected. Skipping."
+            )
             return None
         parameters = inspect.signature(cls.__init__).parameters
         logger.debug("parameters: %s", parameters)
@@ -115,17 +131,19 @@ class ASyncGenericBase(ASyncABC):
         logger.debug("Searching for flags defined on %s", cls)
         try:
             return cls.__parse_flag_name_from_list(cls.__dict__)  # type: ignore [arg-type]
-                                                                    # idk why __dict__ doesn't type check as a dict
+            # idk why __dict__ doesn't type check as a dict
         except exceptions.NoFlagsFound:
             for base in cls.__bases__:
                 with suppress(exceptions.NoFlagsFound):
-                    return cls.__parse_flag_name_from_list(base.__dict__)  # type: ignore [arg-type]  
-                                                                            # idk why __dict__ doesn't type check as a dict
+                    return cls.__parse_flag_name_from_list(base.__dict__)  # type: ignore [arg-type]
+                    # idk why __dict__ doesn't type check as a dict
         raise exceptions.NoFlagsFound(cls, list(cls.__dict__.keys()))
 
     @classmethod  # type: ignore [misc]
     def __a_sync_flag_default_value_from_signature(cls) -> bool:
-        logger.debug("checking `__init__` signature for default %s a_sync flag value", cls)
+        logger.debug(
+            "checking `__init__` signature for default %s a_sync flag value", cls
+        )
         signature = inspect.signature(cls.__init__)
         flag = cls.__get_a_sync_flag_name_from_signature()
         flag_value = signature.parameters[flag].default
@@ -133,7 +151,7 @@ class ASyncGenericBase(ASyncABC):
             raise NotImplementedError(
                 "The implementation for 'cls' uses an arg to specify sync mode, instead of a kwarg. We are unable to proceed. I suppose we can extend the code to accept positional arg flags if necessary"
             )
-        logger.debug('%s defines %s, default value %s', cls, flag, flag_value)
+        logger.debug("%s defines %s, default value %s", cls, flag, flag_value)
         return flag_value
 
     @classmethod
@@ -154,4 +172,4 @@ class ASyncGenericBase(ASyncABC):
             raise exceptions.TooManyFlags(cls, present_flags)
         flag = present_flags[0]
         logger.debug("found flag %s", flag)
-        return flag
+        return flag

a_sync/a_sync/config.py

@@ -1,9 +1,23 @@
 """
-Configuration module for a_sync library.
+Configuration module for the a_sync library.
 
 This module provides configuration options and default settings for the a_sync library.
 It includes functionality for setting up executors, defining default modifiers,
 and handling environment variable configurations.
+
+Environment Variables:
+    A_SYNC_EXECUTOR_TYPE: Specifies the type of executor to use. Valid values are
+        strings that start with 'p' for ProcessPoolExecutor (e.g., 'processes')
+        or 't' for ThreadPoolExecutor (e.g., 'threads'). Defaults to 'threads'.
+    A_SYNC_EXECUTOR_VALUE: Specifies the number of workers for the executor.
+        Defaults to 8.
+    A_SYNC_DEFAULT_MODE: Sets the default mode for a_sync functions if not specified.
+    A_SYNC_CACHE_TYPE: Sets the default cache type. If not specified, defaults to None.
+    A_SYNC_CACHE_TYPED: Boolean flag to determine if cache keys should consider types.
+    A_SYNC_RAM_CACHE_MAXSIZE: Sets the maximum size for the RAM cache. Defaults to -1.
+    A_SYNC_RAM_CACHE_TTL: Sets the time-to-live for cache entries. Defaults to None.
+    A_SYNC_RUNS_PER_MINUTE: Sets the rate limit for function execution.
+    A_SYNC_SEMAPHORE: Sets the semaphore limit for function execution.
 """
 
 import functools
@@ -16,22 +30,26 @@ from a_sync._typing import *
 EXECUTOR_TYPE = os.environ.get("A_SYNC_EXECUTOR_TYPE", "threads")
 EXECUTOR_VALUE = int(os.environ.get("A_SYNC_EXECUTOR_VALUE", 8))
 
+
 @functools.lru_cache(maxsize=1)
 def get_default_executor() -> Executor:
-    """
-    Get the default executor based on the :obj:`EXECUTOR_TYPE` environment variable.
+    """Get the default executor based on the EXECUTOR_TYPE environment variable.
 
     Returns:
-        Executor: An instance of either ProcessPoolExecutor or ThreadPoolExecutor.
+        An instance of either ProcessPoolExecutor or ThreadPoolExecutor.
 
     Raises:
-        :class:`ValueError`: If an invalid EXECUTOR_TYPE is specified.
+        ValueError: If an invalid EXECUTOR_TYPE is specified. Valid values are
+        strings that start with 'p' for ProcessPoolExecutor or 't' for ThreadPoolExecutor.
     """
-    if EXECUTOR_TYPE.lower().startswith('p'): # p, P, proc, Processes, etc
+    if EXECUTOR_TYPE.lower().startswith("p"):  # p, P, proc, Processes, etc
         return ProcessPoolExecutor(EXECUTOR_VALUE)
-    elif EXECUTOR_TYPE.lower().startswith('t'): # t, T, thread, THREADS, etc
+    elif EXECUTOR_TYPE.lower().startswith("t"):  # t, T, thread, THREADS, etc
         return ThreadPoolExecutor(EXECUTOR_VALUE)
-    raise ValueError("Invalid value for A_SYNC_EXECUTOR_TYPE. Please use 'threads' or 'processes'.")
+    raise ValueError(
+        "Invalid value for A_SYNC_EXECUTOR_TYPE. Please use 'threads' or 'processes'."
+    )
+
 
 default_sync_executor = get_default_executor()
 
@@ -53,13 +71,29 @@ null_modifiers = ModifierKwargs(
 # User configurable default modifiers to be applied to any a_sync decorated function if you do not specify kwarg values for each modifier.
 
 DEFAULT_MODE: DefaultMode = os.environ.get("A_SYNC_DEFAULT_MODE")  # type: ignore [assignment]
-CACHE_TYPE: CacheType = typ if (typ := os.environ.get("A_SYNC_CACHE_TYPE", "").lower()) else null_modifiers['cache_type']
+CACHE_TYPE: CacheType = (
+    typ
+    if (typ := os.environ.get("A_SYNC_CACHE_TYPE", "").lower())
+    else null_modifiers["cache_type"]
+)
 CACHE_TYPED = bool(os.environ.get("A_SYNC_CACHE_TYPED"))
-RAM_CACHE_MAXSIZE = int(os.environ.get("A_SYNC_RAM_CACHE_MAXSIZE", -1)) 
-RAM_CACHE_TTL = ttl if (ttl := float(os.environ.get("A_SYNC_RAM_CACHE_TTL", 0))) else null_modifiers['ram_cache_ttl']
+RAM_CACHE_MAXSIZE = int(os.environ.get("A_SYNC_RAM_CACHE_MAXSIZE", -1))
+RAM_CACHE_TTL = (
+    ttl
+    if (ttl := float(os.environ.get("A_SYNC_RAM_CACHE_TTL", 0)))
+    else null_modifiers["ram_cache_ttl"]
+)
 
-RUNS_PER_MINUTE = rpm if (rpm := int(os.environ.get("A_SYNC_RUNS_PER_MINUTE", 0))) else null_modifiers['runs_per_minute']
-SEMAPHORE = rpm if (rpm := int(os.environ.get("A_SYNC_SEMAPHORE", 0))) else null_modifiers['semaphore']
+RUNS_PER_MINUTE = (
+    rpm
+    if (rpm := int(os.environ.get("A_SYNC_RUNS_PER_MINUTE", 0)))
+    else null_modifiers["runs_per_minute"]
+)
+SEMAPHORE = (
+    rpm
+    if (rpm := int(os.environ.get("A_SYNC_SEMAPHORE", 0)))
+    else null_modifiers["semaphore"]
+)
 
 user_set_default_modifiers = ModifierKwargs(
     default=DEFAULT_MODE,