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

a_sync/_typing.py

@@ -1,22 +1,106 @@
 """
-This module provides type definitions and type-related utilities for the a_sync library.
-It includes various type aliases, protocols, and TypedDicts used throughout the library
-to enhance type checking and provide better IDE support.
+This module provides type definitions and type-related utilities for the `a_sync` library.
+
+It includes various type aliases and protocols used throughout the library to enhance type checking and provide better IDE support.
+
+Examples:
+    The following examples demonstrate how to use some of the type aliases and protocols defined in this module.
+
+    Example of a function that can return either an awaitable or a direct value:
+
+    ```python
+    from a_sync._typing import MaybeAwaitable
+    from typing import Awaitable
+
+    async def process_data(data: MaybeAwaitable[int]) -> int:
+        if isinstance(data, Awaitable):
+            return await data
+        return data
+
+    # Usage
+    import asyncio
+
+    async def main():
+        result = await process_data(asyncio.sleep(1, result=42))
+        print(result)  # Output: 42
+
+        result = await process_data(42)
+        print(result)  # Output: 42
+
+    asyncio.run(main())
+    ```
+
+    Example of defining a coroutine function type:
+
+    ```python
+    from a_sync._typing import CoroFn
+
+    async def async_function(x: int) -> str:
+        return str(x)
+
+    coro_fn: CoroFn[[int], str] = async_function
+    ```
+
+    Example of defining a synchronous function type:
+
+    ```python
+    from a_sync._typing import SyncFn
+
+    def sync_function(x: int) -> str:
+        return str(x)
+
+    sync_fn: SyncFn[[int], str] = sync_function
+    ```
+
+See Also:
+    - :mod:`typing`
+    - :mod:`asyncio`
 """
 
 import asyncio
 from concurrent.futures._base import Executor
 from decimal import Decimal
-from typing import (TYPE_CHECKING, Any, AsyncGenerator, AsyncIterable, AsyncIterator, 
-                    Awaitable, Callable, Coroutine, DefaultDict, Deque, Dict, Generator, 
-                    Generic, ItemsView, Iterable, Iterator, KeysView, List, Literal,
-                    Mapping, NoReturn, Optional, Protocol, Set, Tuple, Type, TypedDict,
-                    TypeVar, Union, ValuesView, final, overload, runtime_checkable)
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    AsyncGenerator,
+    AsyncIterable,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Coroutine,
+    DefaultDict,
+    Deque,
+    Dict,
+    Generator,
+    Generic,
+    ItemsView,
+    Iterable,
+    Iterator,
+    KeysView,
+    List,
+    Literal,
+    Mapping,
+    NoReturn,
+    Optional,
+    Protocol,
+    Set,
+    Tuple,
+    Type,
+    TypedDict,
+    TypeVar,
+    Union,
+    ValuesView,
+    final,
+    overload,
+    runtime_checkable,
+)
 
 from typing_extensions import Concatenate, ParamSpec, Self, Unpack
 
 if TYPE_CHECKING:
     from a_sync import ASyncGenericBase
+
     B = TypeVar("B", bound=ASyncGenericBase)
 else:
     B = TypeVar("B")
@@ -27,7 +111,7 @@ V = TypeVar("V")
 I = TypeVar("I")
 """A :class:`TypeVar` that is used to represent instances of a common class."""
 
-E = TypeVar('E', bound=Exception)
+E = TypeVar("E", bound=Exception)
 TYPE = TypeVar("TYPE", bound=Type)
 
 P = ParamSpec("P")
@@ -51,6 +135,7 @@ SyncFn = Callable[P, T]
 AnyFn = Union[CoroFn[P, T], SyncFn[P, T]]
 "Type alias for any function, whether synchronous or asynchronous."
 
+
 class CoroBoundMethod(Protocol[I, P, T]):
     """
     Protocol for coroutine bound methods.
@@ -59,13 +144,15 @@ class CoroBoundMethod(Protocol[I, P, T]):
         class MyClass:
             async def my_method(self, x: int) -> str:
                 return str(x)
-        
+
         instance = MyClass()
         bound_method: CoroBoundMethod[MyClass, [int], str] = instance.my_method
     """
+
     __self__: I
     __call__: Callable[P, Awaitable[T]]
 
+
 class SyncBoundMethod(Protocol[I, P, T]):
     """
     Protocol for synchronous bound methods.
@@ -74,36 +161,43 @@ class SyncBoundMethod(Protocol[I, P, T]):
         class MyClass:
             def my_method(self, x: int) -> str:
                 return str(x)
-        
+
         instance = MyClass()
         bound_method: SyncBoundMethod[MyClass, [int], str] = instance.my_method
     """
+
     __self__: I
     __call__: Callable[P, T]
 
+
 AnyBoundMethod = Union[CoroBoundMethod[Any, P, T], SyncBoundMethod[Any, P, T]]
 "Type alias for any bound method, whether synchronous or asynchronous."
 
