haiway 0.1.0__py3-none-any.whl

haiway/state/validation.py

@@ -0,0 +1,125 @@
+import types
+import typing
+from collections.abc import Callable, Sequence
+from typing import Any
+
+from haiway import types as _types
+from haiway.state.attributes import AttributeAnnotation
+
+__all__ = [
+    "attribute_type_validator",
+]
+
+
+def attribute_type_validator(
+    annotation: AttributeAnnotation,
+    /,
+) -> Callable[[Any], Any]:
+    match annotation.origin:
+        case types.NoneType:
+            return _none_validator
+
+        case _types.Missing:
+            return _missing_validator
+
+        case types.UnionType:
+            return _prepare_union_validator(annotation.arguments)
+
+        case typing.Literal:
+            return _prepare_literal_validator(annotation.arguments)
+
+        case typing.Any:
+            return _any_validator
+
+        case type() as other_type:
+            return _prepare_type_validator(other_type)
+
+        case other:
+            raise TypeError(f"Unsupported type annotation: {other}")
+
+
+def _none_validator(
+    value: Any,
+) -> Any:
+    match value:
+        case None:
+            return None
+
+        case _:
+            raise TypeError(f"Type '{type(value)}' is not matching expected type 'None'")
+
+
+def _missing_validator(
+    value: Any,
+) -> Any:
+    match value:
+        case _types.Missing():
+            return _types.MISSING
+
+        case _:
+            raise TypeError(f"Type '{type(value)}' is not matching expected type 'Missing'")
+
+
+def _any_validator(
+    value: Any,
+) -> Any:
+    return value  # any is always valid
+
+
+def _prepare_union_validator(
+    elements: Sequence[AttributeAnnotation],
+    /,
+) -> Callable[[Any], Any]:
+    validators: list[Callable[[Any], Any]] = [
+        attribute_type_validator(alternative) for alternative in elements
+    ]
+
+    def union_validator(
+        value: Any,
+    ) -> Any:
+        errors: list[Exception] = []
+        for validator in validators:
+            try:
+                return validator(value)
+
+            except Exception as exc:
+                errors.append(exc)
+
+        raise ExceptionGroup("Multiple errors", errors)
+
+    return union_validator
+
+
+def _prepare_literal_validator(
+    elements: Sequence[Any],
+    /,
+) -> Callable[[Any], Any]:
+    def literal_validator(
+        value: Any,
+    ) -> Any:
+        if value in elements:
+            return value
+
+        else:
+            raise ValueError(f"Value '{value}' is not matching expected '{elements}'")
+
+    return literal_validator
+
+
+def _prepare_type_validator(
+    validated_type: type[Any],
+    /,
+) -> Callable[[Any], Any]:
+    def type_validator(
+        value: Any,
+    ) -> Any:
+        match value:
+            case value if isinstance(value, validated_type):
+                return value
+
+            case _:
+                raise TypeError(
+                    f"Type '{type(value)}' is not matching expected type '{validated_type}'"
+                )
+
+    return type_validator

haiway/types/__init__.py

@@ -0,0 +1,11 @@
+from haiway.types.frozen import frozenlist
+from haiway.types.missing import MISSING, Missing, is_missing, not_missing, when_missing
+
+__all__ = [
+    "frozenlist",
+    "is_missing",
+    "Missing",
+    "MISSING",
+    "not_missing",
+    "when_missing",
+]

haiway/types/frozen.py

@@ -0,0 +1,5 @@
+__all__ = [
+    "frozenlist",
+]
+
+type frozenlist[Value] = tuple[Value, ...]

haiway/types/missing.py

