mvx-common 0.2.1__py3-none-any.whl

mvx/common/__init__.py

@@ -0,0 +1 @@
+# common/src/mvx/common/__init__.py

mvx/common/errors/__init__.py

@@ -0,0 +1,14 @@
+# common/src/mvx/common/errors/__init__.py
+
+from .structured_error import StructuredError
+from .reasoned_error import ReasonedError
+from .runtime_errors import RuntimeExtendedError, RuntimeUnexpectedError
+from .invalid_function_argument_error import InvalidFunctionArgumentError
+
+__all__ = (
+    "StructuredError",
+    "ReasonedError",
+    "RuntimeExtendedError",
+    "RuntimeUnexpectedError",
+    "InvalidFunctionArgumentError",
+)

mvx/common/errors/invalid_function_argument_error.py

@@ -0,0 +1,54 @@
+# common/src/mvx/common/errors/invalid_function_argument_error.py
+
+from __future__ import annotations
+from typing import Any, Mapping, Optional
+
+from .structured_error import StructuredError
+
+__all__ = ("InvalidFunctionArgumentError",)
+
+
+class InvalidFunctionArgumentError(StructuredError):
+    """
+    Error raised when a function argument fails validation.
+
+    Wraps an underlying validation exception and adds structured context about
+    the function, argument, offending value, and validation error type.
+
+    Args:
+        func: Function name where validation failed.
+        arg: Argument name that failed validation.
+        value: Offending argument value, when safe and useful to log.
+        cause: Underlying validation exception.
+        details: Additional log-friendly diagnostic context.
+    """
+
+    def __init__(
+        self,
+        *,
+        func: Optional[str],
+        arg: Optional[str],
+        value: Optional[Any] = None,
+        cause: Exception,
+        details: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        msg = f"invalid argument -> {str(cause)}"
+
+        func = func or "<unknown>"
+        arg = arg or "<unknown>"
+
+        base_details: dict[str, Any] = {
+            "func": func,
+            "arg": arg,
+            "error_type": type(cause).__name__,
+        }
+        if value is not None:
+            base_details["value"] = value
+        if details:
+            base_details.update(details)
+
+        super().__init__(
+            message=msg,
+            details=base_details,
+            cause=cause,
+        )

mvx/common/errors/reasoned_error.py

@@ -0,0 +1,56 @@
+# common/src/mvx/common/errors/reasoned_error.py
+from __future__ import annotations
+from typing import Any, Optional, Mapping
+
+from .structured_error import StructuredError
+
+__all__ = ("ReasonedError",)
+
+
+class ReasonedError(StructuredError):
+    """
+    Structured error with an optional stable reason code.
+
+    Extends StructuredError by adding `reason_code`, which can be used as a
+    machine-readable classifier for logging, metrics, and tests.
+
+    Args:
+        message: Human-readable error message.
+        details: Optional log-friendly diagnostic context.
+        cause: Optional underlying exception.
+        reason: Optional stable reason code.
+    """
+
+    def __init__(
+        self,
+        *,
+        message: str,
+        details: Optional[Mapping[str, Any]] = None,
+        cause: Optional[Exception] = None,
+        reason: Optional[str] = None,
+    ) -> None:
+
+        self.reason_code: Optional[str] = reason
+
+        super().__init__(
+            message=message,
+            details=details,
+            cause=cause,
+        )
+
+    def to_log_payload(self) -> dict[str, Any]:
+        """
+        Extend base log payload with the reason code.
+
+        Returns:
+            Log payload including "reason" when present.
+        """
+
+        payload: dict[str, Any] = {}
+
+        if self.reason_code is not None:
+            payload["reason"] = self.reason_code
+
+        payload.update(super().to_log_payload())
+
+        return payload

mvx/common/errors/runtime_errors.py

@@ -0,0 +1,79 @@
+# common/src/mvx/common/errors/runtime_errors.py
+from __future__ import annotations
+
+from typing import Optional, Mapping, Any
+
+from .structured_error import StructuredError
+
+__all__ = (
+    "RuntimeExtendedError",
+    "RuntimeUnexpectedError",
+)
+
+
+class RuntimeExtendedError(StructuredError, RuntimeError):
+    """
+    RuntimeError variant with structured diagnostic context.
+
+    Extends RuntimeError with the structured error payload provided by
+    StructuredError and optional source metadata.
+
+    Args:
+        message: Human-readable error message.
+        details: Optional log-friendly diagnostic context.
+        cause: Optional underlying exception.
+        module: Optional module name associated with the error.
+        qualname: Optional qualified name associated with the error.
+    """
+
+    def __init__(
+        self,
+        *,
+        message: str,
+        details: Optional[Mapping[str, Any]] = None,
+        cause: Optional[Exception] = None,
+        module: Optional[str] = None,
+        qualname: Optional[str] = None,
+    ) -> None:
+
+        self.module = None if module is None else (module.strip() or None)
+        self.qualname = None if qualname is None else (qualname.strip() or None)
+
+        RuntimeError.__init__(self, str(message))
+
+        StructuredError.__init__(
+            self,
+            message=message,
+            details=details,
+            cause=cause,
+        )
+
+    def to_log_payload(self) -> dict[str, Any]:
+        """
+        Return a structured logging payload with optional source metadata.
+
+        Returns:
+            Log-friendly error payload.
+        """
+        base = StructuredError.to_log_payload(self)
+
+        payload: dict[str, Any] = {}
+        if self.module is not None:
+            payload["module"] = self.module
+        if self.qualname is not None:
+            payload["qualname"] = self.qualname
+
+        payload.update(base)
+        return payload
+
+
+class RuntimeUnexpectedError(Exception):
+    """
+    Marker base class for runtime errors classified as unexpected.
+
+    This class is intended for multiple inheritance with concrete domain
+    errors. It marks an error as unexpected without replacing the domain-specific
+    error hierarchy.
+    """
+
+    ...

mvx/common/errors/structured_error.py

@@ -0,0 +1,85 @@
+# common/src/mvx/common/errors/structured_error.py
+from __future__ import annotations
+
+from typing import Any, Mapping, Optional, Self
+
+__all__ = ("StructuredError",)
+
+
+class StructuredError(Exception):
+    """
+    Base exception class for errors with structured diagnostic context.
+
+    Args:
+        message: Human-readable error message.
+        details: Optional log-friendly diagnostic context.
+        cause: Optional underlying exception.
+    """
+
+    def __init__(
+        self,
+        *,
+        message: str,
+        details: Optional[Mapping[str, Any]] = None,
+        cause: Optional[Exception] = None,
+    ) -> None:
+        self.message: str = message
+        self.details: dict[str, Any] = dict(details or {})
+
+        self.cause: Optional[Exception] = cause
+
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        base = f"{self.__class__.__name__}: {self.message}"
+        if self.details:
+            return f"{base} | details={self.details!r}"
+        return base
+
+    def with_detail(self, key: str, value: Any) -> Self:
+        """
+        Add or replace one detail entry.
+
+        Args:
+            key: Detail key.
+            value: Detail value.
+
+        Returns:
+            This error instance.
+        """
+        self.details[key] = value
+        return self
+
+    def with_details(self, extra: Mapping[str, Any]) -> Self:
+        """
+        Merge multiple detail entries.
+
+        Args:
+            extra: Detail entries to merge.
+
+        Returns:
+            This error instance.
+        """
+        self.details.update(extra)
+        return self
+
+    def to_log_payload(self) -> dict[str, Any]:
+        """
+        Return a stable dictionary representation for structured logging.
+
+        Returns:
+            Log-friendly error payload.
+        """
+        payload: dict[str, Any] = {
+            "kind": self.__class__.__name__,
+            "message": self.message,
+            "details": dict(self.details),
+        }
+
+        if self.cause is not None:
+            payload["cause"] = {
+                "kind": self.cause.__class__.__name__,
+                "message": str(self.cause),
+            }
+
+        return payload

mvx/common/helpers/__init__.py

@@ -0,0 +1,18 @@
+# common/src/mvx/common/helpers/__init__.py
+from .introspection import (
+    get_func_module_and_qualname,
+)
+
+from .api_error_processor import api_error_processor
+
+from .run_with_cancellation_policy import run_with_cancellation_policy, CancellationPolicy
+
+__all__ = (
+    # from introspection.py
+    "get_func_module_and_qualname",
+    # from api_error_processor.py
+    "api_error_processor",
+    # from run_with_cancellation_policy.py
+    "run_with_cancellation_policy",
+    "CancellationPolicy",
+)

mvx/common/helpers/api_error_processor.py

@@ -0,0 +1,122 @@
+# common/src/mvx/common/helpers/api_error_processor.py
+"""
+Decorator for normalizing public API errors.
+
+The decorator lets declared API errors pass through unchanged and wraps
+unexpected exceptions into a configured RuntimeExtendedError subclass.
+Cancellation is always propagated unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, TypeVar, Any, cast
+
+import asyncio
+from functools import wraps
+import inspect
+
+from ..errors import RuntimeExtendedError
+
+__all__ = ("api_error_processor",)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def api_error_processor(
+    *,
+    passthrough_error_types: tuple[type[Exception], ...],
+    raise_error_type: type[RuntimeExtendedError],
+) -> Callable[[F], F]:
+    """
+    Build a decorator for public API exception normalization.
+
+    Args:
+        passthrough_error_types: Exception types that must pass through unchanged.
+        raise_error_type: RuntimeExtendedError subclass used to wrap unexpected
+            exceptions.
+
+    Returns:
+        Decorator that applies the public API error policy to sync or async
+        callables.
+    """
+
+    def decorate(func: F) -> F:
+        module = getattr(func, "__module__", "<unknown>")
+        qualname = getattr(func, "__qualname__", getattr(func, "__name__", "<unknown>"))
+
+        target = inspect.unwrap(func)
+
+        if inspect.iscoroutinefunction(target):
+
+            @wraps(func)
+            async def wrapped_async(*args: Any, **kwargs: Any) -> Any:
+                try:
+                    return await func(*args, **kwargs)
+                except asyncio.CancelledError:
+                    raise
+                except Exception as exc:
+                    if isinstance(exc, passthrough_error_types):
+                        raise
+
+                    if isinstance(exc, RuntimeExtendedError):
+                        if exc.module is None:
+                            exc.module = module
+                        if exc.qualname is None:
+                            exc.qualname = qualname
+                        raise
+
+                    # noinspection PyBroadException
+                    try:
+                        err = raise_error_type(
+                            message=f"runtime unexpected error: {str(exc)}",
+                            module=module,
+                            qualname=qualname,
+                            cause=exc,
+                        )
+                    except Exception:
+                        err = raise_error_type(message=str(exc))
+                        err.cause = exc
+                        err.module = module
+                        err.qualname = qualname
+
+                    raise err from exc
+
+            # noinspection PyUnnecessaryCast
+            return cast(F, wrapped_async)
+
+        @wraps(func)
+        def wrapped_sync(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                if isinstance(exc, passthrough_error_types):
+                    raise
+                if isinstance(exc, RuntimeExtendedError):
+                    if exc.module is None:
+                        exc.module = module
+                    if exc.qualname is None:
+                        exc.qualname = qualname
+                    raise
+
+                # noinspection PyBroadException
+                try:
+                    err = raise_error_type(
+                        message=f"runtime unexpected error: {str(exc)}",
+                        module=module,
+                        qualname=qualname,
+                        cause=exc,
+                    )
+                except Exception:
+                    err = raise_error_type(message=str(exc))
+                    err.cause = exc
+                    err.module = module
+                    err.qualname = qualname
+
+                raise err from exc
+
+        # noinspection PyUnnecessaryCast
+        return cast(F, wrapped_sync)
+
+    return decorate

mvx/common/helpers/document_enum.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from enum import Enum
+from typing import TypeVar, cast
+
+EnumClassT = TypeVar("EnumClassT", bound=type[Enum])
+
+try:
+    from enum_tools.documentation import document_enum as _document_enum
+except ImportError:
+
+    def document_enum(enum_class: EnumClassT) -> EnumClassT:
+        return enum_class
+
+else:
+
+    def document_enum(enum_class: EnumClassT) -> EnumClassT:
+        return cast(EnumClassT, _document_enum(enum_class))

mvx/common/helpers/introspection.py

@@ -0,0 +1,21 @@
+# common/src/mvx/common/helpers/introspection.py
+from __future__ import annotations
+
+from typing import Callable
+
+__all__ = ("get_func_module_and_qualname",)
+
+
+def get_func_module_and_qualname(func: Callable) -> tuple[str, str]:
+    """
+    Return module and qualified name of a callable.
+
+    Args:
+        func: Callable object.
+
+    Returns:
+        Tuple of (module, qualname).
+    """
+    module = getattr(func, "__module__", "<unknown>")
+    qualname = getattr(func, "__qualname__", getattr(func, "__name__", "<unknown>"))
+    return module, qualname

mvx/common/helpers/run_with_cancellation_policy.py

@@ -0,0 +1,161 @@
+# common/src/mvx/common/helpers/run_with_cancellation_policy.py
+"""
+Utilities for running awaitables under explicit cancellation policies.
+
+The module provides a small primitive for cases where cancellation of the
+caller task must either be handled normally, deferred and reported as a flag,
+or deferred and re-raised after the protected operation completes.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Coroutine, Literal, TypeVar, Tuple, overload, Union
+from collections.abc import Awaitable, Callable
+
+from enum import StrEnum
+import asyncio
+
+__all__ = (
+    "CancellationPolicy",
+    "run_with_cancellation_policy",
+)
+
+T = TypeVar("T")
+
+
+class CancellationPolicy(StrEnum):
+    """
+    Cancellation handling policy for run_with_cancellation_policy().
+    """
+
+    PLAIN = "PLAIN"
+    DEFER_RERAISE = "DEFER_RERAISE"
+    DEFER_FLAG = "DEFER_FLAG"
+
+
+async def _as_coro(a: Awaitable[T]) -> T:
+    """
+    Wrap an arbitrary awaitable into a coroutine.
+
+    Args:
+        a: Awaitable to execute.
+
+    Returns:
+        Result produced by the awaitable.
+    """
+    return await a
+
+
+def _start_core_task(core_func: Callable[[], Awaitable[T]], op_name: str) -> asyncio.Task[T]:
+    """
+    Start the core awaitable as a named asyncio task.
+
+    Args:
+        core_func: Zero-argument callable returning the awaitable to run.
+        op_name: Name assigned to the created task.
+
+    Returns:
+        Started asyncio task.
+    """
+    a = core_func()
+    coro: Coroutine[Any, Any, T] = _as_coro(a)
+    return asyncio.create_task(coro, name=op_name)
+
+
+@overload
+async def run_with_cancellation_policy(
+    core_func: Callable[[], Awaitable[T]],
+    *,
+    policy: Literal[CancellationPolicy.PLAIN],
+) -> T: ...
+
+
+@overload
+async def run_with_cancellation_policy(
+    core_func: Callable[[], Awaitable[T]],
+    *,
+    policy: Literal[CancellationPolicy.DEFER_RERAISE],
+) -> T: ...
+
+
+@overload
+async def run_with_cancellation_policy(
+    core_func: Callable[[], Awaitable[T]],
+    *,
+    policy: Literal[CancellationPolicy.DEFER_FLAG] = CancellationPolicy.DEFER_FLAG,
+) -> Tuple[bool, T]: ...
+
+
+@overload
+async def run_with_cancellation_policy(
+    core_func: Callable[[], Awaitable[T]],
+    *,
+    policy: CancellationPolicy,
+    op_name: str = "unknown",
+) -> Union[T, Tuple[bool, T]]: ...
+
+
+async def run_with_cancellation_policy(
+    core_func: Callable[[], Awaitable[T]],
+    *,
+    policy: CancellationPolicy = CancellationPolicy.DEFER_FLAG,
+    op_name: str = "unknown",
+) -> Union[T, Tuple[bool, T]]:
+    """
+    Run one awaitable under the selected cancellation policy.
+
+    Args:
+        core_func: Zero-argument callable returning the awaitable to run.
+        policy: Cancellation policy applied while awaiting the operation.
+        op_name: Name assigned to the internal task in deferred policies.
+
+    Returns:
+        The operation result, or ``(cancel_requested, result)`` when using
+        ``CancellationPolicy.DEFER_FLAG``.
+
+    Raises:
+        asyncio.CancelledError: Raised according to the selected cancellation
+            policy or when the core task itself is cancelled.
+        Exception: Propagates exceptions raised by the core awaitable.
+    """
+    if policy is CancellationPolicy.PLAIN:
+        return await core_func()
+
+    core_task: asyncio.Task[T] = _start_core_task(core_func, op_name)
+    cancel_requested = False
+
+    while True:
+        try:
+            result = await asyncio.shield(core_task)
+            break
+        except asyncio.CancelledError:
+            # If the core task itself was cancelled, propagate core cancellation.
+            if core_task.cancelled():
+                raise
+
+            # Otherwise this is caller-task cancellation while core is still running (deferrable).
+            cancel_requested = True
+
+            current = asyncio.current_task()
+            if current is not None:
+                # Drop all pending cancellation requests for this caller task so that
+                # the next await does not immediately raise again.
+                while current.uncancel() > 0:
+                    pass
+            # Keep waiting for core_task to finish.
+
+        # Drain any pending cancellation that might have arrived in a tight race window
+        # after the await resumed but before we return/raise.
+    current = asyncio.current_task()
+    if current is not None and current.cancelling() > 0:
+        cancel_requested = True
+        while current.uncancel() > 0:
+            pass
+
+    if policy is CancellationPolicy.DEFER_FLAG:
+        return cancel_requested, result
+
+    # policy is DEFER_RERAISE
+    if cancel_requested:
+        raise asyncio.CancelledError()
+    return result