mm-std 0.3.26__py3-none-any.whl → 0.3.27__py3-none-any.whl

mm_std/__init__.py

@@ -13,6 +13,7 @@ from .config import BaseConfig as BaseConfig
 from .crypto import fernet_decrypt as fernet_decrypt
 from .crypto import fernet_encrypt as fernet_encrypt
 from .crypto import fernet_generate_key as fernet_generate_key
+from .data_result import DataResult as DataResult
 from .date import parse_date as parse_date
 from .date import utc_delta as utc_delta
 from .date import utc_now as utc_now

mm_std/data_result.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Generic, TypeVar, cast
+
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+
+T = TypeVar("T")
+U = TypeVar("U")
+
+
+class DataResult(Generic[T]):
+    """
+    A result wrapper that encapsulates either a successful result (`ok`) or an error message (`err`).
+    Optionally carries auxiliary `data` field regardless of success or failure.
+    """
+
+    def __init__(
+        self,
+        ok: T | None = None,
+        err: str | None = None,
+        data: object = None,
+        ok_is_none: bool = False,  # Allow None as a valid success value
+    ) -> None:
+        # Sanity check: at least one of ok or err must be provided, unless explicitly allowed via `ok_is_none`
+        if ok is None and err is None and not ok_is_none:
+            raise ValueError("Either ok or err must be set")
+        # You can't set both ok and err unless ok_is_none is True (used to explicitly accept None as success)
+        if (ok_is_none or ok is not None) and err is not None:
+            raise ValueError("Cannot set both ok and err")
+
+        self.ok = ok
+        self.err = err
+        self.data = data
+
+    def is_ok(self) -> bool:
+        """
+        Returns True if the result represents a success.
+        """
+        return self.err is None
+
+    def is_err(self) -> bool:
+        """
+        Returns True if the result represents an error.
+        """
+        return self.err is not None
+
+    def unwrap(self) -> T:
+        """
+        Returns the successful value or raises an exception if this is an error result.
+        """
+        if self.is_err():
+            raise RuntimeError(f"Called `unwrap()` on an `Err` value: {self.err!r}")
+        return cast(T, self.ok)
+
+    def unwrap_ok_or(self, default: T) -> T:
+        """
+        Returns the contained success value if this is a success result,
+        or returns the provided default value if this is an error result.
+
+        Args:
+            default: The value to return if this is an error result.
+
+        Returns:
+            The success value or the default value.
+        """
+        if self.is_ok():
+            return cast(T, self.ok)
+        return default
+
+    def unwrap_err(self) -> str:
+        """
+        Returns the error message or raises an exception if this is a success result.
+        """
+        if self.is_ok():
+            raise RuntimeError(f"Called `unwrap_err()` on an `Ok` value: {self.ok!r}")
+        return cast(str, self.err)
+
+    def dict(self) -> dict[str, object]:
+        """
+        Returns a dictionary representation of the result.
+        """
+        return {"ok": self.ok, "err": self.err, "data": self.data}
+
+    def map(self, fn: Callable[[T], U]) -> DataResult[U]:
+        """
+        Transforms the success value using the provided function if this is a success result.
+        If this is an error result, returns a new error result with the same error message.
+
+        Args:
+            fn: A function that transforms the success value from type T to type U.
+
+        Returns:
+            A new DataResult with the transformed success value or the original error.
+        """
+        if self.is_err():
+            return DataResult[U](err=self.err, data=self.data)
+
+        mapped_ok = fn(self.unwrap())
+        return DataResult[U](ok=mapped_ok, data=self.data)
+
+    async def map_async(self, fn: Callable[[T], Awaitable[U]]) -> DataResult[U]:
+        """
+        Asynchronously transforms the success value using the provided async function if this is a success result.
+        If this is an error result, returns a new error result with the same error message.
+
+        Args:
+            fn: An async function that transforms the success value from type T to type U.
+
+        Returns:
+            A new DataResult with the transformed success value or the original error.
+        """
+        if self.is_err():
+            return DataResult[U](err=self.err, data=self.data)
+
+        mapped_ok = await fn(self.unwrap())
+        return DataResult[U](ok=mapped_ok, data=self.data)
+
+    def __repr__(self) -> str:
+        """
+        Returns the debug representation of the result.
+        """
+        result = f"DataResult(ok={self.ok!r}" if self.is_ok() else f"DataResult(err={self.err!r}"
+        if self.data is not None:
+            result += f", data={self.data!r}"
+        return result + ")"
+
+    def __hash__(self) -> int:
+        """
+        Enables hashing for use in sets and dict keys.
+        """
+        return hash((self.ok, self.err, self.data))
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Compares two DataResult instances by value.
+        """
+        if not isinstance(other, DataResult):
+            return NotImplemented
+        return self.ok == other.ok and self.err == other.err and self.data == other.data
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, _source_type: type[Any], _handler: GetCoreSchemaHandler) -> CoreSchema:
+        """
+        Custom Pydantic v2 integration method for schema generation and validation.
+        """
+        return core_schema.no_info_after_validator_function(
+            cls._validate,
+            core_schema.any_schema(),
+            serialization=core_schema.plain_serializer_function_ser_schema(lambda x: x.dict()),
+        )
+
+    @classmethod
+    def _validate(cls, v: object) -> DataResult[T]:
+        """
+        Internal validation logic for Pydantic.
+        Accepts either an instance of DataResult or a dict-like input.
+        """
+        if isinstance(v, cls):
+            return v
+        if isinstance(v, dict):
+            return cls(
+                ok=v.get("ok"),
+                err=v.get("err"),
+                data=v.get("data"),
+            )
+        raise TypeError(f"Cannot parse value as {cls.__name__}: {v}")

{mm_std-0.3.26.dist-info → mm_std-0.3.27.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mm-std
-Version: 0.3.26
+Version: 0.3.27
 Requires-Python: >=3.12
 Requires-Dist: aiohttp-socks~=0.10.1
 Requires-Dist: aiohttp~=3.11.16

{mm_std-0.3.26.dist-info → mm_std-0.3.27.dist-info}/RECORD

@@ -1,7 +1,8 @@
-mm_std/__init__.py,sha256=Q0UguFT4b_LdKmxFSI4NQ47mwYRVRTjZ6fgYh8qZY4Q,3266
+mm_std/__init__.py,sha256=ePkjykjImp2Wu10lFzK3Fl1HpGqqXFb_HZK_BSiU3MM,3316
 mm_std/command.py,sha256=ze286wjUjg0QSTgIu-2WZks53_Vclg69UaYYgPpQvCU,1283
 mm_std/config.py,sha256=4ox4D2CgGR76bvZ2n2vGQOYUDagFnlKEDb87to5zpxE,1871
 mm_std/crypto.py,sha256=jdk0_TCmeU0pPXMyz9xH6kQHSjjZ9GcGClBwQps5vBo,340
+mm_std/data_result.py,sha256=--rg0YPaJkszCmbt9TO-BthdGdYrCRARA8iII9LVocE,5871
 mm_std/date.py,sha256=976eEkSONuNqHQBgSRu8hrtH23tJqztbmHFHLdbP2TY,1879
 mm_std/dict.py,sha256=6GkhJPXD0LiJDxPcYe6jPdEDw-MN7P7mKu6U5XxwYDk,675
 mm_std/env.py,sha256=5zaR9VeIfObN-4yfgxoFeU5IM1GDeZZj9SuYf7t9sOA,125
@@ -28,6 +29,6 @@ mm_std/concurrency/sync_task_runner.py,sha256=s5JPlLYLGQGHIxy4oDS-PN7O9gcy-yPZFo
 mm_std/http/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mm_std/http/http_request.py,sha256=mJak332gv9NvY0JLO3hNrBxroQGS1HlNBzd1yq4Dy24,3694
 mm_std/http/response.py,sha256=vvv5COTjJula9t33mFyrruhrFC4dr_Uy0jDKj6t1JxM,2923
-mm_std-0.3.26.dist-info/METADATA,sha256=GW6fYKKEoBHo1GlukZ2LtY3gII8feRqjIynazLiX16g,415
-mm_std-0.3.26.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mm_std-0.3.26.dist-info/RECORD,,
+mm_std-0.3.27.dist-info/METADATA,sha256=H30ViZKdZolKRVDR9PxBk7OoQZWofyy-EqjrUpT2NkQ,415
+mm_std-0.3.27.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+mm_std-0.3.27.dist-info/RECORD,,