haiway 0.10.14__py3-none-any.whl → 0.10.16__py3-none-any.whl

haiway/utils/always.py

@@ -0,0 +1,61 @@
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+__all__ = [
+    "always",
+    "async_always",
+]
+
+
+def always[Value](
+    value: Value,
+    /,
+) -> Callable[..., Value]:
+    """
+    Factory method creating functions returning always the same value.
+
+    Parameters
+    ----------
+    value: Value
+        value to be always returned from prepared function
+
+    Returns
+    -------
+    Callable[..., Value]
+        function ignoring arguments and always returning the provided value.
+    """
+
+    def always_value(
+        *args: Any,
+        **kwargs: Any,
+    ) -> Value:
+        return value
+
+    return always_value
+
+
+def async_always[Value](
+    value: Value,
+    /,
+) -> Callable[..., Coroutine[None, None, Value]]:
+    """
+    Factory method creating async functions returning always the same value.
+
+    Parameters
+    ----------
+    value: Value
+        value to be always returned from prepared function
+
+    Returns
+    -------
+    Callable[..., Coroutine[None, None, Value]]
+        async function ignoring arguments and always returning the provided value.
+    """
+
+    async def always_value(
+        *args: Any,
+        **kwargs: Any,
+    ) -> Value:
+        return value
+
+    return always_value

haiway/utils/collections.py

@@ -0,0 +1,185 @@
+from collections.abc import Mapping, Sequence, Set
+from typing import overload
+
+__all__ = [
+    "as_dict",
+    "as_list",
+    "as_set",
+    "as_tuple",
+]
+
+
+@overload
+def as_list[T](
+    collection: Sequence[T],
+    /,
+) -> list[T]: ...
+
+
+@overload
+def as_list[T](
+    collection: Sequence[T] | None,
+    /,
+) -> list[T] | None: ...
+
+
+def as_list[T](
+    collection: Sequence[T] | None,
+    /,
+) -> list[T] | None:
+    """
+    Converts any given Sequence into a list.
+
+    Parameters
+    ----------
+    collection : Sequence[T] | None
+        The input collection to be converted.
+
+    Returns
+    -------
+    list[T] | None
+        A new list containing all elements of the input collection,\
+         or the original list if it was already one.
+        None if no value was provided.
+    """
+
+    if collection is None:
+        return None
+
+    if isinstance(collection, list):
+        return collection
+
+    else:
+        return list(collection)
+
+
+@overload
+def as_tuple[T](
+    collection: Sequence[T],
+    /,
+) -> tuple[T, ...]: ...
+
+
+@overload
+def as_tuple[T](
+    collection: Sequence[T] | None,
+    /,
+) -> tuple[T, ...] | None: ...
+
+
+def as_tuple[T](
+    collection: Sequence[T] | None,
+    /,
+) -> tuple[T, ...] | None:
+    """
+    Converts any given Sequence into a tuple.
+
+    Parameters
+    ----------
+    collection : Sequence[T] | None
+        The input collection to be converted.
+
+    Returns
+    -------
+    tuple[T] | None
+        A new tuple containing all elements of the input collection,\
+         or the original tuple if it was already one.
+        None if no value was provided.
+    """
+
+    if collection is None:
+        return None
+
+    if isinstance(collection, tuple):
+        return collection
+
+    else:
+        return tuple(collection)
+
+
+@overload
+def as_set[T](
+    collection: Set[T],
+    /,
+) -> set[T]: ...
+
+
+@overload
+def as_set[T](
+    collection: Set[T] | None,
+    /,
+) -> set[T] | None: ...
+
+
+def as_set[T](
+    collection: Set[T] | None,
+    /,
+) -> set[T] | None:
+    """
+    Converts any given Set into a set.
+
+    Parameters
+    ----------
+    collection : Set[T]
+        The input collection to be converted.
+
+    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.
+    """
+
+    if collection is None:
+        return None
+
+    if isinstance(collection, set):
+        return collection
+
+    else:
+        return set(collection)
+
+
+@overload
+def as_dict[K, V](
+    collection: Mapping[K, V],
+    /,
+) -> dict[K, V]: ...
+
+
+@overload
+def as_dict[K, V](
+    collection: Mapping[K, V] | None,
+    /,
+) -> dict[K, V] | None: ...
+
+
+def as_dict[K, V](
+    collection: Mapping[K, V] | None,
+    /,
+) -> dict[K, V] | None:
+    """
+    Converts any given Mapping into a dict.
+
+    Parameters
+    ----------
+    collection : Mapping[K, V]
+        The input collection to be converted.
+
+    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.
+    """
+
+    if collection is None:
+        return None
+
+    if isinstance(collection, dict):
+        return collection
+
+    else:
+        return dict(collection)

