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

a_sync/a_sync/_flags.py

@@ -11,6 +11,10 @@ AFFIRMATIVE_FLAGS: Set of flags indicating synchronous behavior. Currently inclu
 NEGATIVE_FLAGS: Set of flags indicating asynchronous behavior. Currently includes "asynchronous".
 
 VIABLE_FLAGS: Set of all valid flags, combining both synchronous and asynchronous indicators.
+
+Functions:
+    - negate_if_necessary: Negates the flag value if necessary based on the flag type.
+    - validate_flag_value: Validates that the flag value is a boolean.
 """
 
 from typing import Any
@@ -18,18 +22,51 @@ from typing import Any
 from a_sync import exceptions
 
 AFFIRMATIVE_FLAGS = {"sync"}
-"""Set of flags indicating synchronous behavior."""
+"""Set of flags indicating synchronous behavior.
+
+Examples:
+    >>> 'sync' in AFFIRMATIVE_FLAGS
+    True
+
+    >>> 'async' in AFFIRMATIVE_FLAGS
+    False
+"""
 
 NEGATIVE_FLAGS = {"asynchronous"}
-"""Set of flags indicating asynchronous behavior."""
+"""Set of flags indicating asynchronous behavior.
+
+Examples:
+    >>> 'asynchronous' in NEGATIVE_FLAGS
+    True
+
+    >>> 'sync' in NEGATIVE_FLAGS
+    False
+"""
 
 VIABLE_FLAGS = AFFIRMATIVE_FLAGS | NEGATIVE_FLAGS
-"""Set of all valid flags."""
+"""Set of all valid flags, combining both synchronous and asynchronous indicators.
+
+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.
+
+Examples:
+    >>> 'sync' in VIABLE_FLAGS
+    True
+
+    >>> 'asynchronous' in VIABLE_FLAGS
+    True
+
+    >>> 'invalid' in VIABLE_FLAGS
+    False
+"""
 
 
 def negate_if_necessary(flag: str, flag_value: bool) -> bool:
     """Negate the flag value if necessary based on the flag type.
 
+    This function checks if the provided flag is in the set of affirmative or negative flags
+    and negates the flag value accordingly. If the flag is not recognized, it raises an exception.
+
     Args:
         flag: The flag to check.
         flag_value: The value of the flag.
@@ -39,6 +76,16 @@ def negate_if_necessary(flag: str, flag_value: bool) -> bool:
 
     Raises:
         exceptions.InvalidFlag: If the flag is not recognized.
+
+    Examples:
+        >>> negate_if_necessary('sync', True)
+        True
+
+        >>> negate_if_necessary('asynchronous', True)
+        False
+
+    See Also:
+        - :func:`validate_flag_value`: Validates that the flag value is a boolean.
     """
     validate_flag_value(flag, flag_value)
     if flag in AFFIRMATIVE_FLAGS:
@@ -52,6 +99,8 @@ def validate_flag_value(flag: str, flag_value: Any) -> bool:
     """
     Validate that the flag value is a boolean.
 
+    This function ensures that the provided flag value is of type boolean. If not, it raises an exception.
+
     Args:
         flag: The flag being validated.
         flag_value: The value to validate.
@@ -61,6 +110,18 @@ def validate_flag_value(flag: str, flag_value: Any) -> bool:
 
     Raises:
         exceptions.InvalidFlagValue: If the flag value is not a boolean.
+
+    Examples:
+        >>> validate_flag_value('sync', True)
+        True
+
+        >>> validate_flag_value('asynchronous', 'yes')
+        Traceback (most recent call last):
+        ...
+        exceptions.InvalidFlagValue: Invalid flag value for 'asynchronous': 'yes'
+
+    See Also:
+        - :func:`negate_if_necessary`: Negates the flag value if necessary based on the flag type.
     """
     if not isinstance(flag_value, bool):
         raise exceptions.InvalidFlagValue(flag, flag_value)

a_sync/a_sync/_helpers.py

@@ -17,10 +17,21 @@ def _await(awaitable: Awaitable[T]) -> T:
     Await an awaitable object in a synchronous context.
 
     Args:
-        awaitable: The awaitable object to be awaited.
+        awaitable (Awaitable[T]): The awaitable object to be awaited.
 
     Raises:
         exceptions.SyncModeInAsyncContextError: If the event loop is already running.
+
+    Examples:
+        >>> async def example_coroutine():
+        ...     return 42
+        ...
+        >>> result = _await(example_coroutine())
+        >>> print(result)
+        42
+
+    See Also:
+        - :func:`asyncio.run`: For running the main entry point of an asyncio program.
     """
     try:
         return a_sync.asyncio.get_event_loop().run_until_complete(awaitable)
@@ -32,17 +43,38 @@ def _await(awaitable: Awaitable[T]) -> T:
 
 def _asyncify(func: SyncFn[P, T], executor: Executor) -> CoroFn[P, T]:  # type: ignore [misc]
     """
-    Convert a synchronous function to a coroutine function.
+    Convert a synchronous function to a coroutine function using an executor.
 
-    Args:
-        func: The synchronous function to be converted.
-        executor: The executor used to run the synchronous function.
+    This function submits the synchronous function to the provided executor and wraps
+    the resulting future in a coroutine function. This allows the synchronous function
+    to be executed asynchronously.
 
-    Returns:
-        A coroutine function wrapping the input function.
+    Note:
+        The function `_asyncify` uses `asyncio.futures.wrap_future` to wrap the future
+        returned by the executor, specifying the event loop with `a_sync.asyncio.get_event_loop()`.
+        Ensure that your environment supports this usage or adjust the import if necessary.
+
+    Args:
+        func (SyncFn[P, T]): The synchronous function to be converted.
+        executor (Executor): The executor used to run the synchronous function.
 
     Raises:
-        exceptions.FunctionNotSync: If the input function is a coroutine function or an instance of ASyncFunction.
+        exceptions.FunctionNotSync: If the input function is a coroutine function or an instance of :class:`~a_sync.a_sync.function.ASyncFunction`.
+
+    Examples:
+        >>> from concurrent.futures import ThreadPoolExecutor
+        >>> def sync_function(x):
+        ...     return x * 2
+        ...
+        >>> executor = ThreadPoolExecutor()
+        >>> async_function = _asyncify(sync_function, executor)
+        >>> result = await async_function(3)
+        >>> print(result)
+        6
+
+    See Also:
+        - :class:`concurrent.futures.Executor`: For managing pools of threads or processes.
+        - :func:`asyncio.to_thread`: For running blocking code in a separate thread.
     """
     from a_sync.a_sync.function import ASyncFunction
 

