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

mm_std/__init__.py

@@ -13,12 +13,16 @@ 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
 from .date import utc_random as utc_random
 from .dict import replace_empty_dict_values as replace_empty_dict_values
 from .env import get_dotenv as get_dotenv
+from .http.http_request import http_request as http_request
+from .http.response import HttpError as HttpError
+from .http.response import HttpResponse as HttpResponse
 from .http_ import CHROME_USER_AGENT as CHROME_USER_AGENT
 from .http_ import FIREFOX_USER_AGENT as FIREFOX_USER_AGENT
 from .http_ import HResponse as HResponse

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/http/http_request.py

@@ -0,0 +1,121 @@
+import aiohttp
+from aiohttp.typedefs import LooseCookies, Query
+from aiohttp_socks import ProxyConnector
+from multidict import CIMultiDictProxy
+
+from mm_std.http.response import HttpError, HttpResponse
+
+
+async def http_request(
+    url: str,
+    *,
+    method: str = "GET",
+    params: Query | None = None,
+    data: dict[str, object] | None = None,
+    json: dict[str, object] | None = None,
+    headers: dict[str, str] | None = None,
+    cookies: LooseCookies | None = None,
+    user_agent: str | None = None,
+    proxy: str | None = None,
+    timeout: float | None = 10.0,
+) -> HttpResponse:
+    """
+    Send an HTTP request and return the response.
+    """
+    timeout_ = aiohttp.ClientTimeout(total=timeout) if timeout else None
+    if user_agent:
+        if not headers:
+            headers = {}
+        headers["user-agent"] = user_agent
+
+    try:
+        if proxy and proxy.startswith("socks"):
+            return await _request_with_socks_proxy(
+                url,
+                method=method,
+                params=params,
+                data=data,
+                json=json,
+                headers=headers,
+                cookies=cookies,
+                proxy=proxy,
+                timeout=timeout_,
+            )
+        return await _request_with_http_or_none_proxy(
+            url,
+            method=method,
+            params=params,
+            data=data,
+            json=json,
+            headers=headers,
+            cookies=cookies,
+            proxy=proxy,
+            timeout=timeout_,
+        )
+    except TimeoutError as err:
+        return HttpResponse(error=HttpError.TIMEOUT, error_message=str(err))
+    except Exception as err:
+        return HttpResponse(error=HttpError.ERROR, error_message=str(err))
+
+
+async def _request_with_http_or_none_proxy(
+    url: str,
+    *,
+    method: str = "GET",
+    params: Query | None = None,
+    data: dict[str, object] | None = None,
+    json: dict[str, object] | None = None,
+    headers: dict[str, str] | None = None,
+    cookies: LooseCookies | None = None,
+    proxy: str | None = None,
+    timeout: aiohttp.ClientTimeout | None,
+) -> HttpResponse:
+    async with aiohttp.request(
+        method, url, params=params, data=data, json=json, headers=headers, cookies=cookies, proxy=proxy, timeout=timeout
+    ) as res:
+        return HttpResponse(
+            status=res.status,
+            error=None,
+            error_message=None,
+            body=(await res.read()).decode(),
+            headers=headers_dict(res.headers),
+        )
+
+
+async def _request_with_socks_proxy(
+    url: str,
+    *,
+    method: str = "GET",
+    proxy: str,
+    params: Query | None = None,
+    data: dict[str, object] | None = None,
+    json: dict[str, object] | None = None,
+    headers: dict[str, str] | None = None,
+    cookies: LooseCookies | None = None,
+    timeout: aiohttp.ClientTimeout | None,
+) -> HttpResponse:
+    connector = ProxyConnector.from_url(proxy)
+    async with (
+        aiohttp.ClientSession(connector=connector) as session,
+        session.request(
+            method, url, params=params, data=data, json=json, headers=headers, cookies=cookies, timeout=timeout
+        ) as res,
+    ):
+        return HttpResponse(
+            status=res.status,
+            error=None,
+            error_message=None,
+            body=(await res.read()).decode(),
+            headers=headers_dict(res.headers),
+        )
+
+
+def headers_dict(headers: CIMultiDictProxy[str]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for key in headers:
+        values = headers.getall(key)
+        if len(values) == 1:
+            result[key] = values[0]
+        else:
+            result[key] = ", ".join(values)
+    return result

mm_std/http/response.py

@@ -0,0 +1,93 @@
+import enum
+import json
+from typing import Any
+
+import pydash
+from pydantic import GetCoreSchemaHandler
+from pydantic_core import CoreSchema, core_schema
+
+
+@enum.unique
+class HttpError(str, enum.Enum):
+    TIMEOUT = "timeout"
+    PROXY = "proxy"
+    CONNECTION = "connection"
+    ERROR = "error"
+
+
+class HttpResponse:
+    def __init__(
+        self,
+        status: int | None = None,
+        error: HttpError | None = None,
+        error_message: str | None = None,
+        body: str | None = None,
+        headers: dict[str, str] | None = None,
+    ) -> None:
+        self.status = status
+        self.error = error
+        self.error_message = error_message
+        self.body = body
+        self.headers = headers
+
+        self._json_data: Any = None
+        self._json_parsed = False
+        self._json_parsed_error = False
+
+    def _parse_json(self) -> None:
+        if self.body is None:
+            self._json_parsed_error = True
+            return
+        try:
+            self._json_data = None
+            self._json_data = json.loads(self.body)
+            self._json_parsed_error = False
+        except json.JSONDecodeError:
+            self._json_parsed_error = True
+        self._json_parsed = True
+
+    def json(self, path: str | None = None) -> Any:  # noqa: ANN401
+        if not self._json_parsed:
+            self._parse_json()
+        if path:
+            return pydash.get(self._json_data, path, None)
+        return self._json_data
+
+    def dict(self) -> dict[str, object]:
+        return {
+            "status": self.status,
+            "error": self.error,
+            "error_message": self.error_message,
+            "body": self.body,
+            "headers": self.headers,
+        }
+
+    def is_json_parse_error(self) -> bool:
+        if not self._json_parsed:
+            self._parse_json()
+        return self._json_parsed_error
+
+    def __repr__(self) -> str:
+        return f"HttpResponse(status={self.status}, error={self.error}, error_message={self.error_message}, body={self.body}, headers={self.headers})"  # noqa: E501
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source_type: type[Any], handler: GetCoreSchemaHandler) -> CoreSchema:
+        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) -> "HttpResponse":
+        if isinstance(v, cls):
+            return v
+        if isinstance(v, dict):
+            return cls(
+                status=v.get("status"),
+                error=HttpError(v["error"]) if v.get("error") else None,
+                error_message=v.get("error_message"),
+                body=v.get("body"),
+                headers=v.get("headers"),
+            )
+        raise TypeError(f"Cannot parse value as {cls.__name__}: {v}")

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mm-std
-Version: 0.3.25
+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.25.dist-info → mm_std-0.3.27.dist-info}/RECORD

@@ -1,7 +1,8 @@
-mm_std/__init__.py,sha256=bdkBTX7_u4NYtTRdVDHgZUozQlFRBx3TTiMK7Cenup0,3100
+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
@@ -25,6 +26,9 @@ mm_std/concurrency/async_task_runner.py,sha256=EN7tN2enkVYVgDbhSiAr-_W4o9m9wBXCv
 mm_std/concurrency/sync_decorators.py,sha256=syCQBOmN7qPO55yzgJB2rbkh10CVww376hmyvs6e5tA,1080
 mm_std/concurrency/sync_scheduler.py,sha256=j4tBL_cBI1spr0cZplTA7N2CoYsznuORMeRN8rpR6gY,2407
 mm_std/concurrency/sync_task_runner.py,sha256=s5JPlLYLGQGHIxy4oDS-PN7O9gcy-yPZFoNm8RQwzcw,1780
-mm_std-0.3.25.dist-info/METADATA,sha256=dLHZWg8G8cs5y3S8bu3zwxW-qgJaGaBGVQxS8vl4lcg,415
-mm_std-0.3.25.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-mm_std-0.3.25.dist-info/RECORD,,
+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.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,,