python-utils 3.8.2__py2.py3-none-any.whl → 3.9.1__py2.py3-none-any.whl

python_utils/__about__.py

@@ -1,3 +1,15 @@
+"""
+This module contains metadata about the `python-utils` package.
+
+Attributes:
+    __package_name__ (str): The name of the package.
+    __author__ (str): The author of the package.
+    __author_email__ (str): The email of the author.
+    __description__ (str): A brief description of the package.
+    __url__ (str): The URL of the package's repository.
+    __version__ (str): The current version of the package.
+"""
+
 __package_name__: str = 'python-utils'
 __author__: str = 'Rick van Hattem'
 __author_email__: str = 'Wolph@wol.ph'
@@ -7,4 +19,4 @@ __description__: str = (
 )
 __url__: str = 'https://github.com/WoLpH/python-utils'
 # Omit type info due to automatic versioning script
-__version__ = '3.8.2'
+__version__ = '3.9.1'

python_utils/__init__.py

@@ -1,6 +1,56 @@
+"""
+This module initializes the `python_utils` package by importing various
+submodules and functions.
+
+Submodules:
+    aio
+    converters
+    decorators
+    formatters
+    generators
+    import_
+    logger
+    terminal
+    time
+    types
+
+Functions:
+    acount
+    remap
+    scale_1024
+    to_float
+    to_int
+    to_str
+    to_unicode
+    listify
+    set_attributes
+    raise_exception
+    reraise
+    camel_to_underscore
+    timesince
+    abatcher
+    batcher
+    import_global
+    get_terminal_size
+    aio_generator_timeout_detector
+    aio_generator_timeout_detector_decorator
+    aio_timeout_generator
+    delta_to_seconds
+    delta_to_seconds_or_none
+    format_time
+    timedelta_to_seconds
+    timeout_generator
+
+Classes:
+    CastedDict
+    LazyCastedDict
+    UniqueList
+    Logged
+    LoggerBase
+"""
+
 from . import (
     aio,
-    compat,
     converters,
     decorators,
     formatters,
@@ -33,45 +83,44 @@ from .time import (
 )
 
 __all__ = [
+    'CastedDict',
+    'LazyCastedDict',
+    'Logged',
+    'LoggerBase',
+    'UniqueList',
+    'abatcher',
+    'acount',
     'aio',
-    'generators',
-    'compat',
+    'aio_generator_timeout_detector',
+    'aio_generator_timeout_detector_decorator',
+    'aio_timeout_generator',
+    'batcher',
+    'camel_to_underscore',
     'converters',
     'decorators',
+    'delta_to_seconds',
+    'delta_to_seconds_or_none',
+    'format_time',
     'formatters',
+    'generators',
+    'get_terminal_size',
     'import_',
+    'import_global',
+    'listify',
     'logger',
-    'terminal',
-    'time',
-    'types',
-    'to_int',
-    'to_float',
-    'to_unicode',
-    'to_str',
-    'scale_1024',
+    'raise_exception',
     'remap',
+    'reraise',
+    'scale_1024',
     'set_attributes',
-    'listify',
-    'camel_to_underscore',
-    'timesince',
-    'import_global',
-    'get_terminal_size',
+    'terminal',
+    'time',
     'timedelta_to_seconds',
-    'format_time',
     'timeout_generator',
-    'acount',
-    'abatcher',
-    'batcher',
-    'aio_timeout_generator',
-    'aio_generator_timeout_detector_decorator',
-    'aio_generator_timeout_detector',
-    'delta_to_seconds',
-    'delta_to_seconds_or_none',
-    'reraise',
-    'raise_exception',
-    'Logged',
-    'LoggerBase',
-    'CastedDict',
-    'LazyCastedDict',
-    'UniqueList',
+    'timesince',
+    'to_float',
+    'to_int',
+    'to_str',
+    'to_unicode',
+    'types',
 ]

python_utils/aio.py

@@ -1,14 +1,15 @@
-'''
-Asyncio equivalents to regular Python functions.
+"""Asyncio equivalents to regular Python functions."""
 
-'''
 import asyncio
 import itertools
+import typing
 
 from . import types
 
 _N = types.TypeVar('_N', int, float)
 _T = types.TypeVar('_T')
+_K = types.TypeVar('_K')
+_V = types.TypeVar('_V')
 
 
 async def acount(
@@ -17,7 +18,7 @@ async def acount(
     delay: float = 0,
     stop: types.Optional[_N] = None,
 ) -> types.AsyncIterator[_N]:
-    '''Asyncio version of itertools.count()'''
+    """Asyncio version of itertools.count()."""
     for item in itertools.count(start, step):  # pragma: no branch
         if stop is not None and item >= stop:
             break
@@ -26,20 +27,52 @@ async def acount(
         await asyncio.sleep(delay)
 
 
+@typing.overload
 async def acontainer(
     iterable: types.Union[
         types.AsyncIterable[_T],
         types.Callable[..., types.AsyncIterable[_T]],
     ],
-    container: types.Callable[[types.Iterable[_T]], types.Iterable[_T]] = list,
-) -> types.Iterable[_T]:
-    '''
-    Asyncio version of list()/set()/tuple()/etc() using an async for loop
+    container: types.Type[types.Tuple[_T, ...]],
+) -> types.Tuple[_T, ...]: ...
+
+
+@typing.overload
+async def acontainer(
+    iterable: types.Union[
+        types.AsyncIterable[_T],
+        types.Callable[..., types.AsyncIterable[_T]],
+    ],
+    container: types.Type[types.List[_T]] = list,
+) -> types.List[_T]: ...
+
+
+@typing.overload
+async def acontainer(
+    iterable: types.Union[
+        types.AsyncIterable[_T],
+        types.Callable[..., types.AsyncIterable[_T]],
+    ],
+    container: types.Type[types.Set[_T]],
+) -> types.Set[_T]: ...
+
+
+async def acontainer(
+    iterable: types.Union[
+        types.AsyncIterable[_T],
+        types.Callable[..., types.AsyncIterable[_T]],
+    ],
+    container: types.Callable[
+        [types.Iterable[_T]], types.Collection[_T]
+    ] = list,
+) -> types.Collection[_T]:
+    """
+    Asyncio version of list()/set()/tuple()/etc() using an async for loop.
 
     So instead of doing `[item async for item in iterable]` you can do
     `await acontainer(iterable)`.
 
-    '''
+    """
     iterable_: types.AsyncIterable[_T]
     if callable(iterable):
         iterable_ = iterable()
@@ -52,3 +85,33 @@ async def acontainer(
         items.append(item)
 
     return container(items)
+
+
+async def adict(
+    iterable: types.Union[
+        types.AsyncIterable[types.Tuple[_K, _V]],
+        types.Callable[..., types.AsyncIterable[types.Tuple[_K, _V]]],
+    ],
+    container: types.Callable[
+        [types.Iterable[types.Tuple[_K, _V]]], types.Mapping[_K, _V]
+    ] = dict,
+) -> types.Mapping[_K, _V]:
+    """
+    Asyncio version of dict() using an async for loop.
+
+    So instead of doing `{key: value async for key, value in iterable}` you
+    can do `await adict(iterable)`.
+
+    """
+    iterable_: types.AsyncIterable[types.Tuple[_K, _V]]
+    if callable(iterable):
+        iterable_ = iterable()
+    else:
+        iterable_ = iterable
+
+    item: types.Tuple[_K, _V]
+    items: types.List[types.Tuple[_K, _V]] = []
+    async for item in iterable_:  # pragma: no branch
+        items.append(item)
+
+    return container(items)