ez-a-sync 0.22.15__tar.gz → 0.23.0__tar.gz

{ez_a_sync-0.22.15 → ez_a_sync-0.23.0}/.github/workflows/pytest.yaml

@@ -38,10 +38,12 @@ jobs:
           python-version: ${{ matrix.pyversion }}
 
       - name: Install dependencies
+        run: pip install -r requirements.txt -r requirements-dev.txt
+
+      - name: Install ez-a-sync
         run: |
-          pip install pytest
-          pip install -r requirements.txt
-          pip install -r requirements-dev.txt
+          python setup.py build_ext --inplace
+          python setup.py install
       
       - name: Run test suite
         run: pytest

{ez_a_sync-0.22.15 → ez_a_sync-0.23.0}/.github/workflows/release.yaml

@@ -21,11 +21,11 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install setuptools wheel twine
+        pip install setuptools wheel twine cython
     - name: Build and publish
       env:
         TWINE_USERNAME: __token__
         TWINE_PASSWORD: ${{ secrets.PYPI_PASSWORD }}
       run: |
-        python setup.py sdist bdist_wheel
+        python setup.py sdist
         twine upload dist/*

{ez_a_sync-0.22.15 → ez_a_sync-0.23.0}/.gitignore

@@ -8,4 +8,8 @@ dist/
 .eggs/
 *.egg-info
 cache/**/*.json
-cache/**/*.pkl
+cache/**/*.pkl
+mypy_plugin_tests/mypy
+mypy_plugin_tests/venv
+*.c
+*.so

{ez_a_sync-0.22.15 → ez_a_sync-0.23.0}/Makefile

@@ -6,3 +6,6 @@ docs:
 	rm -r ./docs/_templates -f
 	rm -r ./docs/_build -f
 	sphinx-apidoc --private -o ./docs/source ./a_sync
+
+cython:
+	python csetup.py build_ext --inplace

