scalebox-sdk 0.1.0__py3-none-any.whl

scalebox/utils/httpcoreclient.py

@@ -0,0 +1,297 @@
+import contextlib
+import json
+from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
+
+import httpcore
+
+
+class HTTPXCoreTool:
+    """
+    基于 httpcore 的高级 HTTP 工具类
+    支持同步/异步请求、连接池管理、流式传输等
+    """
+
+    def __init__(
+        self,
+        base_url: str = "",
+        timeout: float = 10.0,
+        max_connections: int = 100,
+        max_keepalive_connections: int = 50,
+        keepalive_expiry: float = 5.0,
+        http2: bool = False,
+        ssl_verify: bool = True,
+        headers: Optional[Dict[str, str]] = None,
+    ):
+        """
+        初始化 HTTP 客户端
+
+        :param base_url: 基础 URL 前缀
+        :param timeout: 请求超时时间(秒)
+        :param max_connections: 最大连接数
+        :param max_keepalive_connections: 最大空闲连接数
+        :param keepalive_expiry: 空闲连接超时时间(秒)
+        :param http2: 是否启用 HTTP/2
+        :param ssl_verify: 是否验证 SSL 证书
+        :param headers: 默认请求头
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.http2 = http2
+        self.ssl_verify = ssl_verify
+        self.default_headers = headers or {}
+
+        # 创建同步连接池
+        self.sync_pool = httpcore.ConnectionPool(
+            max_connections=max_connections,
+            max_keepalive_connections=max_keepalive_connections,
+            keepalive_expiry=keepalive_expiry,
+            http2=http2,
+            ssl_context=(
+                None if ssl_verify else httpcore._ssl.create_untrusted_context()
+            ),
+        )
+
+        # 创建异步连接池
+        self.async_pool = httpcore.AsyncConnectionPool(
+            max_connections=max_connections,
+            max_keepalive_connections=max_keepalive_connections,
+            keepalive_expiry=keepalive_expiry,
+            http2=http2,
+            ssl_context=(
+                None if ssl_verify else httpcore._ssl.create_untrusted_context()
+            ),
+        )
+
+    def close(self) -> None:
+        """关闭同步连接池"""
+        self.sync_pool.close()
+
+    async def aclose(self) -> None:
+        """关闭异步连接池"""
+        await self.async_pool.aclose()
+
+    @contextlib.contextmanager
+    def stream_context(
+        self,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        content: Optional[Union[bytes, Iterable[bytes]]] = None,
+    ) -> Iterable[httpcore.Response]:
+        """
+        同步流式请求上下文管理器
+
+        使用示例:
+        with tool.stream_context("GET", "https://example.com") as response:
+            for chunk in response.iter_bytes():
+                print(chunk)
+        """
+        full_url = self._build_url(url, params)
+        req_headers = self._build_headers(headers)
+
+        response = self.sync_pool.request(
+            method=method.encode(),
+            url=self._parse_url(full_url),
+            headers=req_headers,
+            content=content,
+            timeout=self.timeout,
+        )
+
+        try:
+            yield response
+        finally:
+            # 确保流关闭
+            for _ in response.stream:
+                pass
+
+    @contextlib.asynccontextmanager
+    async def async_stream_context(
+        self,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        content: Optional[Union[bytes, Iterable[bytes]]] = None,
+    ) -> Iterable[httpcore.Response]:
+        """
+        异步流式请求上下文管理器
+
+        使用示例:
+        async with tool.async_stream_context("GET", "https://example.com") as response:
+            async for chunk in response.astream_bytes():
+                print(chunk)
+        """
+        full_url = self._build_url(url, params)
+        req_headers = self._build_headers(headers)
+
+        response = await self.async_pool.request(
+            method=method.encode(),
+            url=self._parse_url(full_url),
+            headers=req_headers,
+            content=content,
+            timeout=self.timeout,
+        )
+
+        try:
+            yield response
+        finally:
+            # 确保流关闭
+            async for _ in response.stream:
+                pass
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        json_data: Optional[Any] = None,
+        data: Optional[Union[bytes, Dict[str, Any]]] = None,
+    ) -> httpcore.Response:
+        """
+        同步 HTTP 请求
+        """
+        content, headers = self._prepare_content(json_data, data, headers)
+        full_url = self._build_url(url, params)
+        req_headers = self._build_headers(headers)
+
+        return self.sync_pool.request(
+            method=method.encode(),
+            url=self._parse_url(full_url),
+            headers=req_headers,
+            content=content,
+            timeout=self.timeout,
+        )
+
+    async def async_request(
+        self,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        json_data: Optional[Any] = None,
+        data: Optional[Union[bytes, Dict[str, Any]]] = None,
+    ) -> httpcore.Response:
+        """
+        异步 HTTP 请求
+        """
+        content, headers = self._prepare_content(json_data, data, headers)
+        full_url = self._build_url(url, params)
+        req_headers = self._build_headers(headers)
+
+        return await self.async_pool.request(
+            method=method.encode(),
+            url=self._parse_url(full_url),
+            headers=req_headers,
+            content=content,
+            timeout=self.timeout,
+        )
+
+    # 快捷方法
+    def get(self, url: str, **kwargs) -> httpcore.Response:
+        return self.request("GET", url, **kwargs)
+
+    async def async_get(self, url: str, **kwargs) -> httpcore.Response:
+        return await self.async_request("GET", url, **kwargs)
+
+    def post(self, url: str, **kwargs) -> httpcore.Response:
+        return self.request("POST", url, **kwargs)
+
+    async def async_post(self, url: str, **kwargs) -> httpcore.Response:
+        return await self.async_request("POST", url, **kwargs)
+
+    def put(self, url: str, **kwargs) -> httpcore.Response:
+        return self.request("PUT", url, **kwargs)
+
+    async def async_put(self, url: str, **kwargs) -> httpcore.Response:
+        return await self.async_request("PUT", url, **kwargs)
+
+    def delete(self, url: str, **kwargs) -> httpcore.Response:
+        return self.request("DELETE", url, **kwargs)
+
+    async def async_delete(self, url: str, **kwargs) -> httpcore.Response:
+        return await self.async_request("DELETE", url, **kwargs)
+
+    # 辅助方法
+    def _build_url(self, url: str, params: Optional[Dict[str, Any]]) -> str:
+        """构建完整 URL"""
+        if not url.startswith(("http://", "https://")):
+            url = f"{self.base_url}/{url.lstrip('/')}"
+
+        if params:
+            from urllib.parse import urlencode
+
+            query = urlencode(params, doseq=True)
+            url = f"{url}?{query}" if "?" not in url else f"{url}&{query}"
+
+        return url
+
+    def _parse_url(self, url: str) -> Tuple[bytes, bytes, int, bytes]:
+        """解析 URL 为 httpcore 格式"""
+        from urllib.parse import urlparse
+
+        parsed = urlparse(url)
+        scheme = parsed.scheme.encode()
+        host = parsed.hostname.encode()
+        port = parsed.port or (443 if scheme == b"https" else 80)
+        path = parsed.path.encode() or b"/"
+        if parsed.query:
+            path += b"?" + parsed.query.encode()
+        return (scheme, host, port, path)
+
+    def _build_headers(
+        self, headers: Optional[Dict[str, str]]
+    ) -> List[Tuple[bytes, bytes]]:
+        """构建请求头列表"""
+        merged_headers = {**self.default_headers, **(headers or {})}
+        return [(k.lower().encode(), v.encode()) for k, v in merged_headers.items()]
+
+    def _prepare_content(
+        self,
+        json_data: Optional[Any],
+        data: Optional[Union[bytes, Dict[str, Any]]],
+        headers: Optional[Dict[str, str]],
+    ) -> Tuple[Optional[Union[bytes, Iterable[bytes]]], Dict[str, str]]:
+        """准备请求内容和头信息"""
+        content = None
+        headers = headers or {}
+
+        if json_data is not None:
+            content = json.dumps(json_data).encode("utf-8")
+            headers.setdefault("Content-Type", "application/json")
+
+        elif data is not None:
+            if isinstance(data, dict):
+                from urllib.parse import urlencode
+
+                content = urlencode(data, doseq=True).encode("utf-8")
+                headers.setdefault("Content-Type", "application/x-www-form-urlencoded")
+            else:
+                content = data
+
+        return content, headers
+
+    @staticmethod
+    def read_response(response: httpcore.Response) -> bytes:
+        """读取完整响应内容"""
+        return b"".join(response.stream)
+
+    @staticmethod
+    def read_response_json(response: httpcore.Response) -> Any:
+        """读取并解析 JSON 响应"""
+        return json.loads(HTTPXCoreTool.read_response(response))
+
+    @staticmethod
+    async def async_read_response(response: httpcore.Response) -> bytes:
+        """异步读取完整响应内容"""
+        content = b""
+        async for chunk in response.stream:
+            content += chunk
+        return content
+
+    @staticmethod
+    async def async_read_response_json(response: httpcore.Response) -> Any:
+        """异步读取并解析 JSON 响应"""
+        content = await HTTPXCoreTool.async_read_response(response)
+        return json.loads(content)

scalebox/utils/httpxclient.py

@@ -0,0 +1,403 @@
+import asyncio
+import contextlib
+import json
+from typing import Any, AsyncGenerator, Dict, Generator, Optional, Union
+
+import httpx
+
+
+class HTTPXClient:
+    """
+    基于 httpx.AsyncClient 的高级 HTTP 工具类
+    支持同步/异步请求、连接池管理、流式传输等完整功能
+    """
+
+    def __init__(
+        self,
+        base_url: str = "",
+        timeout: float = 30.0,
+        max_connections: int = 100,
+        max_keepalive_connections: int = 50,
+        keepalive_expiry: float = 5.0,
+        http2: bool = False,
+        ssl_verify: bool = True,
+        default_headers: Optional[Dict[str, str]] = None,
+        follow_redirects: bool = True,
+        retries: int = 0,
+        backoff_factor: float = 0.1,
+    ):
+        """
+        初始化 HTTP 客户端
+
+        :param base_url: 基础 URL 前缀
+        :param timeout: 请求超时时间(秒)
+        :param max_connections: 最大连接数
+        :param max_keepalive_connections: 最大空闲连接数
+        :param keepalive_expiry: 空闲连接超时时间(秒)
+        :param http2: 是否启用 HTTP/2
+        :param ssl_verify: 是否验证 SSL 证书
+        :param default_headers: 默认请求头
+        :param follow_redirects: 是否跟随重定向
+        :param retries: 请求失败重试次数
+        :param backoff_factor: 重试退避因子
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.http2 = http2
+        self.ssl_verify = ssl_verify
+        self.default_headers = default_headers or {}
+        self.follow_redirects = follow_redirects
+        self.retries = retries
+        self.backoff_factor = backoff_factor
+
+        # 创建同步客户端
+        self.sync_client = httpx.Client(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            limits=httpx.Limits(
+                max_connections=max_connections,
+                max_keepalive_connections=max_keepalive_connections,
+                keepalive_expiry=keepalive_expiry,
+            ),
+            http2=http2,
+            verify=ssl_verify,
+            headers=self.default_headers,
+            follow_redirects=follow_redirects,
+        )
+
+        # 创建异步客户端
+        self.async_client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            limits=httpx.Limits(
+                max_connections=max_connections,
+                max_keepalive_connections=max_keepalive_connections,
+                keepalive_expiry=keepalive_expiry,
+            ),
+            http2=http2,
+            verify=ssl_verify,
+            headers=self.default_headers,
+            follow_redirects=follow_redirects,
+        )
+
+        # 配置重试
+        if retries > 0:
+            retry_transport = httpx.HTTPTransport(
+                retries=self.retries, backoff_factor=self.backoff_factor
+            )
+            async_retry_transport = httpx.AsyncHTTPTransport(
+                retries=self.retries, backoff_factor=self.backoff_factor
+            )
+
+            self.sync_client = httpx.Client(transport=retry_transport)
+            self.async_client = httpx.AsyncClient(transport=async_retry_transport)
+
+    def close(self) -> None:
+        """关闭同步客户端"""
+        self.sync_client.close()
+
+    async def aclose(self) -> None:
+        """关闭异步客户端"""
+        await self.async_client.aclose()
+
+    @contextlib.contextmanager
+    def context(self) -> "HTTPXClient":
+        """
+        同步上下文管理器 (自动关闭)
+
+        使用示例:
+        with HTTPXClient() as client:
+            response = client.get("/api")
+        """
+        try:
+            yield self
+        finally:
+            self.close()
+
+    @contextlib.asynccontextmanager
+    async def acontext(self) -> "HTTPXClient":
+        """
+        异步上下文管理器 (自动关闭)
+
+        使用示例:
+        async with HTTPXClient() as client:
+            response = await client.aget("/api")
+        """
+        try:
+            yield self
+        finally:
+            await self.aclose()
+
+    @contextlib.contextmanager
+    def stream(
+        self,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        json_data: Optional[Any] = None,
+        data: Optional[Union[bytes, Dict[str, Any]]] = None,
+    ) -> Generator[httpx.Response, None, None]:
+        """
+        同步流式请求上下文管理器
+
+        使用示例:
+        with client.stream("GET", "/large-file") as response:
+            for chunk in response.iter_bytes():
+                process_chunk(chunk)
+        """
+        headers = headers or {}
+        with self.sync_client.stream(
+            method,
+            url,
+            params=params,
+            headers={**self.default_headers, **headers},
+            json=json_data,
+            data=data,
+        ) as response:
+            yield response
+
+    @contextlib.asynccontextmanager
+    async def astream(
+        self,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        json_data: Optional[Any] = None,
+        data: Optional[Union[bytes, Dict[str, Any]]] = None,
+    ) -> AsyncGenerator[httpx.Response, None]:
+        """
+        异步流式请求上下文管理器
+
+        使用示例:
+        async with client.astream("GET", "/large-file") as response:
+            async for chunk in response.aiter_bytes():
+                process_chunk(chunk)
+        """
+        headers = headers or {}
+        async with self.async_client.stream(
+            method,
+            url,
+            params=params,
+            headers={**self.default_headers, **headers},
+            json=json_data,
+            data=data,
+        ) as response:
+            yield response
+
+    # ================ 同步请求方法 ================
+    def request(
+        self,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        json_data: Optional[Any] = None,
+        data: Optional[Union[bytes, Dict[str, Any]]] = None,
+    ) -> httpx.Response:
+        """同步 HTTP 请求"""
+        headers = headers or {}
+        return self.sync_client.request(
+            method,
+            url,
+            params=params,
+            headers={**self.default_headers, **headers},
+            json=json_data,
+            data=data,
+        )
+
+    def get(
+        self,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> httpx.Response:
+        """同步 GET 请求"""
+        return self.request("GET", url, params=params, headers=headers)
+
+    def post(
+        self,
+        url: str,
+        json_data: Optional[Any] = None,
+        data: Optional[Union[bytes, Dict[str, Any]]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> httpx.Response:
+        """同步 POST 请求"""
+        return self.request(
+            "POST", url, params=params, headers=headers, json_data=json_data, data=data
+        )
+
+    def put(
+        self,
+        url: str,
+        json_data: Optional[Any] = None,
+        data: Optional[Union[bytes, Dict[str, Any]]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> httpx.Response:
+        """同步 PUT 请求"""
+        return self.request(
+            "PUT", url, params=params, headers=headers, json_data=json_data, data=data
+        )
+
+    def delete(
+        self,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> httpx.Response:
+        """同步 DELETE 请求"""
+        return self.request("DELETE", url, params=params, headers=headers)
+
+    # ================ 异步请求方法 ================
+    async def arequest(
+        self,
+        method: str,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        json_data: Optional[Any] = None,
+        data: Optional[Union[bytes, Dict[str, Any]]] = None,
+    ) -> httpx.Response:
+        """异步 HTTP 请求"""
+        headers = headers or {}
+        return await self.async_client.request(
+            method,
+            url,
+            params=params,
+            headers={**self.default_headers, **headers},
+            json=json_data,
+            data=data,
+        )
+
+    async def aget(
+        self,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> httpx.Response:
+        """异步 GET 请求"""
+        return await self.arequest("GET", url, params=params, headers=headers)
+
+    async def apost(
+        self,
+        url: str,
+        json_data: Optional[Any] = None,
+        data: Optional[Union[bytes, Dict[str, Any]]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> httpx.Response:
+        """异步 POST 请求"""
+        return await self.arequest(
+            "POST", url, params=params, headers=headers, json_data=json_data, data=data
+        )
+
+    async def aput(
+        self,
+        url: str,
+        json_data: Optional[Any] = None,
+        data: Optional[Union[bytes, Dict[str, Any]]] = None,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> httpx.Response:
+        """异步 PUT 请求"""
+        return await self.arequest(
+            "PUT", url, params=params, headers=headers, json_data=json_data, data=data
+        )
+
+    async def adelete(
+        self,
+        url: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> httpx.Response:
+        """异步 DELETE 请求"""
+        return await self.arequest("DELETE", url, params=params, headers=headers)
+
+    # ================ 响应处理工具 ================
+    @staticmethod
+    def read_response(response: httpx.Response) -> bytes:
+        """读取完整响应内容 (同步)"""
+        return response.content
+
+    @staticmethod
+    def read_response_text(response: httpx.Response) -> str:
+        """读取响应文本 (同步)"""
+        return response.text
+
+    @staticmethod
+    def read_response_json(response: httpx.Response) -> Any:
+        """解析 JSON 响应 (同步)"""
+        return response.json()
+
+    @staticmethod
+    async def aread_response(response: httpx.Response) -> bytes:
+        """异步读取完整响应内容"""
+        return await response.aread()
+
+    @staticmethod
+    async def aread_response_text(response: httpx.Response) -> str:
+        """异步读取响应文本"""
+        return await response.atext()
+
+    @staticmethod
+    async def aread_response_json(response: httpx.Response) -> Any:
+        """异步解析 JSON 响应"""
+        return await response.ajson()
+
+    # ================ 连接池状态 ================
+    def connection_pool_status(self) -> Dict[str, Any]:
+        """获取同步连接池状态"""
+        transport = self.sync_client._transport
+        return {
+            "total_connections": transport._pool.num_connections,
+            "active_connections": transport._pool.num_active_connections,
+            "idle_connections": transport._pool.num_idle_connections,
+            "max_connections": transport._pool.max_connections,
+        }
+
+    async def aconnection_pool_status(self) -> Dict[str, Any]:
+        """获取异步连接池状态"""
+        transport = self.async_client._transport
+        return {
+            "total_connections": transport._pool.num_connections,
+            "active_connections": transport._pool.num_active_connections,
+            "idle_connections": transport._pool.num_idle_connections,
+            "max_connections": transport._pool.max_connections,
+        }
+
+    # ================ 高级功能 ================
+    def set_proxy(self, proxy_url: str, proxy_auth: Optional[tuple] = None) -> None:
+        """设置代理 (同步和异步)"""
+        self.sync_client = httpx.Client(proxies=proxy_url, auth=proxy_auth)
+        self.async_client = httpx.AsyncClient(proxies=proxy_url, auth=proxy_auth)
+
+    def set_cookies(self, cookies: Dict[str, str]) -> None:
+        """设置 Cookies (同步和异步)"""
+        self.sync_client.cookies = httpx.Cookies(cookies)
+        self.async_client.cookies = httpx.Cookies(cookies)
+
+    def add_event_hook(self, event: str, hook: callable) -> None:
+        """添加事件钩子 (同步和异步)"""
+        self.sync_client.event_hooks[event].append(hook)
+        self.async_client.event_hooks[event].append(hook)
+
+    def reset_client(self) -> None:
+        """重置客户端 (清除所有状态)"""
+        self.close()
+        self.async_client = httpx.AsyncClient(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            http2=self.http2,
+            verify=self.ssl_verify,
+            headers=self.default_headers,
+        )
+        self.sync_client = httpx.Client(
+            base_url=self.base_url,
+            timeout=self.timeout,
+            http2=self.http2,
+            verify=self.ssl_verify,
+            headers=self.default_headers,
+        )