+
 @runtime_checkable
 class AsyncUnboundMethod(Protocol[I, P, T]):
     """
     Protocol for unbound asynchronous methods.
-    
+
     An unbound method is a method that hasn't been bound to an instance of a class yet.
     It's essentially the function object itself, before it's accessed through an instance.
     """
+
     __get__: Callable[[I, Type], CoroBoundMethod[I, P, T]]
 
+
 @runtime_checkable
 class SyncUnboundMethod(Protocol[I, P, T]):
     """
     Protocol for unbound synchronous methods.
-    
+
     An unbound method is a method that hasn't been bound to an instance of a class yet.
     It's essentially the function object itself, before it's accessed through an instance.
     """
+
     __get__: Callable[[I, Type], SyncBoundMethod[I, P, T]]
 
+
 AnyUnboundMethod = Union[AsyncUnboundMethod[I, P, T], SyncUnboundMethod[I, P, T]]
 "Type alias for any unbound method, whether synchronous or asynchronous."
 
@@ -122,19 +216,21 @@ AsyncDecorator = Callable[[CoroFn[P, T]], CoroFn[P, T]]
 AsyncDecoratorOrCoroFn = Union[AsyncDecorator[P, T], CoroFn[P, T]]
 "Type alias for either an asynchronous decorator or a coroutine function."
 
-DefaultMode = Literal['sync', 'async', None]
+DefaultMode = Literal["sync", "async", None]
 "Type alias for default modes of operation."
 
-CacheType = Literal['memory', None]
+CacheType = Literal["memory", None]
 "Type alias for cache types."
 
 SemaphoreSpec = Optional[Union[asyncio.Semaphore, int]]
 "Type alias for semaphore specifications."
 
+
 class ModifierKwargs(TypedDict, total=False):
     """
     TypedDict for keyword arguments that modify the behavior of asynchronous operations.
     """
+
     default: DefaultMode
     cache_type: CacheType
     cache_typed: bool
@@ -145,6 +241,7 @@ class ModifierKwargs(TypedDict, total=False):
     # sync modifiers
     executor: Executor
 
+
 AnyIterable = Union[AsyncIterable[K], Iterable[K]]
 "Type alias for any iterable, whether synchronous or asynchronous."
 

a_sync/a_sync/__init__.py

@@ -1,13 +1,38 @@
+"""
+This module enables developers to write both synchronous and asynchronous code without having to write redundant code. 
+
+The two main objects you should use are
+    - a decorator `@a_sync()`
+    - a base class `ASyncGenericBase` which can be used to create classes that can be utilized in both synchronous and asynchronous contexts.
+
+The rest of the objects are exposed for type checking only, you should not make use of them otherwise.
+"""
+
+# TODO: double check on these before adding them to docs
+# - two decorators @:class:`property` and @:class:`cached_property` for the creation of dual-function properties and cached properties, respectively.
 
 from a_sync.a_sync.base import ASyncGenericBase
 from a_sync.a_sync.decorator import a_sync
-from a_sync.a_sync.function import ASyncFunction, ASyncFunctionAsyncDefault, ASyncFunctionSyncDefault
+from a_sync.a_sync.function import (
+    ASyncFunction,
+    ASyncFunctionAsyncDefault,
+    ASyncFunctionSyncDefault,
+)
 from a_sync.a_sync.modifiers.semaphores import apply_semaphore
+
 # NOTE: Some of these we purposely import without including in __all__. Do not remove.
-from a_sync.a_sync.property import (ASyncCachedPropertyDescriptor, ASyncCachedPropertyDescriptorAsyncDefault,
-                                    ASyncCachedPropertyDescriptorSyncDefault, ASyncPropertyDescriptor, 
-                                    ASyncPropertyDescriptorAsyncDefault, ASyncPropertyDescriptorSyncDefault, 
-                                    HiddenMethod, HiddenMethodDescriptor, cached_property, property)
+from a_sync.a_sync.property import (
+    ASyncCachedPropertyDescriptor,
+    ASyncCachedPropertyDescriptorAsyncDefault,
+    ASyncCachedPropertyDescriptorSyncDefault,
+    ASyncPropertyDescriptor,
+    ASyncPropertyDescriptorAsyncDefault,
+    ASyncPropertyDescriptorSyncDefault,
+    HiddenMethod,
+    HiddenMethodDescriptor,
+    cached_property,
+    property,
+)
 from a_sync.a_sync.singleton import ASyncGenericSingleton
 
 
@@ -15,14 +40,14 @@ __all__ = [
     # entrypoints
     "a_sync",
     "ASyncGenericBase",
-
-    # classes
-    "ASyncFunction",
-
+    # maybe entrypoints (?)
+    # TODO: double check how I intended for these to be used
     "property",
     "cached_property",
+    # classes exposed for type hinting only
+    "ASyncFunction",
     "ASyncPropertyDescriptor",
     "ASyncCachedPropertyDescriptor",
     "HiddenMethod",
     "HiddenMethodDescriptor",
-]
+]