{ez_a_sync-0.22.15 → ez_a_sync-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ez-a-sync
-Version: 0.22.15
+Version: 0.23.0
 Summary: A library that makes it easy to define objects that can be used for both sync and async use cases.
 Home-page: https://github.com/BobTheBuidler/a-sync
 Author: BobTheBuidler
@@ -11,5 +11,6 @@ License-File: LICENSE.txt
 Requires-Dist: aiolimiter==1.0.0
 Requires-Dist: async_lru_threadsafe==2.0.4
 Requires-Dist: async_property==0.2.1
+Requires-Dist: Cython>=3.0.11
 Requires-Dist: typed_envs>=0.0.2
 Requires-Dist: typing_extensions>=4.1.0

{ez_a_sync-0.22.15 → ez_a_sync-0.23.0}/README.md

@@ -13,6 +13,16 @@
         - [async modifiers](#async-modifiers)
         - [sync modifiers](#sync-modifiers)
         - [Default Modifiers](#default-modifiers)
+    - [Other Helpful Classes](#other-helpful-modules)
+        - [ASyncIterable](#asynciterable)
+        - [ASyncIterator](#asynciterator)
+        - [ASyncFilter](#asyncfilter)
+        - [ASyncSorter](#asyncsorter)
+- [Other Helpful Modules](#other-helpful-modules)
+    - [future](#future)
+        - [ASyncFuture](#asyncfuture)
+        - [future decorator](#future-decorator)
+    - [asyncio](#asyncio)
 
 <!-- /TOC -->
 ## Introduction
@@ -195,3 +205,125 @@ Instead of setting modifiers one by one in functions, you can set a default valu
 - `RAM_CACHE_TTL`
 - `RUNS_PER_MINUTE`
 - `SEMAPHORE`
+
+### Other Helpful Classes
+#### ASyncIterable
+The [ASyncIterable](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.ASyncIterable) class allows objects to be iterated over using either a standard `for` loop or an `async for` loop. This is particularly useful in scenarios where the mode of iteration needs to be flexible or is determined at runtime.
+
+```python
+from a_sync import ASyncIterable
+
+async_iterable = ASyncIterable(some_async_iterable)
+
+# Asynchronous iteration
+async for item in async_iterable:
+    ...
+
+# Synchronous iteration
+for item in async_iterable:
+    ...
+```
+
+See the [documentation](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.ASyncIterable) for more information.
+
+#### ASyncIterator
+
+The [ASyncIterator](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.ASyncIterator) class provides a unified interface for iteration that can operate in both synchronous and asynchronous contexts. It allows the wrapping of asynchronous iterable objects or async generator functions.
+
+```python
+from a_sync import ASyncIterator
+
+async_iterator = ASyncIterator(some_async_iterator)
+
+# Asynchronous iteration
+async for item in async_iterator:
+    ...
+
+# Synchronous iteration
+for item in async_iterator:
+    ...
+```
+
+See the [documentation](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.ASyncIterator) for more information.
+
+#### ASyncFilter
+
+The [ASyncFilter](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.ASyncFilter) class filters items of an async iterable based on a provided function. It can handle both synchronous and asynchronous filter functions.
+
+```python
+from a_sync import ASyncFilter
+
+async def is_even(x):
+    return x % 2 == 0
+
+filtered_iterable = ASyncFilter(is_even, some_async_iterable)
+
+# or use the alias
+import a_sync
+
+filtered_iterable = a_sync.filter(is_even, some_async_iterable)
+
+# Asynchronous iteration
+async for item in filtered_iterable:
+    ...
+
+# Synchronous iteration
+for item in filtered_iterable:
+    ...
+```
+
+See the [documentation](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.ASyncFilter) for more information.
+
+#### ASyncSorter
+
+The [ASyncSorter](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.ASyncSorter) class sorts items of an async iterable based on a provided key function. It supports both synchronous and asynchronous key functions.
+
+```python
+from a_sync import ASyncSorter
+
+sorted_iterable = ASyncSorter(some_async_iterable, key=lambda x: x.value)
+
+# or use the alias
+import a_sync
+
+sorted_iterable = a_sync.sort(some_async_iterable, key=lambda x: x.value)
+
+# Asynchronous iteration
+async for item in sorted_iterable:
+    ...
+
+# Synchronous iteration
+for item in sorted_iterable:
+    ...
+```
+
+See the [documentation](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.ASyncSorter) for more information.
+
+## Other Helpful Modules
+The stuff here is unrelated to the main purpose of ez-a-sync, but cool and useful nonetheless
+
+### asyncio
+
+The `ez-a-sync` library extends the functionality of Python's `asyncio` module with additional utilities to simplify asynchronous programming.
+
+- **as_completed**: This function allows you to iterate over awaitables as they complete, similar to `asyncio.as_completed`. It supports both synchronous and asynchronous iteration. [Learn more about `as_completed`](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.asyncio.as_completed).
+
+- **gather**: A utility to run multiple asynchronous operations concurrently and wait for all of them to complete. It is similar to `asyncio.gather` but integrates seamlessly with the `ez-a-sync` library. [Learn more about `gather`](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.asyncio.gather).
+
+- **create_task**: A function to create a new task from a coroutine, similar to `asyncio.create_task`, but with additional features provided by `ez-a-sync`. [Learn more about `create_task`](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.asyncio.create_task).
+
+- **as_completed**: This function allows you to iterate over awaitables as they complete, similar to `asyncio.as_completed`. It supports both synchronous and asynchronous iteration. [Learn more about `as_completed`](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.asyncio.as_completed).
+
+These utilities enhance the standard `asyncio` module, providing more flexibility and control over asynchronous operations. For detailed documentation and examples, please refer to the [documentation](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.asyncio)
+
+### future
+The future module is something totally different. 
+ TODO: short explainer of module value prop and use case
+
+#### ASyncFuture
+[documentation](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.future.ASyncFuture)
+ TODO: short explainers on ASyncFuture class
+
+#### future decorator
+[documentation](#https://bobthebuidler.github.io/ez-a-sync/source/a_sync.html#a_sync.future.future)
+ TODO: short explainers on future fn

ez_a_sync-0.23.0/a_sync/ENVIRONMENT_VARIABLES.py

@@ -0,0 +1,44 @@
+from typed_envs import EnvVarFactory
+
+envs = EnvVarFactory("EZASYNC")
+
+# We have some envs here to help you debug your custom class implementations
+
+DEBUG_CLASS_NAME = envs.create_env("DEBUG_CLASS_NAME", str, default="", verbose=False)
+"""str: The name of the class to debug.
+
+If you're only interested in debugging a specific class, set this to the class name.
+
+Examples:
+    To debug a class named `MyClass`, set the environment variable:
+    
+    .. code-block:: bash
+
+        export EZASYNC_DEBUG_CLASS_NAME=MyClass
+
+See Also:
+    :func:`DEBUG_MODE` for enabling debug mode on all classes.
+"""
+
+DEBUG_MODE = envs.create_env(
+    "DEBUG_MODE", bool, default=bool(DEBUG_CLASS_NAME), verbose=False
+)
+"""bool: Enables debug mode on all classes.
+
+Set this environment variable to `True` to enable debug mode on all classes. 
+If `DEBUG_CLASS_NAME` is set to a non-empty string, 
+`DEBUG_MODE` will default to `True`.
+
+Examples:
+    To enable debug mode globally, set the environment variable:
+
+    .. code-block:: bash
+
+        export EZASYNC_DEBUG_MODE=True
+
+    If you have set `DEBUG_CLASS_NAME` to a specific class, `DEBUG_MODE` will 
+    automatically be `True` unless `DEBUG_CLASS_NAME` is an empty string.
+
+See Also:
+    :func:`DEBUG_CLASS_NAME` for debugging a specific class.
+"""

{ez_a_sync-0.22.15 → ez_a_sync-0.23.0}/a_sync/__init__.py

@@ -8,17 +8,40 @@ that can operate in both synchronous and asynchronous contexts. Additionally, it
 such as queues and locks, with extra functionality.
 
 Modules and components included:
-- `aliases`, `exceptions`, `iter`, `task`: Core modules of the library.
-- `ASyncGenericBase`, `ASyncGenericSingleton`, `a_sync`: Base classes and decorators for dual-context execution.
-- `apply_semaphore`: Function to apply semaphores to coroutines.
-- `ASyncCachedPropertyDescriptor`, `ASyncPropertyDescriptor`, `cached_property`, `property`: Property descriptors for async properties.
-- `as_completed`, `create_task`, `gather`: Enhanced asyncio functions.
-- Executors: `AsyncThreadPoolExecutor`, `AsyncProcessPoolExecutor`, `PruningThreadPoolExecutor` for async execution.
-- Iterators: `ASyncFilter`, `ASyncSorter`, `ASyncIterable`, `ASyncIterator` for async iteration.
-- Utilities: `all`, `any`, `as_yielded` for async utilities.
+    - :mod:`~a_sync.aliases`, :mod:`~a_sync.exceptions`, :mod:`~a_sync.iter`, :mod:`~a_sync.task`: Core modules of the library.
+    - :class:`~ASyncGenericBase`, :class:`~ASyncGenericSingleton`, :func:`~a_sync`: Base classes and decorators for dual-context execution.
+    - :class:`~ASyncCachedPropertyDescriptor`, :class:`~ASyncPropertyDescriptor`, `cached_property`, `property`: Property descriptors for async properties.
+    - :func:`~as_completed`, :func:`~create_task`, :func:`~gather`: Enhanced asyncio functions.
+    - Executors: :class:`~AsyncThreadPoolExecutor`, :class:`~AsyncProcessPoolExecutor`, :class:`~PruningThreadPoolExecutor` for async execution.
+    - Iterators: :class:`~ASyncIterable`, :class:`~ASyncIterator`, :class:`~filter`, :class:`~sorted` for async iteration.
+    - Utilities: :func:`~all`, :func:`~any`, :func:`~as_yielded` for async utilities.
+    - :func:`~a_sync.a_sync.modifiers.semaphores.apply_semaphore`: Function to apply semaphores to coroutines.
 
 Alias for backward compatibility:
-- `ASyncBase` is an alias for `ASyncGenericBase`, which will be removed eventually, probably in version 0.1.0.
+- :class:`~ASyncBase` is an alias for :class:`~ASyncGenericBase`, which will be removed eventually, probably in version 0.1.0.
+
+Examples:
+    Using the `@a_sync` decorator:
+    >>> from a_sync import a_sync
+    >>> @a_sync
+    ... async def my_function():
+    ...     return "Hello, World!"
+    >>> result = await my_function()
+    >>> print(result)
+
+    Using `ASyncGenericBase` for dual-context classes:
+    >>> from a_sync import ASyncGenericBase
+    >>> class MyClass(ASyncGenericBase):
+    ...     async def my_method(self):
+    ...         return "Hello from MyClass"
+    >>> obj = MyClass()
+    >>> result = await obj.my_method()
+    >>> print(result)
+
+See Also:
+    - :mod:`a_sync.a_sync`: Contains the core classes and decorators.
+    - :mod:`a_sync.asyncio`: Provides enhanced asyncio functions.
+    - :mod:`a_sync.primitives`: Includes modified versions of standard asyncio primitives.
 """
 
 from a_sync import aliases, exceptions, iter, task
@@ -68,8 +91,6 @@ __all__ = [
     "all",
     "any",
     "as_yielded",
-    "exhaust_iterator",
-    "exhaust_iterators",
     "map",
     # classes
     "ASyncIterable",

{ez_a_sync-0.22.15 → ez_a_sync-0.23.0}/a_sync/_smart.py

@@ -1,7 +1,8 @@
 """
 This module defines smart future and task utilities for the a_sync library.
 These utilities provide enhanced functionality for managing asynchronous tasks and futures,
-including task shielding and a custom task factory for creating SmartTask instances.
+including a custom task factory for creating :class:`~SmartTask` instances and a shielding mechanism
+to protect tasks from cancellation.
 """
 
 import asyncio
@@ -28,6 +29,26 @@ class _SmartFutureMixin(Generic[T]):
     Mixin class that provides common functionality for smart futures and tasks.
 
     This mixin provides methods for managing waiters and integrating with a smart processing queue.
+    It uses weak references to manage resources efficiently.
+
+    Example:
+        Creating a SmartFuture and awaiting it:
+
+        ```python
+        future = SmartFuture()
+        result = await future
+        ```
+
+        Creating a SmartTask and awaiting it:
+
+        ```python
+        task = SmartTask(coro=my_coroutine())
+        result = await task
+        ```
+
+    See Also:
+        - :class:`SmartFuture`
+        - :class:`SmartTask`
     """
 
     _queue: Optional["SmartProcessingQueue[Any, Any, T]"] = None
@@ -37,6 +58,27 @@ class _SmartFutureMixin(Generic[T]):
     def __await__(self: Union["SmartFuture", "SmartTask"]) -> Generator[Any, None, T]:
         """
         Await the smart future or task, handling waiters and logging.
+
+        Yields:
+            The result of the future or task.
+
+        Raises:
+            RuntimeError: If await wasn't used with future.
+
+        Example:
+            Awaiting a SmartFuture:
+
+            ```python
+            future = SmartFuture()
+            result = await future
+            ```
+
+            Awaiting a SmartTask:
+
+            ```python
+            task = SmartTask(coro=my_coroutine())
+            result = await task
+            ```
         """
         if self.done():
             return self.result()  # May raise too.
@@ -51,12 +93,22 @@ class _SmartFutureMixin(Generic[T]):
 
     @property
     def num_waiters(self: Union["SmartFuture", "SmartTask"]) -> int:
-        # NOTE: we check .done() because the callback may not have ran yet and its very lightweight
         """
         Get the number of waiters currently awaiting the future or task.
+
+        This property checks if the future or task is done to ensure accurate counting
+        of waiters, as the callback may not have run yet.
+
+        Example:
+            ```python
+            future = SmartFuture()
+            print(future.num_waiters)
+            ```
+
+        See Also:
+            - :meth:`_waiter_done_cleanup_callback`
         """
         if self.done():
-            # if there are any waiters left, there won't be once the event loop runs once
             return 0
         return sum(getattr(waiter, "num_waiters", 1) or 1 for waiter in self._waiters)
 
@@ -66,7 +118,13 @@ class _SmartFutureMixin(Generic[T]):
         """
         Callback to clean up waiters when a waiter task is done.
 
-        Removes the waiter from _waiters, and _queue._futs if applicable
+        Removes the waiter from _waiters, and _queue._futs if applicable.
+
+        Args:
+            waiter: The waiter task to clean up.
+
+        Example:
+            Automatically called when a waiter task completes.
         """
         if not self.done():
             self._waiters.remove(waiter)
@@ -74,6 +132,8 @@ class _SmartFutureMixin(Generic[T]):
     def _self_done_cleanup_callback(self: Union["SmartFuture", "SmartTask"]) -> None:
         """
         Callback to clean up waiters and remove the future from the queue when done.
+
+        This method clears all waiters and removes the future from the associated queue.
         """
         self._waiters.clear()
         if queue := self._queue:
@@ -84,8 +144,20 @@ class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
     """
     A smart future that tracks waiters and integrates with a smart processing queue.
 
-    Inherits from both _SmartFutureMixin and asyncio.Future, providing additional functionality
+    Inherits from both :class:`_SmartFutureMixin` and :class:`asyncio.Future`, providing additional functionality
     for tracking waiters and integrating with a smart processing queue.
+
+    Example:
+        Creating and awaiting a SmartFuture:
+
+        ```python
+        future = SmartFuture()
+        await future
+        ```
+
+    See Also:
+        - :class:`_SmartFutureMixin`
+        - :class:`asyncio.Future`
     """
 
     _queue = None
@@ -105,6 +177,14 @@ class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
             queue: Optional; a smart processing queue.
             key: Optional; a key identifying the future.
             loop: Optional; the event loop.
+
+        Example:
+            ```python
+            future = SmartFuture(queue=my_queue, key=my_key)
+            ```
+
+        See Also:
+            - :class:`SmartProcessingQueue`
         """
         super().__init__(loop=loop)
         if queue:
@@ -125,8 +205,15 @@ class SmartFuture(_SmartFutureMixin[T], asyncio.Future):
         Args:
             other: Another SmartFuture to compare with.
 
-        Returns:
-            True if self has more waiters than other.
+        Example:
+            ```python
+            future1 = SmartFuture()
+            future2 = SmartFuture()
+            print(future1 < future2)
+            ```
+
+        See Also:
+            - :meth:`num_waiters`
         """
         return self.num_waiters > other.num_waiters
 
@@ -138,7 +225,7 @@ def create_future(
     loop: Optional[asyncio.AbstractEventLoop] = None,
 ) -> SmartFuture[V]:
     """
-    Create a SmartFuture instance.
+    Create a :class:`~SmartFuture` instance.
 
     Args:
         queue: Optional; a smart processing queue.
@@ -147,6 +234,16 @@ def create_future(
 
     Returns:
         A SmartFuture instance.
+
+    Example:
+        Creating a SmartFuture using the factory function:
+
+        ```python
+        future = create_future(queue=my_queue, key=my_key)
+        ```
+
+    See Also:
+        - :class:`SmartFuture`
     """
     return SmartFuture(queue=queue, key=key, loop=loop or asyncio.get_event_loop())
 
@@ -155,8 +252,20 @@ class SmartTask(_SmartFutureMixin[T], asyncio.Task):
     """
     A smart task that tracks waiters and integrates with a smart processing queue.
 
-    Inherits from both _SmartFutureMixin and asyncio.Task, providing additional functionality
+    Inherits from both :class:`_SmartFutureMixin` and :class:`asyncio.Task`, providing additional functionality
     for tracking waiters and integrating with a smart processing queue.
+
+    Example:
+        Creating and awaiting a SmartTask:
+
+        ```python
+        task = SmartTask(coro=my_coroutine())
+        await task
+        ```
+
+    See Also:
+        - :class:`_SmartFutureMixin`
+        - :class:`asyncio.Task`
     """
 
     def __init__(
@@ -173,6 +282,14 @@ class SmartTask(_SmartFutureMixin[T], asyncio.Task):
             coro: The coroutine to run in the task.
             loop: Optional; the event loop.
             name: Optional; the name of the task.
+
+        Example:
+            ```python
+            task = SmartTask(coro=my_coroutine(), name="my_task")
+            ```
+
+        See Also:
+            - :func:`asyncio.create_task`
         """
         super().__init__(coro, loop=loop, name=name)
         self._waiters: Set["asyncio.Task[T]"] = set()
@@ -193,6 +310,18 @@ def smart_task_factory(
 
     Returns:
         A SmartTask instance running the provided coroutine.
+
+    Example:
+        Using the smart task factory to create a SmartTask:
+
+        ```python
+        loop = asyncio.get_event_loop()
+        task = smart_task_factory(loop, my_coroutine())
+        ```
+
+    See Also:
+        - :func:`set_smart_task_factory`
+        - :class:`SmartTask`
     """
     return SmartTask(coro, loop=loop)
 
@@ -203,6 +332,16 @@ def set_smart_task_factory(loop: asyncio.AbstractEventLoop = None) -> None:
 
     Args:
         loop: Optional; the event loop. If None, the current event loop is used.
+
+    Example:
+        Setting the smart task factory for the current event loop:
+
+        ```python
+        set_smart_task_factory()
+        ```
+
+    See Also:
+        - :func:`smart_task_factory`
     """
     if loop is None:
         loop = a_sync.asyncio.get_event_loop()
@@ -211,7 +350,7 @@ def set_smart_task_factory(loop: asyncio.AbstractEventLoop = None) -> None:
 
 def shield(
     arg: Awaitable[T], *, loop: Optional[asyncio.AbstractEventLoop] = None
-) -> SmartFuture[T]:
+) -> Union[SmartFuture[T], asyncio.Future]:
     """
     Wait for a future, shielding it from cancellation.
 
@@ -241,6 +380,19 @@ def shield(
     Args:
         arg: The awaitable to shield from cancellation.
         loop: Optional; the event loop. Deprecated since Python 3.8.
+
+    Returns:
+        A :class:`SmartFuture` or :class:`asyncio.Future` instance.
+
+    Example:
+        Using shield to protect a coroutine from cancellation:
+
+        ```python
+        result = await shield(my_coroutine())
+        ```
+
+    See Also:
+        - :func:`asyncio.shield`
     """
     if loop is not None:
         warnings.warn(

{ez_a_sync-0.22.15 → ez_a_sync-0.23.0}/a_sync/_typing.py

@@ -1,7 +1,67 @@
 """
-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 using `CoroFn` with `ParamSpec`:
+
+    ```python
+    from a_sync._typing import CoroFn
+    from typing_extensions import ParamSpec
+    from typing import Awaitable
+
+    P = ParamSpec("P")
+
+    async def async_function(x: int) -> str:
+        return str(x)
+
+    coro_fn: CoroFn[[int], str] = async_function
+    ```
+
+    Example of defining a synchronous function type using `SyncFn` with `ParamSpec`:
+
+    ```python
+    from a_sync._typing import SyncFn
+    from typing_extensions import ParamSpec
+
+    P = ParamSpec("P")
+
+    def sync_function(x: int) -> str:
+        return str(x)
+
+    sync_fn: SyncFn[[int], str] = sync_function
+    ```
+
+See Also:
+    - :mod:`typing`
+    - :mod:`asyncio`
 """
 
 import asyncio