ez-a-sync 0.22.14__tar.gz → 0.22.16__tar.gz

ez_a_sync-0.22.16/.github/workflows/black.yaml

@@ -0,0 +1,45 @@
+name: Black Formatter
+
+on:
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  format:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+      with:
+        ref: ${{ github.head_ref }}  # Check out the PR branch
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.12'
+
+    - name: Install Black
+      run: pip install black
+
+    - name: Run Black
+      run: black .
+
+    - name: Check for changes
+      id: changes
+      run: |
+        if [[ -n $(git status --porcelain) ]]; then
+          echo "changes_detected=true" >> $GITHUB_ENV
+        else
+          echo "changes_detected=false" >> $GITHUB_ENV
+        fi
+
+    - name: Commit changes
+      if: env.changes_detected == 'true'
+      run: |
+        git config --local user.name "github-actions[bot]"
+        git config --local user.email "github-actions[bot]@users.noreply.github.com"
+        git add .
+        git commit -m "chore: \`black .\`"
+        git push

{ez_a_sync-0.22.14 → ez_a_sync-0.22.16}/.github/workflows/mypy.yaml

@@ -30,4 +30,4 @@ jobs:
         python -m pip install --upgrade pip
         pip install mypy types-requests
     - name: Run MyPy
-      run: mypy ./a_sync --pretty --ignore-missing-imports --show-error-codes --show-error-context --enable-incomplete-feature=Unpack
+      run: mypy ./a_sync --pretty --ignore-missing-imports --show-error-codes --show-error-context --enable-incomplete-feature=Unpack --install-types --non-interactive

{ez_a_sync-0.22.14 → ez_a_sync-0.22.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: ez-a-sync
-Version: 0.22.14
+Version: 0.22.16
 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

{ez_a_sync-0.22.14 → ez_a_sync-0.22.16}/README.md

@@ -13,12 +13,25 @@
         - [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
 
 `ez-a-sync` is a Python library that enables developers to write both synchronous and asynchronous code without having to write redundant code. It provides a decorator `@a_sync()`, as well as a base class `ASyncGenericBase` which can be used to create classes that can be executed in both synchronous and asynchronous contexts.
 
+It also contains implementations of various asyncio primitives with extra functionality, including queues and various types of locks.
+\# TODO add links to various objects' docs
+
 ## Installation
 
 `ez-a-sync` can be installed via pip:
@@ -192,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.22.16/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 truthy value other than an 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.16/a_sync/__init__.py

@@ -0,0 +1,125 @@
+"""
+This module initializes the a_sync library by importing and organizing various components, utilities, and classes.
+It provides a convenient and unified interface for asynchronous programming with a focus on flexibility and efficiency.
+
+The `a_sync` library offers decorators and base classes to facilitate writing both synchronous and asynchronous code.
+It includes the `@a_sync()` decorator and the `ASyncGenericBase` class, which allow for creating functions and classes
+that can operate in both synchronous and asynchronous contexts. Additionally, it provides enhanced asyncio primitives,
+such as queues and locks, with extra functionality.
+
+Modules and components included:
+- :mod:`~aliases`, :mod:`~exceptions`, :mod:`~iter`, :mod:`~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:`~ASyncFilter`, :class:`~ASyncSorter`, :class:`~ASyncIterable`, :class:`~ASyncIterator` for async iteration.
+- Utilities: :func:`~all`, :func:`~any`, :func:`~as_yielded`, :func:`~exhaust_iterator`, :func:`~exhaust_iterators` for async utilities.
+- :func:`~apply_semaphore`: Function to apply semaphores to coroutines.
+
+Alias for backward compatibility:
+- :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
+from a_sync.a_sync import ASyncGenericBase, ASyncGenericSingleton, a_sync
+from a_sync.a_sync.modifiers.semaphores import apply_semaphore
+from a_sync.a_sync.property import (
+    ASyncCachedPropertyDescriptor,
+    ASyncPropertyDescriptor,
+    cached_property,
+    property,
+)
+from a_sync.asyncio import as_completed, create_task, gather
+from a_sync.executor import *
+from a_sync.executor import AsyncThreadPoolExecutor as ThreadPoolExecutor
+from a_sync.executor import AsyncProcessPoolExecutor as ProcessPoolExecutor
+from a_sync.future import ASyncFuture, future  # type: ignore [attr-defined]
+from a_sync.iter import ASyncFilter as filter
+from a_sync.iter import ASyncSorter as sorted
+from a_sync.iter import ASyncIterable, ASyncIterator
+from a_sync.primitives import *
+from a_sync.task import TaskMapping as map
+from a_sync.task import TaskMapping, create_task
+from a_sync.utils import all, any, as_yielded
+
+# I alias the aliases for your convenience.
+# I prefer "aka" but its meaning is not intuitive when reading code so I created both aliases for you to choose from.
+# NOTE: Overkill? Maybe.
+aka = alias = aliases
+
+# alias for backward-compatability, will be removed eventually, probably in 0.1.0
+ASyncBase = ASyncGenericBase
+
+__all__ = [
+    # modules
+    "exceptions",
+    "iter",
+    "task",
+    # builtins
+    "sorted",
+    "filter",
+    # asyncio
+    "create_task",
+    "gather",
+    "as_completed",
+    # functions
+    "a_sync",
+    "all",
+    "any",
+    "as_yielded",
+    "exhaust_iterator",
+    "exhaust_iterators",
+    "map",
+    # classes
+    "ASyncIterable",
+    "ASyncIterator",
+    "ASyncGenericSingleton",
+    "TaskMapping",
+    # property
+    "cached_property",
+    "property",
+    "ASyncPropertyDescriptor",
+    "ASyncCachedPropertyDescriptor",
+    # semaphores
+    "Semaphore",
+    "PrioritySemaphore",
+    "ThreadsafeSemaphore",
+    # queues
+    "Queue",
+    "ProcessingQueue",
+    "SmartProcessingQueue",
+    # locks
+    "CounterLock",
+    "Event",
+    # executors
+    "AsyncThreadPoolExecutor",
+    "PruningThreadPoolExecutor",
+    "AsyncProcessPoolExecutor",
+    # executor aliases
+    "ThreadPoolExecutor",
+    "ProcessPoolExecutor",
+]