haiway/utils/env.py

@@ -0,0 +1,230 @@
+from os import environ, getenv
+from typing import Literal, overload
+
+__all__ = [
+    "getenv_bool",
+    "getenv_float",
+    "getenv_int",
+    "getenv_str",
+    "load_env",
+]
+
+
+@overload
+def getenv_bool(
+    key: str,
+    /,
+) -> bool | None: ...
+
+
+@overload
+def getenv_bool(
+    key: str,
+    /,
+    default: bool,
+) -> bool: ...
+
+
+@overload
+def getenv_bool(
+    key: str,
+    /,
+    *,
+    required: Literal[True],
+) -> bool: ...
+
+
+def getenv_bool(
+    key: str,
+    /,
+    default: bool | None = None,
+    *,
+    required: bool = False,
+) -> bool | None:
+    if value := getenv(key=key):
+        return value.lower() in ("true", "1", "t")
+
+    elif required and default is None:
+        raise ValueError(f"Required environment value `{key}` is missing!")
+
+    else:
+        return default
+
+
+@overload
+def getenv_int(
+    key: str,
+    /,
+) -> int | None: ...
+
+
+@overload
+def getenv_int(
+    key: str,
+    /,
+    default: int,
+) -> int: ...
+
+
+@overload
+def getenv_int(
+    key: str,
+    /,
+    *,
+    required: Literal[True],
+) -> int: ...
+
+
+def getenv_int(
+    key: str,
+    /,
+    default: int | None = None,
+    *,
+    required: bool = False,
+) -> int | None:
+    if value := getenv(key=key):
+        try:
+            return int(value)
+
+        except Exception as exc:
+            raise ValueError(f"Environment value `{key}` is not a valid int!") from exc
+
+    elif required and default is None:
+        raise ValueError(f"Required environment value `{key}` is missing!")
+
+    else:
+        return default
+
+
+@overload
+def getenv_float(
+    key: str,
+    /,
+) -> float | None: ...
+
+
+@overload
+def getenv_float(
+    key: str,
+    /,
+    default: float,
+) -> float: ...
+
+
+@overload
+def getenv_float(
+    key: str,
+    /,
+    *,
+    required: Literal[True],
+) -> float: ...
+
+
+def getenv_float(
+    key: str,
+    /,
+    default: float | None = None,
+    *,
+    required: bool = False,
+) -> float | None:
+    if value := getenv(key=key):
+        try:
+            return float(value)
+
+        except Exception as exc:
+            raise ValueError(f"Environment value `{key}` is not a valid float!") from exc
+
+    elif required and default is None:
+        raise ValueError(f"Required environment value `{key}` is missing!")
+
+    else:
+        return default
+
+
+@overload
+def getenv_str(
+    key: str,
+    /,
+) -> str | None: ...
+
+
+@overload
+def getenv_str(
+    key: str,
+    /,
+    default: str,
+) -> str: ...
+
+
+@overload
+def getenv_str(
+    key: str,
+    /,
+    *,
+    required: Literal[True],
+) -> str: ...
+
+
+def getenv_str(
+    key: str,
+    /,
+    default: str | None = None,
+    *,
+    required: bool = False,
+) -> str | None:
+    if value := getenv(key=key):
+        return value
+
+    elif required and default is None:
+        raise ValueError(f"Required environment value `{key}` is missing!")
+
+    else:
+        return default
+
+
+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
+
+    Parameters
+    ----------
+    path: str
+        custom path to load environment variables, default is '.env'
+    override: bool
+        override existing variables on conflict if True, otherwise keep existing
+    """
+
+    try:
+        with open(file=path or ".env") as file:
+            for line in file.readlines():
+                if line.startswith("#"):
+                    continue  # ignore commented
+
+                idx: int  # find where key ends
+                for element in enumerate(line):
+                    if element[1] == "=":
+                        idx: int = element[0]
+                        break
+                else:  # ignore keys without assignment
+                    continue
+
+                if idx >= len(line):
+                    continue  # ignore keys without values
+
+                key: str = line[0:idx]
+                value: str = line[idx + 1 :].strip()
+                if value and (override or key not in environ):
+                    environ[key] = value
+
+    except FileNotFoundError:
+        pass  # ignore loading if no .env available

haiway/utils/freezing.py

@@ -0,0 +1,28 @@
+from typing import Any
+
+__all__ = [
+    "freeze",
+]
+
+
+def freeze(
+    instance: object,
+    /,
+) -> None:
+    """
+    Freeze object instance by replacing __delattr__ and __setattr__ to raising Exceptions.
+    """
+
+    def frozen_set(
+        __name: str,
+        __value: Any,
+    ) -> None:
+        raise RuntimeError(f"{instance.__class__.__qualname__} is frozen and can't be modified")
+
+    def frozen_del(
+        __name: str,
+    ) -> None:
+        raise RuntimeError(f"{instance.__class__.__qualname__} is frozen and can't be modified")
+
+    instance.__delattr__ = frozen_del
+    instance.__setattr__ = frozen_set

haiway/utils/logs.py

@@ -0,0 +1,57 @@
+from logging.config import dictConfig
+
+from haiway.utils.env import getenv_bool
+
+__all__ = [
+    "setup_logging",
+]
+
+
+def setup_logging(
+    *loggers: str,
+    debug: bool = getenv_bool("DEBUG_LOGGING", __debug__),
+) -> None:
+    """\
+    Setup logging configuration and prepare specified loggers.
+
+    Parameters
+    ----------
+    *loggers: str
+        names of additional loggers to configure.
+
+    NOTE: this function should be run only once on application start
+    """
+
+    dictConfig(
+        config={
+            "version": 1,
+            "disable_existing_loggers": True,
+            "formatters": {
+                "standard": {
+                    "format": "%(asctime)s [%(levelname)-4s] [%(name)s] %(message)s",
+                    "datefmt": "%d/%b/%Y:%H:%M:%S +0000",
+                },
+            },
+            "handlers": {
+                "console": {
+                    "level": "DEBUG" if debug else "INFO",
+                    "formatter": "standard",
+                    "class": "logging.StreamHandler",
+                    "stream": "ext://sys.stdout",
+                },
+            },
+            "loggers": {
+                name: {
+                    "handlers": ["console"],
+                    "level": "DEBUG" if debug else "INFO",
+                    "propagate": False,
+                }
+                for name in loggers
+            },
+            "root": {  # root logger
+                "handlers": ["console"],
+                "level": "DEBUG" if debug else "INFO",
+                "propagate": False,
+            },
+        },
+    )

haiway/utils/mimic.py

@@ -0,0 +1,77 @@
+from collections.abc import Callable
+from typing import Any, cast, overload
+
+__all__ = [
+    "mimic_function",
+]
+
+
+@overload
+def mimic_function[**Args, Result](
+    function: Callable[Args, Result],
+    /,
+    within: Callable[..., Any],
+) -> Callable[Args, Result]: ...
+
+
+@overload
+def mimic_function[**Args, Result](
+    function: Callable[Args, Result],
+    /,
+) -> Callable[[Callable[..., Any]], Callable[Args, Result]]: ...
+
+
+def mimic_function[**Args, Result](
+    function: Callable[Args, Result],
+    /,
+    within: Callable[..., Result] | None = None,
+) -> Callable[[Callable[..., Result]], Callable[Args, Result]] | Callable[Args, Result]:
+    def mimic(
+        target: Callable[..., Result],
+    ) -> Callable[Args, Result]:
+        # mimic function attributes if able
+        for attribute in (
+            "__module__",
+            "__name__",
+            "__qualname__",
+            "__doc__",
+            "__annotations__",
+            "__type_params__",
+            "__defaults__",
+            "__kwdefaults__",
+            "__globals__",
+        ):
+            try:
+                setattr(
+                    target,
+                    attribute,
+                    getattr(
+                        function,
+                        attribute,
+                    ),
+                )
+
+            except AttributeError:
+                pass
+        try:
+            target.__dict__.update(function.__dict__)
+
+        except AttributeError:
+            pass
+
+        setattr(  # noqa: B010 - mimic functools.wraps behavior for correct signature checks
+            target,
+            "__wrapped__",
+            function,
+        )
+
+        return cast(
+            Callable[Args, Result],
+            target,
+        )
+
+    if target := within:
+        return mimic(target)
+
+    else:
+        return mimic

haiway/utils/noop.py

@@ -0,0 +1,24 @@
+from typing import Any
+
+__all__ = [
+    "async_noop",
+    "noop",
+]
+
+
+def noop(
+    *args: Any,
+    **kwargs: Any,
+) -> None:
+    """
+    Placeholder function doing nothing (no operation).
+    """
+
+
+async def async_noop(
+    *args: Any,
+    **kwargs: Any,
+) -> None:
+    """
+    Placeholder async function doing nothing (no operation).
+    """