haiway 0.23.2__py3-none-any.whl → 0.24.1__py3-none-any.whl

haiway/__init__.py

@@ -18,6 +18,7 @@ from haiway.helpers import (
     LoggerObservability,
     asynchronous,
     cache,
+    execute_concurrently,
     process_concurrently,
     retry,
     throttle,
@@ -32,7 +33,7 @@ from haiway.types import (
     Missing,
     is_missing,
     not_missing,
-    when_missing,
+    unwrap_missing,
 )
 from haiway.utils import (
     AsyncQueue,
@@ -44,6 +45,7 @@ from haiway.utils import (
     as_tuple,
     async_always,
     async_noop,
+    getenv,
     getenv_base64,
     getenv_bool,
     getenv_float,
@@ -89,6 +91,8 @@ __all__ = (
     "asynchronous",
     "cache",
     "ctx",
+    "execute_concurrently",
+    "getenv",
     "getenv_base64",
     "getenv_bool",
     "getenv_float",
@@ -104,6 +108,6 @@ __all__ = (
     "throttle",
     "timeout",
     "traced",
-    "when_missing",
+    "unwrap_missing",
     "without_missing",
 )

haiway/context/access.py

@@ -3,7 +3,6 @@ from asyncio import (
     Task,
     TaskGroup,
     current_task,
-    iscoroutinefunction,
 )
 from collections.abc import (
     AsyncGenerator,
@@ -28,7 +27,6 @@ from haiway.context.observability import (
 from haiway.context.state import ScopeState, StateContext
 from haiway.context.tasks import TaskGroupContext
 from haiway.state import State
-from haiway.utils import mimic_function
 from haiway.utils.stream import AsyncStream
 
 __all__ = ("ctx",)
@@ -218,44 +216,6 @@ class ScopeContext:
             exc_tb=exc_tb,
         )
 
-    @overload
-    def __call__[Result, **Arguments](
-        self,
-        function: Callable[Arguments, Coroutine[Any, Any, Result]],
-    ) -> Callable[Arguments, Coroutine[Any, Any, Result]]: ...
-
-    @overload
-    def __call__[Result, **Arguments](
-        self,
-        function: Callable[Arguments, Result],
-    ) -> Callable[Arguments, Result]: ...
-
-    def __call__[Result, **Arguments](
-        self,
-        function: Callable[Arguments, Coroutine[Any, Any, Result]] | Callable[Arguments, Result],
-    ) -> Callable[Arguments, Coroutine[Any, Any, Result]] | Callable[Arguments, Result]:
-        if iscoroutinefunction(function):
-
-            async def async_context(
-                *args: Arguments.args,
-                **kwargs: Arguments.kwargs,
-            ) -> Result:
-                async with self:
-                    return await function(*args, **kwargs)
-
-            return mimic_function(function, within=async_context)
-
-        else:
-
-            def sync_context(
-                *args: Arguments.args,
-                **kwargs: Arguments.kwargs,
-            ) -> Result:
-                with self:
-                    return function(*args, **kwargs)  # pyright: ignore[reportReturnType]
-
-            return mimic_function(function, within=sync_context)  # pyright: ignore[reportReturnType]
-
 
 @final
 class ctx:
@@ -482,18 +442,19 @@ class ctx:
         """
 
         output_stream = AsyncStream[Element]()
+        stream_scope: ScopeContext = ctx.scope("stream")
 
-        @ctx.scope("stream")
         async def stream() -> None:
-            try:
-                async for result in source(*args, **kwargs):
-                    await output_stream.send(result)
+            async with stream_scope:
+                try:
+                    async for result in source(*args, **kwargs):
+                        await output_stream.send(result)
 
-            except BaseException as exc:
-                output_stream.finish(exception=exc)
+                except BaseException as exc:
+                    output_stream.finish(exception=exc)
 
-            else:
-                output_stream.finish()
+                else:
+                    output_stream.finish()
 
         TaskGroupContext.run(stream)
         return output_stream

haiway/context/observability.py

@@ -11,7 +11,6 @@ from typing import Any, Protocol, Self, final, runtime_checkable
 from uuid import UUID, uuid4
 
 from haiway.context.identifier import ScopeIdentifier
-from haiway.state import State
 from haiway.types import Missing
 from haiway.utils.formatting import format_str
 
@@ -166,7 +165,7 @@ class ObservabilityScopeEntering(Protocol):
     Implementations should record when execution enters a new scope.
     """
 
-    def __call__[Metric: State](
+    def __call__(
         self,
         scope: ScopeIdentifier,
         /,
@@ -182,7 +181,7 @@ class ObservabilityScopeExiting(Protocol):
     including any exceptions that caused the exit.
     """
 
-    def __call__[Metric: State](
+    def __call__(
         self,
         scope: ScopeIdentifier,
         /,

haiway/context/state.py

@@ -25,7 +25,10 @@ class ScopeState:
     This class is immutable after initialization.
     """
 
-    __slots__ = ("_lock", "_state")
+    __slots__ = (
+        "_lock",
+        "_state",
+    )
 
     def __init__(
         self,
@@ -271,7 +274,10 @@ class StateContext:
             If state not found and default not provided or instantiation fails
         """
         try:
-            return cls._context.get().state(state, default=default)
+            return cls._context.get().state(
+                state,
+                default=default,
+            )
 
         except LookupError as exc:
             raise MissingContext("StateContext requested but not defined!") from exc

haiway/context/types.py

@@ -13,8 +13,6 @@ class MissingContext(Exception):
     identifiers when no context has been established.
     """
 
-    pass
-
 
 class MissingState(Exception):
     """
@@ -24,5 +22,3 @@ class MissingState(Exception):
     that is not present in the current context and cannot be automatically
     created (either because no default was provided or instantiation failed).
     """
-
-    pass

haiway/helpers/__init__.py

@@ -1,6 +1,6 @@
 from haiway.helpers.asynchrony import asynchronous
 from haiway.helpers.caching import CacheMakeKey, CacheRead, CacheWrite, cache
-from haiway.helpers.concurrent import process_concurrently
+from haiway.helpers.concurrent import execute_concurrently, process_concurrently
 from haiway.helpers.files import File, FileAccess
 from haiway.helpers.observability import LoggerObservability
 from haiway.helpers.retries import retry
@@ -17,6 +17,7 @@ __all__ = (
     "LoggerObservability",
     "asynchronous",
     "cache",
+    "execute_concurrently",
     "process_concurrently",
     "retry",
     "throttle",

haiway/helpers/concurrent.py

@@ -1,11 +1,22 @@
-from asyncio import FIRST_COMPLETED, CancelledError, Task, wait
-from collections.abc import AsyncIterator, Callable, Coroutine
-from concurrent.futures import ALL_COMPLETED
-from typing import Any
+from asyncio import ALL_COMPLETED, FIRST_COMPLETED, CancelledError, Task, wait
+from collections.abc import (
+    AsyncIterable,
+    AsyncIterator,
+    Callable,
+    Collection,
+    Coroutine,
+    MutableSequence,
+    Sequence,
+)
+from typing import Any, Literal, overload
 
 from haiway.context import ctx
 
-__all__ = ("process_concurrently",)
+__all__ = (
+    "execute_concurrently",
+    "process_concurrently",
+    "stream_concurrently",
+)
 
 
 async def process_concurrently[Element](  # noqa: C901, PLR0912
@@ -18,20 +29,52 @@ async def process_concurrently[Element](  # noqa: C901, PLR0912
 ) -> None:
     """Process elements from an async iterator concurrently.
 
+    Consumes elements from an async iterator and processes them using the provided
+    handler function. Processing happens concurrently with a configurable maximum
+    number of concurrent tasks. Elements are processed as they become available,
+    maintaining the specified concurrency limit.
+
+    The function continues until the source iterator is exhausted. If the function
+    is cancelled, all running tasks are also cancelled. When ignore_exceptions is
+    False, the first exception encountered will stop processing and propagate.
+
     Parameters
     ----------
-    source: AsyncIterator[Element]
-        An async iterator providing elements to process.
+    source : AsyncIterator[Element]
+        An async iterator providing elements to process. Elements are consumed
+        one at a time as processing slots become available.
+    handler : Callable[[Element], Coroutine[Any, Any, None]]
+        A coroutine function that processes each element. The handler should
+        not return a value (returns None).
+    concurrent_tasks : int, default=2
+        Maximum number of concurrent tasks. Must be greater than 0. Higher
+        values allow more parallelism but consume more resources.
+    ignore_exceptions : bool, default=False
+        If True, exceptions from handler tasks will be logged but not propagated,
+        allowing processing to continue. If False, the first exception stops
+        all processing.
 
-    handler: Callable[[Element], Coroutine[Any, Any, None]]
-        A coroutine function that processes each element.
+    Raises
+    ------
+    CancelledError
+        If the function is cancelled, propagated after cancelling all running tasks.
+    Exception
+        Any exception raised by handler tasks when ignore_exceptions is False.
 
-    concurrent_tasks: int
-        Maximum number of concurrent tasks (must be > 0), default is 2.
-
-    ignore_exceptions: bool
-        If True, exceptions from tasks will be logged but not propagated,
-         default is False.
+    Examples
+    --------
+    >>> async def process_item(item: str) -> None:
+    ...     await some_async_operation(item)
+    ...
+    >>> async def items() -> AsyncIterator[str]:
+    ...     for i in range(10):
+    ...         yield f"item_{i}"
+    ...
+    >>> await process_concurrently(
+    ...     items(),
+    ...     process_item,
+    ...     concurrent_tasks=5
+    ... )
 
     """
     assert concurrent_tasks > 0  # nosec: B101
@@ -83,3 +126,269 @@ async def process_concurrently[Element](  # noqa: C901, PLR0912
                         f"Concurrent processing error - {type(exc)}: {exc}",
                         exception=exc,
                     )
+
+
+@overload
+async def execute_concurrently[Element, Result](
+    source: Collection[Element],
+    /,
+    handler: Callable[[Element], Coroutine[Any, Any, Result]],
+    *,
+    concurrent_tasks: int = 2,
+) -> Sequence[Result]: ...
+
+
+@overload
+async def execute_concurrently[Element, Result](
+    source: Collection[Element],
+    /,
+    handler: Callable[[Element], Coroutine[Any, Any, Result]],
+    *,
+    concurrent_tasks: int = 2,
+    return_exceptions: Literal[True],
+) -> Sequence[Result | BaseException]: ...
+
+
+async def execute_concurrently[Element, Result](  # noqa: C901
+    source: Collection[Element],
+    /,
+    handler: Callable[[Element], Coroutine[Any, Any, Result]],
+    *,
+    concurrent_tasks: int = 2,
+    return_exceptions: bool = False,
+) -> Sequence[Result | BaseException] | Sequence[Result]:
+    """Execute handler for each element from a collection concurrently.
+
+    Processes all elements from a collection using the provided handler function,
+    executing multiple handlers concurrently up to the specified limit. Results
+    are collected and returned in the same order as the input elements.
+
+    Unlike `process_concurrently`, this function:
+    - Works with collections (known size) rather than async iterators
+    - Returns results from each handler invocation
+    - Preserves the order of results to match input order
+
+    The function ensures all tasks complete before returning. If cancelled,
+    all running tasks are cancelled before propagating the cancellation.
+
+    Parameters
+    ----------
+    source : Collection[Element]
+        A collection of elements to process. The collection size determines
+        the result sequence length.
+    handler : Callable[[Element], Coroutine[Any, Any, Result]]
+        A coroutine function that processes each element and returns a result.
+    concurrent_tasks : int, default=2
+        Maximum number of concurrent tasks. Must be greater than 0. Higher
+        values allow more parallelism but consume more resources.
+    return_exceptions : bool, default=False
+        If True, exceptions from handler tasks are included in the results
+        as BaseException instances. If False, the first exception stops
+        processing and is raised.
+
+    Returns
+    -------
+    Sequence[Result] or Sequence[Result | BaseException]
+        Results from each handler invocation, in the same order as input elements.
+        If return_exceptions is True, failed tasks return BaseException instances.
+
+    Raises
+    ------
+    CancelledError
+        If the function is cancelled, propagated after cancelling all running tasks.
+    Exception
+        Any exception raised by handler tasks when return_exceptions is False.
+
+    Examples
+    --------
+    >>> async def fetch_data(url: str) -> dict:
+    ...     return await http_client.get(url)
+    ...
+    >>> urls = ["http://api.example.com/1", "http://api.example.com/2"]
+    >>> results = await execute_concurrently(
+    ...     urls,
+    ...     fetch_data,
+    ...     concurrent_tasks=10
+    ... )
+    >>> # results[0] corresponds to urls[0], results[1] to urls[1], etc.
+
+    >>> # With exception handling
+    >>> results = await execute_concurrently(
+    ...     urls,
+    ...     fetch_data,
+    ...     concurrent_tasks=10,
+    ...     return_exceptions=True
+    ... )
+    >>> for url, result in zip(urls, results):
+    ...     if isinstance(result, BaseException):
+    ...         print(f"Failed to fetch {url}: {result}")
+    ...     else:
+    ...         print(f"Got data from {url}")
+
+    """
+    assert concurrent_tasks > 0  # nosec: B101
+    running: set[Task[Result]] = set()
+    results: MutableSequence[Task[Result]] = []
+    try:
+        for element in source:
+            task: Task[Result] = ctx.spawn(handler, element)
+            results.append(task)
+            running.add(task)
+            if len(running) < concurrent_tasks:
+                continue  # keep spawning tasks
+
+            completed, running = await wait(
+                running,
+                return_when=FIRST_COMPLETED,
+            )
+
+            for task in completed:
+                if exc := task.exception():
+                    if not return_exceptions:
+                        raise exc
+
+                    ctx.log_error(
+                        f"Concurrent execution error - {type(exc)}: {exc}",
+                        exception=exc,
+                    )
+
+    except CancelledError as exc:
+        # Cancel all running tasks
+        for task in running:
+            task.cancel()
+
+        raise exc
+
+    finally:
+        if running:
+            completed, _ = await wait(
+                running,
+                return_when=ALL_COMPLETED,
+            )
+            for task in completed:
+                if exc := task.exception():
+                    if not return_exceptions:
+                        raise exc
+
+                    ctx.log_error(
+                        f"Concurrent execution error - {type(exc)}: {exc}",
+                        exception=exc,
+                    )
+
+    return [result.exception() or result.result() for result in results]
+
+
+async def stream_concurrently[ElementA, ElementB](  # noqa: C901
+    source_a: AsyncIterator[ElementA],
+    source_b: AsyncIterator[ElementB],
+    /,
+) -> AsyncIterable[ElementA | ElementB]:
+    """Merge streams from two async iterators processed concurrently.
+
+    Concurrently consumes elements from two async iterators and yields them
+    as they become available. Elements from both sources are interleaved based
+    on which iterator produces them first. The function continues until both
+    iterators are exhausted.
+
+    This is useful for combining multiple async data sources into a single
+    stream while maintaining concurrency. Each iterator is polled independently,
+    and whichever has data available first will have its element yielded.
+
+    Parameters
+    ----------
+    source_a : AsyncIterator[ElementA]
+        First async iterator to consume from.
+    source_b : AsyncIterator[ElementB]
+        Second async iterator to consume from.
+
+    Yields
+    ------
+    ElementA | ElementB
+        Elements from either source as they become available. The order
+        depends on which iterator produces elements first.
+
+    Raises
+    ------
+    CancelledError
+        If the async generator is cancelled, both source tasks are cancelled
+        before propagating the cancellation.
+    Exception
+        Any exception raised by either source iterator.
+
+    Examples
+    --------
+    >>> async def numbers() -> AsyncIterator[int]:
+    ...     for i in range(5):
+    ...         await asyncio.sleep(0.1)
+    ...         yield i
+    ...
+    >>> async def letters() -> AsyncIterator[str]:
+    ...     for c in "abcde":
+    ...         await asyncio.sleep(0.15)
+    ...         yield c
+    ...
+    >>> async for item in stream_concurrently(numbers(), letters()):
+    ...     print(item)  # Prints interleaved numbers and letters
+
+    Notes
+    -----
+    The function maintains exactly one pending task per iterator at all times,
+    ensuring efficient resource usage while maximizing throughput from both
+    sources.
+
+    """
+
+    async def next_a() -> ElementA:
+        return await anext(source_a)
+
+    async def next_b() -> ElementB:
+        return await anext(source_b)
+
+    task_a: Task[ElementA] = ctx.spawn(next_a)
+    task_b: Task[ElementB] = ctx.spawn(next_b)
+
+    try:
+        while not (  # Continue until both iterators are exhausted
+            task_a.done()
+            and task_b.done()
+            and isinstance(task_a.exception(), StopAsyncIteration)
+            and isinstance(task_b.exception(), StopAsyncIteration)
+        ):
+            # Wait for at least one task to complete
+            done, _ = await wait(
+                {task_a, task_b},
+                return_when=FIRST_COMPLETED,
+            )
+
+            # Process completed tasks
+            for task in done:
+                if task is task_a:
+                    exc: BaseException | None = task.exception()
+                    if exc is None:
+                        yield task.result()
+                        task_a = ctx.spawn(next_a)
+
+                    elif not isinstance(exc, StopAsyncIteration):
+                        raise exc
+                    # If StopAsyncIteration, don't respawn task_a
+
+                elif task is task_b:
+                    exc: BaseException | None = task.exception()
+                    if exc is None:
+                        yield task.result()
+                        task_b = ctx.spawn(next_b)
+
+                    elif not isinstance(exc, StopAsyncIteration):
+                        raise exc
+                    # If StopAsyncIteration, don't respawn task_b
+
+    except CancelledError as exc:
+        # Cancel all running tasks
+        task_a.cancel()
+        task_b.cancel()
+        raise exc
+
+    finally:
+        # Ensure cleanup of any remaining tasks
+        for task in (task_a, task_b):
+            task.cancel()

haiway/helpers/retries.py

@@ -207,7 +207,7 @@ def _wrap_sync[**Args, Result](
                         case float(strict):
                             sleep_sync(strict)
 
-                        case make_delay:  # type: Callable[[], float]
+                        case make_delay:
                             sleep_sync(make_delay(attempt, exc))  # pyright: ignore[reportCallIssue, reportUnknownArgumentType]
 
                 else:
@@ -253,7 +253,7 @@ def _wrap_async[**Args, Result](
                         case float(strict):
                             await sleep(strict)
 
-                        case make_delay:  # type: Callable[[], float]
+                        case make_delay:
                             await sleep(make_delay(attempt, exc))  # pyright: ignore[reportCallIssue, reportUnknownArgumentType]
 
                 else:

haiway/state/requirement.py

@@ -100,7 +100,7 @@ class AttributeRequirement[Root]:
         ), "Prepare attribute path by using Self._.path.to.property or explicitly"
 
         def check_text_match(root: Root) -> None:
-            checked: Any = cast(AttributePath[Root, str], path)(root)
+            checked: Any = path(root)
             if not isinstance(checked, str):
                 raise ValueError(
                     f"Attribute value must be a string for like operation, got {type(checked)}"

haiway/types/__init__.py

@@ -1,5 +1,5 @@
 from haiway.types.default import Default, DefaultValue
-from haiway.types.missing import MISSING, Missing, is_missing, not_missing, when_missing
+from haiway.types.missing import MISSING, Missing, is_missing, not_missing, unwrap_missing
 
 __all__ = (
     "MISSING",
@@ -8,5 +8,5 @@ __all__ = (
     "Missing",
     "is_missing",
     "not_missing",
-    "when_missing",
+    "unwrap_missing",
 )

haiway/types/missing.py

@@ -1,11 +1,12 @@
-from typing import Any, Final, TypeGuard, cast, final
+from collections.abc import Callable
+from typing import Any, Final, TypeGuard, cast, final, overload
 
 __all__ = (
     "MISSING",
     "Missing",
     "is_missing",
     "not_missing",
-    "when_missing",
+    "unwrap_missing",
 )
 
 
@@ -147,11 +148,12 @@ def not_missing[Value](
     return check is not MISSING
 
 
-def when_missing[Value](
+@overload
+def unwrap_missing[Value](
     check: Value | Missing,
     /,
     *,
-    value: Value,
+    default: Value,
 ) -> Value:
     """
     Substitute a default value when the input is MISSING.
@@ -162,10 +164,10 @@ def when_missing[Value](
 
     Parameters
     ----------
-    check : Value | Missing
-        The value to check
-    value : Value
-        The default value to use if check is MISSING
+    value : Value | Missing
+        The value to check.
+    default : Value
+        The default value to use if check is MISSING.
 
     Returns
     -------
@@ -175,13 +177,65 @@ def when_missing[Value](
     Examples
     --------
     ```python
-    result = when_missing(optional_value, value=default_value)
+    result = unwrap_missing(optional_value, default=default_value)
     # result will be default_value if optional_value is MISSING
     # otherwise it will be optional_value
     ```
     """
-    if check is MISSING:
-        return value
+
+
+@overload
+def unwrap_missing[Value, Mapped](
+    value: Value | Missing,
+    /,
+    *,
+    default: Mapped,
+    mapping: Callable[[Value], Mapped],
+) -> Value | Mapped:
+    """
+    Substitute a default value when the input is MISSING or map the original.
+
+    This function provides a convenient way to replace the MISSING
+    sentinel with a default value, similar to how the or operator
+    works with None but specifically for the MISSING sentinel.
+    Original value is mapped using provided function when not missing.
+
+    Parameters
+    ----------
+    value : Value | Missing
+        The value to check.
+    default : Mapped
+        The default value to use if check is MISSING.
+    mapping: Callable[[Value], Result] | None = None
+        Mapping to apply to the value.
+
+    Returns
+    -------
+    Mapped
+        The original value with mapping applied if not MISSING, otherwise the provided default.
+
+    Examples
+    --------
+    ```python
+    result = unwrap_missing(optional_value, default=default_value, mapping=value_map)
+    # result will be default_value if optional_value is MISSING
+    # otherwise it will be optional_value after mapping
+    ```
+    """
+
+
+def unwrap_missing[Value, Mapped](
+    value: Value | Missing,
+    /,
+    *,
+    default: Value | Mapped,
+    mapping: Callable[[Value], Mapped] | None = None,
+) -> Value | Mapped:
+    if value is MISSING:
+        return default
+
+    elif mapping is not None:
+        return mapping(cast(Value, value))
 
     else:
-        return cast(Value, check)
+        return cast(Value, value)

haiway/utils/__init__.py

@@ -1,6 +1,7 @@
 from haiway.utils.always import always, async_always
 from haiway.utils.collections import as_dict, as_list, as_set, as_tuple, without_missing
 from haiway.utils.env import (
+    getenv,
     getenv_base64,
     getenv_bool,
     getenv_float,
@@ -26,6 +27,7 @@ __all__ = (
     "async_always",
     "async_noop",
     "format_str",
+    "getenv",
     "getenv_base64",
     "getenv_bool",
     "getenv_float",

haiway/utils/collections.py

@@ -50,7 +50,7 @@ def as_list[T](
     if collection is None:
         return None
 
-    if isinstance(collection, list):
+    elif isinstance(collection, list):
         return collection
 
     else:
@@ -95,7 +95,7 @@ def as_tuple[T](
     if collection is None:
         return None
 
-    if isinstance(collection, tuple):
+    elif isinstance(collection, tuple):
         return collection
 
     else:
@@ -140,7 +140,7 @@ def as_set[T](
     if collection is None:
         return None
 
-    if isinstance(collection, set):
+    elif isinstance(collection, set):
         return collection
 
     else:
@@ -185,7 +185,7 @@ def as_dict[K, V](
     if collection is None:
         return None
 
-    if isinstance(collection, dict):
+    elif isinstance(collection, dict):
         return collection
 
     else:

haiway/utils/env.py

@@ -1,9 +1,11 @@
 from base64 import b64decode
 from collections.abc import Callable
-from os import environ, getenv
+from os import environ
+from os import getenv as os_getenv
 from typing import Literal, overload
 
 __all__ = (
+    "getenv",
     "getenv_base64",
     "getenv_bool",
     "getenv_float",
@@ -13,6 +15,83 @@ __all__ = (
 )
 
 
+@overload
+def getenv[Value](
+    key: str,
+    /,
+    mapping: Callable[[str], Value],
+) -> Value | None: ...
+
+
+@overload
+def getenv[Value](
+    key: str,
+    /,
+    mapping: Callable[[str], Value],
+    *,
+    default: Value,
+) -> Value: ...
+
+
+@overload
+def getenv[Value](
+    key: str,
+    /,
+    mapping: Callable[[str], Value],
+    *,
+    required: Literal[True],
+) -> Value: ...
+
+
+def getenv[Value](
+    key: str,
+    /,
+    mapping: Callable[[str], Value],
+    *,
+    default: Value | None = None,
+    required: bool = False,
+) -> Value | None:
+    """
+    Get a value from an environment variable and transforms.
+
+    Uses provided transformation method to deliver custom data type from env variable.
+
+    Parameters
+    ----------
+    key : str
+        The environment variable name to retrieve
+    mapping : Callable[[str], Value]
+        Custom transformation of env value to desired value type.
+    default : Value | None, optional
+        Value to return if the environment variable is not set
+    required : bool, default=False
+        If True and the environment variable is not set and no default is provided,
+        raises a ValueError
+
+    Returns
+    -------
+    Value | None
+        The value from the environment variable, or the default value
+
+    Raises
+    ------
+    ValueError
+        If required=True, the environment variable is not set, and no default is provided
+    """
+    if value := os_getenv(key=key):
+        try:
+            return mapping(value)
+
+        except Exception as exc:
+            raise ValueError(f"Failed to transform environment value `{key}`: {value}") from exc
+
+    elif required and default is None:
+        raise ValueError(f"Required environment value `{key}` is missing!")
+
+    else:
+        return default
+
+
 @overload
 def getenv_bool(
     key: str,
@@ -70,7 +149,7 @@ def getenv_bool(
     ValueError
         If required=True, the environment variable is not set, and no default is provided
     """
-    if value := getenv(key=key):
+    if value := os_getenv(key=key):
         return value.lower() in ("true", "1", "t")
 
     elif required and default is None:
@@ -135,7 +214,7 @@ def getenv_int(
         If the environment variable is set but cannot be converted to an integer,
         or if required=True, the environment variable is not set, and no default is provided
     """
-    if value := getenv(key=key):
+    if value := os_getenv(key=key):
         try:
             return int(value)
 
@@ -204,7 +283,7 @@ def getenv_float(
         If the environment variable is set but cannot be converted to a float,
         or if required=True, the environment variable is not set, and no default is provided
     """
-    if value := getenv(key=key):
+    if value := os_getenv(key=key):
         try:
             return float(value)
 
@@ -272,7 +351,7 @@ def getenv_str(
     ValueError
         If required=True, the environment variable is not set, and no default is provided
     """
-    if value := getenv(key=key):
+    if value := os_getenv(key=key):
         return value
 
     elif required and default is None:
@@ -344,7 +423,7 @@ def getenv_base64[Value](
     ValueError
         If required=True, the environment variable is not set, and no default is provided
     """
-    if value := getenv(key=key):
+    if value := os_getenv(key=key):
         return decoder(b64decode(value))
 
     elif required and default is None:
@@ -395,7 +474,7 @@ def load_env(
                 idx: int  # find where key ends
                 for element in enumerate(line):
                     if element[1] == "=":
-                        idx: int = element[0]
+                        idx = element[0]
                         break
                 else:  # ignore keys without assignment
                     continue

haiway/utils/formatting.py

@@ -47,7 +47,7 @@ def format_str(  # noqa: PLR0911
 
     # check for bytes
     elif isinstance(value, bytes):
-        return f"b'{value}'"
+        return f"b'{value!r}'"
 
     # try unpack mapping
     elif isinstance(value, Mapping):

haiway/utils/logs.py

@@ -7,6 +7,7 @@ __all__ = ("setup_logging",)
 
 def setup_logging(
     *loggers: str,
+    time: bool = True,
     debug: bool = getenv_bool("DEBUG_LOGGING", __debug__),
 ) -> None:
     """\
@@ -16,6 +17,10 @@ def setup_logging(
     ----------
     *loggers: str
         names of additional loggers to configure.
+    time: bool = True
+        include timestamps in logs.
+    debug: bool = __debug__
+        include debug logs.
 
     NOTE: this function should be run only once on application start
     """
@@ -28,6 +33,10 @@ def setup_logging(
                 "standard": {
                     "format": "%(asctime)s [%(levelname)-4s] [%(name)s] %(message)s",
                     "datefmt": "%d/%b/%Y:%H:%M:%S +0000",
+                }
+                if time
+                else {
+                    "format": "[%(levelname)-4s] [%(name)s] %(message)s",
                 },
             },
             "handlers": {

{haiway-0.23.2.dist-info → haiway-0.24.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haiway
-Version: 0.23.2
+Version: 0.24.1
 Summary: Framework for dependency injection and state management within structured concurrency model.
 Project-URL: Homepage, https://miquido.com
 Project-URL: Repository, https://github.com/miquido/haiway.git

{haiway-0.23.2.dist-info → haiway-0.24.1.dist-info}/RECORD

@@ -1,20 +1,20 @@
-haiway/__init__.py,sha256=FiOAMHHawyGk9FfZU-1UflT8nmwu9J0CrG2QwrJGccw,1917
+haiway/__init__.py,sha256=E-IUVgLuTkaj-6hUzuqOwef_98rDXmGeE79waiYrFfQ,2001
 haiway/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 haiway/context/__init__.py,sha256=1N_SvdPkTfIZDZybm3y0rY2dGrDLWTm0ryzUz2XD4f8,1174
-haiway/context/access.py,sha256=QCabyZtqqJjGTgAod1ZC3Fz3IfPsyurLo_i68RnCm4Q,25736
+haiway/context/access.py,sha256=lsK6RnSjaGRgdOprtLCz4vyw5KqMtbGs0uFXnJWc_j4,24446
 haiway/context/disposables.py,sha256=AP9eZ0BPHJZfjrrfrjSzr4jONMKkR6YmhjOfnBp37so,11504
 haiway/context/identifier.py,sha256=dCCwLneXJzH__ZWFlGRUHvoCmbT4lM0QVbyokYIbUHg,5255
-haiway/context/observability.py,sha256=E-TDqqJ_EnHkFTspEjyA61O0iIbEev15YUn5d3yHhvU,23692
-haiway/context/state.py,sha256=DuCtI0rMLWYbnBGXxpkbQgrX4aAftGkuK8XSd1JtdVc,11912
+haiway/context/observability.py,sha256=JGiBScElJMgYDxi1PoIx7K98PpCXTVV3WY-x8abLx9A,23631
+haiway/context/state.py,sha256=lzkVVdTMYn-Bfon2aCPMx6vRScrbOqY2f_DuS5aMx0s,11982
 haiway/context/tasks.py,sha256=pScFgeiyrXSJRDFZiYbBLi3k_DHkSlhB8rgAnYtgyrU,4925
-haiway/context/types.py,sha256=VDWXJySihfvSSPzY09PaGk6j5S9HgmAUboBGCZ8o_4k,766
-haiway/helpers/__init__.py,sha256=PTWpavAveEB2V9Au1QuaRZwh3Rkb1bQSNvo_mxuGqlE,721
+haiway/context/types.py,sha256=LoW8238TTdbUgmxyHDi0LVc8M8ZwTHLWKkAPttTsTeg,746
+haiway/helpers/__init__.py,sha256=K_OABDzXcCURHNDDBLmZleKP1pDCOxsG30c4zkfRnIE,771
 haiway/helpers/asynchrony.py,sha256=Ddj8UdXhVczAbAC-rLpyhWa4RJ_W2Eolo45Veorq7_4,5362
 haiway/helpers/caching.py,sha256=BqgcUGQSAmXsuLi5V8EwlZzuGyutHOn1V4k7BHsGKeg,14347
-haiway/helpers/concurrent.py,sha256=xGMcan_tiETAHQs1YFmgYpA4YMFo6rIbFKvNeMlRFG8,2551
+haiway/helpers/concurrent.py,sha256=P8YXukabb29iQhSKTECVaThPhzTX17JDdKrWAjHy4d4,13105
 haiway/helpers/files.py,sha256=L6vXd8gdgWx5jPL8azloU8IGoFq2xnxjMc4ufz-gdl4,11650
 haiway/helpers/observability.py,sha256=jCJzOPJ5E3RKJsbbGRR1O-mZydaHNIGkIpppOH7nFBA,11012
-haiway/helpers/retries.py,sha256=52LA85HejTiSmCmTMAA9c8oUqD_VnhbTn1b3kwlU52c,9032
+haiway/helpers/retries.py,sha256=OH__I9e-PUFxcSwuQLIzJ9F1MwXgbz1Ur4jEjJiOmjQ,8974
 haiway/helpers/throttling.py,sha256=KBWUSHdKVMC5_nRMmmoPNwfp-3AcerQ6OczJa9gNLM0,5796
 haiway/helpers/timeouting.py,sha256=GQ8-btb36f0Jq7TnorAPYXyKScNmf0nxHXCYxqGl-o8,3949
 haiway/helpers/tracing.py,sha256=NHipA5UlngwFcAaKhXg1jTuJ-ti6AqSNxE7u7-92vWo,5409
@@ -23,23 +23,23 @@ haiway/opentelemetry/observability.py,sha256=akGAPX6_958BxCfzlLnoDJHPtEvztdMnfMA
 haiway/state/__init__.py,sha256=AaMqlMhO4zKS_XNevy3A7BHh5PxmguA-Sk_FnaNDY1Q,355
 haiway/state/attributes.py,sha256=sububiFP23aBB8RGk6OvTUp7BEY6S0kER_uHC09yins,26733
 haiway/state/path.py,sha256=bv5MI3HmUyku78k0Sz5lc7Q_Bay53iom1l3AL5KZs-4,32143
-haiway/state/requirement.py,sha256=zNTx7s8FiMZKu9EV3T6f1SOJpR4SC9X5hhL--PVWPCY,15641
+haiway/state/requirement.py,sha256=HjoABPQ2r-uo6xr5s4q9nDPGUMde5X_JCIZlYqTts5s,15609
 haiway/state/structure.py,sha256=CTf1l0TyKA7vkVDqA9RMdxaOVNSHwQduN2jb6H015hg,23798
 haiway/state/validation.py,sha256=eDOZKRrfd-dmdbqoHcLacdCVKmVCEpwt239EG6ljNF8,23557
-haiway/types/__init__.py,sha256=jFr5kf36SvVGdgngvik6_HzG8YNa3NVsdDDSqxVuGm4,281
+haiway/types/__init__.py,sha256=BQKjbPZQej4DQsD_y4linn4rQMWdfaahKW-t-gapSjs,285
 haiway/types/default.py,sha256=59chcOaoGqI2to08RamCCLluimfYbJp5xbYl3fWaLrM,4153
-haiway/types/missing.py,sha256=OfiyYUnzTk3arKWu8S6ORCEYGvcRu_mdL4j1ExdSvgI,4256
-haiway/utils/__init__.py,sha256=Zs4mJnoRL_4ssGSZqvCFuhllxMDww_8-McsI2xB0mug,917
+haiway/types/missing.py,sha256=V9FWUgAWUsmFuSXc57MORQOVh2wO2vlF1qYopmcEA2A,5760
+haiway/utils/__init__.py,sha256=FkY6EUwkZmb2Z8Z5UpMW3i9J0l9JoowgrULy-s_6X5M,943
 haiway/utils/always.py,sha256=dd6jDQ1j4DpJjTKO1J2Tv5xS8X1LnMC4kQ0D7DtKUvw,1230
-haiway/utils/collections.py,sha256=gF5tC1EaEzBfPpXrHqR0mZh8e4pRwEPSVactvfN-30M,4737
-haiway/utils/env.py,sha256=Z0uHJDFegvgzy-gM-f0uPMha9_1ldUglrD5SKNJsvYE,9445
-haiway/utils/formatting.py,sha256=jgSIGalGUBZVo2ziiNC5Y7vBYbAEwPugOiwEOrNFTcI,4039
-haiway/utils/logs.py,sha256=NuwoqKQnMNi1FMIA91cVFnAPefUFeg3UIT50IOl3sJk,1571
+haiway/utils/collections.py,sha256=W2K5haxogHdngEw2JF_qEUr0O28dhirdy2kzSbeW4wE,4745
+haiway/utils/env.py,sha256=mCMveOWwOphgp8Ir5NEpZQFENyG7MBOoLlUeHzzIYEQ,11262
+haiway/utils/formatting.py,sha256=SQ-gjBa2nxg_UhIP0AhNXIRwcDRei2ZZUiCLMiYLYUo,4041
+haiway/utils/logs.py,sha256=-MVyxVGU892yJKFh0bkshW_NEg1aiJt9wv2cUY2w98o,1847
 haiway/utils/mimic.py,sha256=xaZiUKp096QFfdSw7cNIKEWt2UIS7vf880KF54gny38,1831
 haiway/utils/noop.py,sha256=U8ocfoCgt-pY0owJDPtrRrj53cabeIXH9qCKWMQnoRk,1336
 haiway/utils/queue.py,sha256=6v2u3pA6A44IuCCTOjmCt3yLyOcm7PCRnrIGo25j-1o,6402
 haiway/utils/stream.py,sha256=lXaeveTY0-AYG5xVzcQYaiC6SUD5fUtHoMXiQcrQAAM,5723
-haiway-0.23.2.dist-info/METADATA,sha256=Q7kt1rIp4ag9Losks7W_ltiQGWVP_tWlXiaOzEJW5V8,4919
-haiway-0.23.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-haiway-0.23.2.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
-haiway-0.23.2.dist-info/RECORD,,
+haiway-0.24.1.dist-info/METADATA,sha256=Wkbm7ERtjanGClRRM6m8TJi2m5bA8hujWwekCvdjfiQ,4919
+haiway-0.24.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+haiway-0.24.1.dist-info/licenses/LICENSE,sha256=3phcpHVNBP8jsi77gOO0E7rgKeDeu99Pi7DSnK9YHoQ,1069
+haiway-0.24.1.dist-info/RECORD,,