haiway 0.19.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

haiway/utils/collections.py

@@ -36,14 +36,15 @@ def as_list[T](
     Parameters
     ----------
     collection : Iterable[T] | None
-        The input to be converted.
+        The input collection to be converted to a list.
+        If None is provided, None is returned.
 
     Returns
     -------
     list[T] | None
-        A new list containing all elements of the input,\
-         or the original list if it was already one.
-        None if no value was provided.
+        A new list containing all elements of the input collection,
+        or the original list if it was already one.
+        Returns None if None was provided.
     """
 
     if collection is None:
@@ -79,15 +80,16 @@ def as_tuple[T](
 
     Parameters
     ----------
-    collection : Sequence[T] | None
-        The input to be converted.
+    collection : Iterable[T] | None
+        The input collection to be converted to a tuple.
+        If None is provided, None is returned.
 
     Returns
     -------
-    tuple[T] | None
-        A new tuple containing all elements of the input,\
-         or the original tuple if it was already one.
-        None if no value was provided.
+    tuple[T, ...] | None
+        A new tuple containing all elements of the input collection,
+        or the original tuple if it was already one.
+        Returns None if None was provided.
     """
 
     if collection is None:
@@ -123,15 +125,16 @@ def as_set[T](
 
     Parameters
     ----------
-    collection : Set[T]
-        The input collection to be converted.
+    collection : Set[T] | None
+        The input collection to be converted to a set.
+        If None is provided, None is returned.
 
     Returns
     -------
-    set[T]
-        A new set containing all elements of the input collection,\
-         or the original set if it was already one.
-        None if no value was provided.
+    set[T] | None
+        A new set containing all elements of the input collection,
+        or the original set if it was already one.
+        Returns None if None was provided.
     """
 
     if collection is None:
@@ -167,15 +170,16 @@ def as_dict[K, V](
 
     Parameters
     ----------
-    collection : Mapping[K, V]
-        The input collection to be converted.
+    collection : Mapping[K, V] | None
+        The input collection to be converted to a dict.
+        If None is provided, None is returned.
 
     Returns
     -------
-    dict[K, V]
-        A new dict containing all elements of the input collection,\
-         or the original dict if it was already one.
-        None if no value was provided.
+    dict[K, V] | None
+        A new dict containing all elements of the input collection,
+        or the original dict if it was already one.
+        Returns None if None was provided.
     """
 
     if collection is None:
@@ -211,17 +215,21 @@ def without_missing[T: Mapping[str, Any]](
     typed: type[T] | None = None,
 ) -> T | Mapping[str, Any]:
     """
-    Strip items with missing values.
+    Create a new mapping without any items that have MISSING values.
 
     Parameters
     ----------
-    mapping : Mapping[K, V]
-        The input mapping to be stripped.
+    mapping : Mapping[str, Any]
+        The input mapping to be filtered.
+    typed : type[T] | None, default=None
+        Optional type to cast the result to. If provided, the result will be
+        cast to this type before returning.
 
     Returns
     -------
-    T | dict[str, Any]
-        A new mapping containing all items of the input mapping,\
-         except items with missing values.
+    T | Mapping[str, Any]
+        A new mapping containing all items of the input mapping,
+        except items with MISSING values. If typed is provided,
+        the result is cast to that type.
     """
     return cast(T, {key: value for key, value in mapping.items() if value is not MISSING})

haiway/utils/env.py

@@ -44,6 +44,32 @@ def getenv_bool(
     *,
     required: bool = False,
 ) -> bool | None:
+    """
+    Get a boolean value from an environment variable.
+
+    Interprets 'true', '1', and 't' (case-insensitive) as True,
+    any other value as False.
+
+    Parameters
+    ----------
+    key : str
+        The environment variable name to retrieve
+    default : bool | 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
+    -------
+    bool | None
+        The boolean 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 := getenv(key=key):
         return value.lower() in ("true", "1", "t")
 
@@ -85,6 +111,30 @@ def getenv_int(
     *,
     required: bool = False,
 ) -> int | None:
+    """
+    Get an integer value from an environment variable.
+
+    Parameters
+    ----------
+    key : str
+        The environment variable name to retrieve
+    default : int | 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
+    -------
+    int | None
+        The integer value from the environment variable, or the default value
+
+    Raises
+    ------
+    ValueError
+        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):
         try:
             return int(value)
@@ -130,6 +180,30 @@ def getenv_float(
     *,
     required: bool = False,
 ) -> float | None:
+    """
+    Get a float value from an environment variable.
+
+    Parameters
+    ----------
+    key : str
+        The environment variable name to retrieve
+    default : float | 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
+    -------
+    float | None
+        The float value from the environment variable, or the default value
+
+    Raises
+    ------
+    ValueError
+        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):
         try:
             return float(value)
@@ -175,6 +249,29 @@ def getenv_str(
     *,
     required: bool = False,
 ) -> str | None:
+    """
+    Get a string value from an environment variable.
+
+    Parameters
+    ----------
+    key : str
+        The environment variable name to retrieve
+    default : str | 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
+    -------
+    str | None
+        The string 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 := getenv(key=key):
         return value
 
@@ -222,6 +319,31 @@ def getenv_base64[Value](
     decoder: Callable[[bytes], Value],
     required: bool = False,
 ) -> Value | None:
+    """
+    Get a base64-encoded value from an environment variable and decode it.
+
+    Parameters
+    ----------
+    key : str
+        The environment variable name to retrieve
+    default : Value | None, optional
+        Value to return if the environment variable is not set
+    decoder : Callable[[bytes], Value]
+        Function to decode the base64-decoded bytes into the desired type
+    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 decoded 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 := getenv(key=key):
         return decoder(b64decode(value))
 
@@ -236,22 +358,32 @@ def load_env(
     path: str | None = None,
     override: bool = True,
 ) -> None:
-    """\
-    Minimalist implementation of environment variables file loader. \
-    When the file is not available configuration won't be loaded.
-    Allows only subset of formatting:
-    - lines starting with '#' are ignored
-    - other comments are not allowed
-    - each element is in a new line
-    - each element must be a `key=value` pair without whitespaces or additional characters
-    - keys without values are ignored
+    """
+    Load environment variables from a .env file.
+
+    A minimalist implementation that reads key-value pairs from the specified file
+    and sets them as environment variables. If the file doesn't exist, the function
+    silently continues without loading any variables.
+
+    The file format follows these rules:
+    - Lines starting with '#' are treated as comments and ignored
+    - Each variable must be on a separate line in the format `KEY=VALUE`
+    - No spaces or additional characters are allowed around the '=' sign
+    - Keys without values are ignored
+    - Inline comments are not supported
 
     Parameters
     ----------
-    path: str
-        custom path to load environment variables, default is '.env'
-    override: bool
-        override existing variables on conflict if True, otherwise keep existing
+    path : str | None, default=None
+        Path to the environment file. If None, defaults to '.env'
+    override : bool, default=True
+        If True, overrides existing environment variables with values from the file.
+        If False, only sets variables that don't already exist in the environment.
+
+    Returns
+    -------
+    None
+        This function modifies the environment variables but doesn't return anything.
     """
 
     try:

haiway/utils/formatting.py

@@ -10,6 +10,33 @@ def format_str(  # noqa: PLR0911
     value: Any,
     /,
 ) -> str:
+    """
+    Format any Python value into a readable string representation.
+
+    Creates a human-readable string representation of complex data structures,
+    with proper indentation and formatting for nested structures. This is especially
+    useful for logging, debugging, and observability contexts.
+
+    Parameters
+    ----------
+    value : Any
+        The value to format as a string
+
+    Returns
+    -------
+    str
+        A formatted string representation of the input value
+
+    Notes
+    -----
+    - Strings are quoted, with multi-line strings using triple quotes
+    - Bytes are prefixed with 'b' and quoted
+    - Mappings (like dictionaries) are formatted with keys and values
+    - Sequences (like lists) are formatted with indices and values
+    - Objects are formatted with their attribute names and values
+    - MISSING values are converted to empty strings
+    - Nested structures maintain proper indentation
+    """
     # check for string
     if isinstance(value, str):
         if "\n" in value:

haiway/utils/freezing.py

@@ -8,7 +8,27 @@ def freeze(
     /,
 ) -> None:
     """
-    Freeze object instance by replacing __delattr__ and __setattr__ to raising Exceptions.
+    Make an object instance immutable by preventing attribute modification.
+
+    This function modifies the given object to prevent further changes to its attributes.
+    It replaces the object's __setattr__ and __delattr__ methods with ones that raise
+    exceptions, effectively making the object immutable after this function is called.
+
+    Parameters
+    ----------
+    instance : object
+        The object instance to make immutable
+
+    Returns
+    -------
+    None
+        The object is modified in-place
+
+    Notes
+    -----
+    - This only affects direct attribute assignments and deletions
+    - Mutable objects contained within the instance can still be modified internally
+    - The object's class remains unchanged, only the specific instance is affected
     """
 
     def frozen_set(

haiway/utils/noop.py

@@ -11,7 +11,23 @@ def noop(
     **kwargs: Any,
 ) -> None:
     """
-    Placeholder function doing nothing (no operation).
+    Placeholder function that accepts any arguments and does nothing.
+
+    This utility function is useful for cases where a callback is required
+    but no action should be taken, such as in testing, as a default handler,
+    or as a placeholder during development.
+
+    Parameters
+    ----------
+    *args: Any
+        Any positional arguments, which are ignored
+    **kwargs: Any
+        Any keyword arguments, which are ignored
+
+    Returns
+    -------
+    None
+        This function performs no operation and returns nothing
     """
 
 
@@ -20,5 +36,21 @@ async def async_noop(
     **kwargs: Any,
 ) -> None:
     """
-    Placeholder async function doing nothing (no operation).
+    Asynchronous placeholder function that accepts any arguments and does nothing.
+
+    This utility function is useful for cases where an async callback is required
+    but no action should be taken, such as in testing, as a default async handler,
+    or as a placeholder during asynchronous workflow development.
+
+    Parameters
+    ----------
+    *args: Any
+        Any positional arguments, which are ignored
+    **kwargs: Any
+        Any keyword arguments, which are ignored
+
+    Returns
+    -------
+    None
+        This function performs no operation and returns nothing
     """

haiway/utils/queue.py

@@ -9,7 +9,25 @@ __all__ = ("AsyncQueue",)
 class AsyncQueue[Element](AsyncIterator[Element]):
     """
     Asynchronous queue supporting iteration and finishing.
-    Cannot be concurrently consumed by multiple readers.
+
+    A queue implementation optimized for asynchronous workflows, providing async
+    iteration over elements and supporting operations like enqueuing elements,
+    finishing the queue, and cancellation.
+
+    Cannot be concurrently consumed by multiple readers - only one consumer
+    can iterate through the queue at a time.
+
+    Parameters
+    ----------
+    *elements : Element
+        Initial elements to populate the queue with
+    loop : AbstractEventLoop | None, default=None
+        Event loop to use for async operations. If None, the running loop is used.
+
+    Notes
+    -----
+    This class is immutable with respect to its attributes after initialization.
+    Any attempt to modify its attributes directly will raise an AttributeError.
     """
 
     __slots__ = (
@@ -70,6 +88,14 @@ class AsyncQueue[Element](AsyncIterator[Element]):
 
     @property
     def is_finished(self) -> bool:
+        """
+        Check if the queue has been marked as finished.
+
+        Returns
+        -------
+        bool
+            True if the queue has been finished, False otherwise
+        """
         return self._finish_reason is not None
 
     def enqueue(
@@ -77,6 +103,22 @@ class AsyncQueue[Element](AsyncIterator[Element]):
         element: Element,
         /,
     ) -> None:
+        """
+        Add an element to the queue.
+
+        If a consumer is waiting for an element, it will be immediately notified.
+        Otherwise, the element is appended to the queue.
+
+        Parameters
+        ----------
+        element : Element
+            The element to add to the queue
+
+        Raises
+        ------
+        RuntimeError
+            If the queue has already been finished
+        """
         if self.is_finished:
             raise RuntimeError("AsyncQueue is already finished")
 
@@ -90,6 +132,19 @@ class AsyncQueue[Element](AsyncIterator[Element]):
         self,
         exception: BaseException | None = None,
     ) -> None:
+        """
+        Mark the queue as finished, optionally with an exception.
+
+        After finishing, no more elements can be enqueued. Any waiting consumers
+        will be notified with the provided exception or StopAsyncIteration.
+        If the queue is already finished, this method does nothing.
+
+        Parameters
+        ----------
+        exception : BaseException | None, default=None
+            Optional exception to raise in consumers. If None, StopAsyncIteration
+            is used to signal normal completion.
+        """
         if self.is_finished:
             return  # already finished, ignore
 
@@ -113,6 +168,12 @@ class AsyncQueue[Element](AsyncIterator[Element]):
                 self._waiting.set_exception(self._finish_reason)  # pyright: ignore[reportArgumentType]
 
     def cancel(self) -> None:
+        """
+        Cancel the queue with a CancelledError exception.
+
+        This is a convenience method that calls finish() with a CancelledError.
+        Any waiting consumers will receive this exception.
+        """
         self.finish(exception=CancelledError())
 
     async def __anext__(self) -> Element:
@@ -143,5 +204,11 @@ class AsyncQueue[Element](AsyncIterator[Element]):
             )
 
     def clear(self) -> None:
+        """
+        Clear all pending elements from the queue.
+
+        This method removes all elements currently in the queue. It will only
+        clear the queue if no consumer is currently waiting for an element.
+        """
         if self._waiting is None or self._waiting.done():
             self._queue.clear()

haiway/utils/stream.py

@@ -10,10 +10,32 @@ __all__ = ("AsyncStream",)
 
 
 class AsyncStream[Element](AsyncIterator[Element]):
+    """
+    An asynchronous stream implementation supporting push-based async iteration.
+
+    AsyncStream provides a way to create a stream of elements where producers can
+    asynchronously send elements and consumers can iterate over them using async
+    iteration. Only one consumer can iterate through the stream at a time.
+
+    This class implements a flow-controlled stream where the producer waits until
+    the consumer is ready to receive the next element, ensuring back-pressure.
+
+    Unlike AsyncQueue, AsyncStream cannot be reused for multiple iterations and
+    requires coordination between producer and consumer.
+    """
+
     def __init__(
         self,
         loop: AbstractEventLoop | None = None,
     ) -> None:
+        """
+        Initialize a new asynchronous stream.
+
+        Parameters
+        ----------
+        loop : AbstractEventLoop | None, default=None
+            Event loop to use for async operations. If None, the running loop is used.
+        """
         self._loop: AbstractEventLoop = loop or get_running_loop()
         self._ready: Future[None] = self._loop.create_future()
         self._waiting: Future[Element] | None = None
@@ -21,6 +43,14 @@ class AsyncStream[Element](AsyncIterator[Element]):
 
     @property
     def finished(self) -> bool:
+        """
+        Check if the stream has been marked as finished.
+
+        Returns
+        -------
+        bool
+            True if the stream has been finished, False otherwise
+        """
         return self._finish_reason is not None
 
     async def send(
@@ -28,6 +58,18 @@ class AsyncStream[Element](AsyncIterator[Element]):
         element: Element,
         /,
     ) -> None:
+        """
+        Send an element to the stream.
+
+        This method waits until the consumer is ready to receive the element,
+        implementing back-pressure. If the stream is finished, the element will
+        be silently discarded.
+
+        Parameters
+        ----------
+        element : Element
+            The element to send to the stream
+        """
         if self._finish_reason is not None:
             return  # already finished
 
@@ -47,6 +89,21 @@ class AsyncStream[Element](AsyncIterator[Element]):
         self,
         exception: BaseException | None = None,
     ) -> None:
