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

a_sync/a_sync/_kwargs.py

@@ -19,26 +19,51 @@ def get_flag_name(kwargs: dict) -> Optional[str]:
         The name of the flag if present, None otherwise.
 
     Raises:
-        :class:`exceptions.TooManyFlags`: If more than one flag is present in the kwargs.
+        :class:`exceptions.TooManyFlags`: If more than one flag is present in the kwargs,
+        the exception includes the message "kwargs" and the list of present flags.
+
+    Examples:
+        >>> get_flag_name({'sync': True})
+        'sync'
+
+        >>> get_flag_name({'async': False})
+        'async'
+
+        >>> get_flag_name({})
+        None
+
+    See Also:
+        :func:`is_sync`: Determines if the operation should be synchronous based on the flag value.
     """
     present_flags = [flag for flag in _flags.VIABLE_FLAGS if flag in kwargs]
     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.
 
     Args:
-        flag: The name of the flag to check.
-        kwargs: A dictionary of keyword arguments.
-        pop_flag: Whether to remove the flag from kwargs. Defaults to False.
+        flag (str): The name of the flag to check.
+        kwargs (dict): A dictionary of keyword arguments.
+        pop_flag (bool, optional): Whether to remove the flag from kwargs. Defaults to False.
 
-    Returns:
-        True if the operation should be synchronous, False otherwise.
+    Examples:
+        >>> is_sync('sync', {'sync': True})
+        True
+
+        >>> is_sync('async', {'async': False})
+        False
+
+        >>> is_sync('sync', {'sync': True}, pop_flag=True)
+        True
+
+    See Also:
+        :func:`get_flag_name`: Retrieves the name of the flag present in the kwargs.
     """
     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,141 @@ 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 :class:`~a_sync.a_sync.method.ASyncMethodDescriptor` and properties with
+    :class:`~a_sync.a_sync.property.ASyncPropertyDescriptor` or :class:`~a_sync.a_sync.property.ASyncCachedPropertyDescriptor`.
+    It also handles attributes that are instances of :class:`~a_sync.a_sync.function.ASyncFunction`,
+    which are used when functions are decorated with a_sync decorators to apply specific modifiers to those functions.
+
+    Attributes that are instances of :class:`~a_sync.future._ASyncFutureWrappedFn` and :class:`~a_sync.primitives.locks.semaphore.Semaphore`
+    are explicitly skipped and not wrapped.
+
+    Example:
+        To create a class with asynchronous capabilities, define your class with `ASyncMeta` as its metaclass:
+
+        >>> class MyClass(metaclass=ASyncMeta):
+        ...     def my_method(self):
+        ...         return "Hello, World!"
+
+        The `my_method` function will be wrapped with :class:`~a_sync.a_sync.method.ASyncMethodDescriptor`, allowing it to be used asynchronously.
+
+    See Also:
+        - :class:`~a_sync.a_sync.function.ASyncFunction`
+        - :class:`~a_sync.a_sync.method.ASyncMethodDescriptor`
+        - :class:`~a_sync.a_sync.property.ASyncPropertyDescriptor`
+        - :class:`~a_sync.a_sync.property.ASyncCachedPropertyDescriptor`
+    """
+
     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 +151,42 @@ 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 :class:`~a_sync.a_sync._meta.ASyncMeta` to ensure that only one instance of a class
+    is created for each synchronous or asynchronous context.
+
+    Example:
+        To create a singleton class with asynchronous capabilities, define your class with `ASyncSingletonMeta` as its metaclass:
+
+        >>> class MySingleton(metaclass=ASyncSingletonMeta):
+        ...     def __init__(self):
+        ...         print("Instance created")
+
+        The `MySingleton` class will ensure that only one instance is created for each context.
+
+    See Also:
+        - :class:`~a_sync.a_sync._meta.ASyncMeta`
+    """
+
+    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 +196,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 +214,7 @@ def _update_logger(new_class_name: str) -> None:
         logger.removeHandler(_debug_handler)
         logger.setLevel(logging.INFO)
 
+
 _debug_handler = logging.StreamHandler()
 
 __all__ = ["ASyncMeta", "ASyncSingletonMeta"]

a_sync/a_sync/abstract.py

@@ -1,3 +1,13 @@
+"""
+This module provides an abstract base class for defining asynchronous and synchronous behavior.
+
+The :class:`ASyncABC` class uses the :class:`ASyncMeta` metaclass to facilitate the creation of classes
+that can operate in both asynchronous and synchronous contexts. It provides concrete methods to determine
+the execution mode based on flags and keyword arguments.
+
+Note: It is recommended to use :class:`ASyncGenericBase` for most use cases. This class
+is intended for more custom implementations if necessary.
+"""
 
 import abc
 import functools
@@ -11,70 +21,182 @@ 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 provides methods to determine the execution mode based on flags and keyword arguments.
+    It is designed to be subclassed, allowing developers to create classes that can be used in both
+    synchronous and asynchronous contexts.
+
+    See Also:
+        - :class:`ASyncGenericBase`: A more user-friendly base class for creating dual-mode classes.
+        - :class:`ASyncMeta`: Metaclass that facilitates asynchronous capabilities in class attributes.
+
+    Examples:
+        To create a class that inherits from `ASyncABC`, you need to implement the abstract methods
+        and can override the concrete methods if needed.
+
+        ```python
+        class MyASyncClass(ASyncABC):
+            @property
+            def __a_sync_flag_name__(self) -> str:
+                return "sync"
+
+            @property
+            def __a_sync_flag_value__(self) -> bool:
+                return True
+
+            @classmethod
+            def __a_sync_default_mode__(cls) -> bool:
+                return False
+        ```
+
+        In this example, `MyASyncClass` is a subclass of `ASyncABC` with custom implementations
+        for the required abstract methods.
+    """
 
     ##################################
     # 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.
+
+        Examples:
+            >>> instance = MyASyncClass()
+            >>> instance.__a_sync_should_await__({'sync': True})
+            False
+        """
         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.
+
+        Examples:
+            >>> instance = MyASyncClass()
+            >>> instance.__a_sync_instance_should_await__
+            True
         """
-        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.
+
+        Examples:
+            >>> instance = MyASyncClass()
+            >>> instance.__a_sync_should_await_from_kwargs__({'sync': False})
+            True
+        """
         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.
+
+        Examples:
+            >>> MyASyncClass.__a_sync_instance_will_be_sync__((), {'sync': True})
+            True
+        """
+        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.
+
+        Examples:
+            >>> instance = MyASyncClass()
+            >>> instance.__a_sync_modifiers__
+            {'cache_type': 'memory'}
+        """
         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