a_sync/a_sync/_kwargs.py

@@ -19,7 +19,21 @@ 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:
@@ -34,12 +48,22 @@ 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)

a_sync/a_sync/_meta.py

@@ -24,11 +24,28 @@ class ASyncMeta(ABCMeta):
 
     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.
+    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):
@@ -145,8 +162,20 @@ class ASyncMeta(ABCMeta):
 class ASyncSingletonMeta(ASyncMeta):
     """Metaclass for creating singleton instances with asynchronous capabilities.
 
-    This metaclass extends `ASyncMeta` to ensure that only one instance of a class
+    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__(

a_sync/a_sync/abstract.py

@@ -1,12 +1,11 @@
 """
 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.
+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 ASyncGenericBase for most use cases. This class
+Note: It is recommended to use :class:`ASyncGenericBase` for most use cases. This class
 is intended for more custom implementations if necessary.
 """
 
@@ -26,10 +25,35 @@ 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.
+    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.
     """
 
     ##################################
@@ -45,6 +69,11 @@ class ASyncABC(metaclass=ASyncMeta):
 
         Args:
             kwargs: A dictionary of keyword arguments to check for flags.
+
+        Examples:
+            >>> instance = MyASyncClass()
+            >>> instance.__a_sync_should_await__({'sync': True})
+            False
         """
         try:
             return self.__a_sync_should_await_from_kwargs__(kwargs)
@@ -58,6 +87,11 @@ class ASyncABC(metaclass=ASyncMeta):
         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
         """
         return _flags.negate_if_necessary(
             self.__a_sync_flag_name__, self.__a_sync_flag_value__
@@ -74,6 +108,11 @@ class ASyncABC(metaclass=ASyncMeta):
 
         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]
@@ -89,6 +128,10 @@ class ASyncABC(metaclass=ASyncMeta):
         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",
@@ -119,6 +162,11 @@ class ASyncABC(metaclass=ASyncMeta):
 
         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)
 

a_sync/a_sync/config.py

@@ -1,23 +1,46 @@
 """
-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'.
+        strings that start with 'p' for :class:`~concurrent.futures.ProcessPoolExecutor` 
+        (e.g., 'processes') or 't' for :class:`~concurrent.futures.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_RAM_CACHE_TTL: Sets the time-to-live for cache entries. If not specified,
+        defaults to None, meaning cache entries do not expire by default.
+        Note: Although the environment variable retrieval process uses 0 as a placeholder,
+        the actual default behavior is determined by `null_modifiers["ram_cache_ttl"]`, 
+        which is `None`.
     A_SYNC_RUNS_PER_MINUTE: Sets the rate limit for function execution.
     A_SYNC_SEMAPHORE: Sets the semaphore limit for function execution.
+
+Examples:
+    To set the executor type to use threads with 4 workers, set the environment variables:
+    
+    .. code-block:: bash
+
+        export A_SYNC_EXECUTOR_TYPE=threads
+        export A_SYNC_EXECUTOR_VALUE=4
+
+    To configure caching with a maximum size of 100 and a TTL of 60 seconds:
+
+    .. code-block:: bash
+
+        export A_SYNC_CACHE_TYPE=memory
+        export A_SYNC_RAM_CACHE_MAXSIZE=100
+        export A_SYNC_RAM_CACHE_TTL=60
+
+See Also:
+    - :mod:`concurrent.futures`: For more details on executors.
+    - :mod:`functools`: For caching mechanisms.
 """
 
 import functools
@@ -36,11 +59,25 @@ def get_default_executor() -> Executor:
     """Get the default executor based on the EXECUTOR_TYPE environment variable.
 
     Returns:
-        An instance of either ProcessPoolExecutor or ThreadPoolExecutor.
+        An instance of either :class:`~concurrent.futures.ProcessPoolExecutor`
+        or :class:`~concurrent.futures.ThreadPoolExecutor`.
 
     Raises:
         ValueError: If an invalid EXECUTOR_TYPE is specified. Valid values are
-        strings that start with 'p' for ProcessPoolExecutor or 't' for ThreadPoolExecutor.
+        strings that start with 'p' for :class:`~concurrent.futures.ProcessPoolExecutor`
+        or 't' for :class:`~concurrent.futures.ThreadPoolExecutor`.
+
+    Examples:
+        >>> import os
+        >>> os.environ["A_SYNC_EXECUTOR_TYPE"] = "threads"
+        >>> executor = get_default_executor()
+        >>> isinstance(executor, ThreadPoolExecutor)
+        True
+
+        >>> os.environ["A_SYNC_EXECUTOR_TYPE"] = "processes"
+        >>> executor = get_default_executor()
+        >>> isinstance(executor, ProcessPoolExecutor)
+        True
     """
     if EXECUTOR_TYPE.lower().startswith("p"):  # p, P, proc, Processes, etc
         return ProcessPoolExecutor(EXECUTOR_VALUE)