@@ -0,0 +1,91 @@
+from typing import Any, Final, TypeGuard, cast, final
+
+__all__ = [
+    "MISSING",
+    "Missing",
+    "is_missing",
+    "not_missing",
+    "when_missing",
+]
+
+
+class MissingType(type):
+    _instance: Any = None
+
+    def __call__(cls) -> Any:
+        if cls._instance is None:
+            cls._instance = super().__call__()
+            return cls._instance
+
+        else:
+            return cls._instance
+
+
+@final
+class Missing(metaclass=MissingType):
+    """
+    Type representing absence of a value. Use MISSING constant for its value.
+    """
+
+    def __bool__(self) -> bool:
+        return False
+
+    def __eq__(
+        self,
+        value: object,
+    ) -> bool:
+        return value is MISSING
+
+    def __str__(self) -> str:
+        return "MISSING"
+
+    def __repr__(self) -> str:
+        return "MISSING"
+
+    def __getattribute__(
+        self,
+        name: str,
+    ) -> Any:
+        raise RuntimeError("Missing has no attributes")
+
+    def __setattr__(
+        self,
+        __name: str,
+        __value: Any,
+    ) -> None:
+        raise RuntimeError("Missing can't be modified")
+
+    def __delattr__(
+        self,
+        __name: str,
+    ) -> None:
+        raise RuntimeError("Missing can't be modified")
+
+
+MISSING: Final[Missing] = Missing()
+
+
+def is_missing(
+    check: Any | Missing,
+    /,
+) -> TypeGuard[Missing]:
+    return check is MISSING
+
+
+def not_missing[Value](
+    check: Value | Missing,
+    /,
+) -> TypeGuard[Value]:
+    return check is not MISSING
+
+
+def when_missing[Value](
+    check: Value | Missing,
+    /,
+    value: Value,
+) -> Value:
+    if check is MISSING:
+        return value
+
+    else:
+        return cast(Value, check)

haiway/utils/__init__.py

@@ -0,0 +1,23 @@
+from haiway.utils.always import always, async_always
+from haiway.utils.env import getenv_bool, getenv_float, getenv_int, getenv_str, load_env
+from haiway.utils.immutable import freeze
+from haiway.utils.logs import setup_logging
+from haiway.utils.mimic import mimic_function
+from haiway.utils.noop import async_noop, noop
+from haiway.utils.queue import AsyncQueue
+
+__all__ = [
+    "always",
+    "async_always",
+    "async_noop",
+    "AsyncQueue",
+    "freeze",
+    "getenv_bool",
+    "getenv_float",
+    "getenv_int",
+    "getenv_str",
+    "load_env",
+    "mimic_function",
+    "noop",
+    "setup_logging",
+]

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/env.py

@@ -0,0 +1,164 @@
+from os import environ, getenv
+from typing import overload
+
+__all__ = [
+    "getenv_bool",
+    "getenv_int",
+    "getenv_float",
+    "getenv_str",
+    "load_env",
+]
+
+
+@overload
+def getenv_bool(
+    key: str,
+    /,
+) -> bool | None: ...
+
+
+@overload
+def getenv_bool(
+    key: str,
+    /,
+    default: bool,
+) -> bool: ...
+
+
+def getenv_bool(
+    key: str,
+    /,
+    default: bool | None = None,
+) -> bool | None:
+    if value := getenv(key=key):
+        return value.lower() in ("true", "1", "t")
+    else:
+        return default
+
+
+@overload
+def getenv_int(
+    key: str,
+    /,
+) -> int | None: ...
+
+
+@overload
+def getenv_int(
+    key: str,
+    /,
+    default: int,
+) -> int: ...
+
+
+def getenv_int(
+    key: str,
+    /,
+    default: int | None = None,
+) -> int | None:
+    if value := getenv(key=key):
+        return int(value)
+
+    else:
+        return default
+
+
+@overload
+def getenv_float(
+    key: str,
+    /,
+) -> float | None: ...
+
+
+@overload
+def getenv_float(
+    key: str,
+    /,
+    default: float,
+) -> float: ...
+
+
+def getenv_float(
+    key: str,
+    /,
+    default: float | None = None,
+) -> float | None:
+    if value := getenv(key=key):
+        return float(value)
+
+    else:
+        return default
+
+
+@overload
+def getenv_str(
+    key: str,
+    /,
+) -> str | None: ...
+
+
+@overload
+def getenv_str(
+    key: str,
+    /,
+    default: str,
+) -> str: ...
+
+
+def getenv_str(
+    key: str,
+    /,
+    default: str | None = None,
+) -> str | None:
+    if value := getenv(key=key):
+        return value
+    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/immutable.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).
+    """