+        """
+        Mark the stream as finished, optionally with an exception.
+
+        After finishing, sent elements will be silently discarded. The consumer
+        will receive the provided exception or StopAsyncIteration when attempting
+        to get the next element.
+
+        If the stream is already finished, this method does nothing.
+
+        Parameters
+        ----------
+        exception : BaseException | None, default=None
+            Optional exception to raise in the consumer. If None, StopAsyncIteration
+            is used to signal normal completion.
+        """
         if self.finished:
             return  # already finished, ignore
 
@@ -73,9 +130,35 @@ class AsyncStream[Element](AsyncIterator[Element]):
                 self._waiting.set_exception(self._finish_reason)
 
     def cancel(self) -> None:
+        """
+        Cancel the stream with a CancelledError exception.
+
+        This is a convenience method that calls finish() with a CancelledError.
+        The consumer will receive this exception when attempting to get the next element.
+        """
         self.finish(exception=CancelledError())
 
     async def __anext__(self) -> Element:
+        """
+        Get the next element from the stream.
+
+        This method is called automatically when the stream is used in an
+        async for loop. It waits for the next element to be sent or for
+        the stream to be finished.
+
+        Returns
+        -------
+        Element
+            The next element from the stream
+
+        Raises
+        ------
+        BaseException
+            The exception provided to finish(), or StopAsyncIteration if
+            finish() was called without an exception
+        AssertionError
+            If the stream is being consumed by multiple consumers
+        """
         assert self._waiting is None, "AsyncStream can't be reused"  # nosec: B101
 
         if self._finish_reason:

{haiway-0.19.5.dist-info → haiway-0.20.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: haiway
-Version: 0.19.5
+Version: 0.20.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