py-wecom-toolkit 4.2.3__tar.gz → 4.2.4__tar.gz

{py_wecom_toolkit-4.2.3 → py_wecom_toolkit-4.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.5
 Name: py-wecom-toolkit
-Version: 4.2.3
+Version: 4.2.4
 Summary: 企业微信 API 工具包
 Project-URL: HomePage, https://gitee.com/guolei19850528/py_wecom_toolkit
 Project-URL: Repository, https://gitee.com/guolei19850528/py_wecom_toolkit
@@ -28,7 +28,16 @@ Requires-Dist: httpx<1.0,>=0.24.0
 Requires-Dist: pydantic<3.0,>=2.0.0
 Requires-Dist: redis>=5.0.0
 Provides-Extra: all
-Requires-Dist: py-wecom-toolkit[dev,docs,test]; extra == 'all'
+Requires-Dist: mkdocs-material>=9.0.0; extra == 'all'
+Requires-Dist: mkdocs>=1.5.0; extra == 'all'
+Requires-Dist: mypy>=1.10.0; extra == 'all'
+Requires-Dist: pre-commit>=3.7.0; extra == 'all'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
+Requires-Dist: pytest>=8.0.0; extra == 'all'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'all'
+Requires-Dist: respx>=0.21.0; extra == 'all'
+Requires-Dist: ruff>=0.8.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: mypy>=1.10.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.7.0; extra == 'dev'

{py_wecom_toolkit-4.2.3 → py_wecom_toolkit-4.2.4}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 # 项目发布元数据及支持的最低 Python 版本。
 [project]
 name = "py-wecom-toolkit"
-version = "4.2.3"
+version = "4.2.4"
 description = "企业微信 API 工具包"
 # 发布后不会自动更新 README.md 内容，需手动维护。
 readme = { file = "README.md", content-type = "text/markdown" }

{py_wecom_toolkit-4.2.3 → py_wecom_toolkit-4.2.4}/src/py_wecom_toolkit/server/__init__.py

@@ -30,12 +30,6 @@ from ._models import (
 from ._models import (
     BaseResponse as ServerBaseResponse,
 )
-from ._models import (
-    ConfigError as ServerConfigError,
-)
-from ._models import (
-    NetworkError as ServerNetworkError,
-)
 
 __all__ = [
     "ServerAccessTokenCache",
@@ -47,7 +41,5 @@ __all__ = [
     "ServerAsyncClient",
     "ServerBaseResponse",
     "ServerClient",
-    "ServerConfigError",
-    "ServerNetworkError",
     "server_build_access_token_cache_key",
 ]

{py_wecom_toolkit-4.2.3 → py_wecom_toolkit-4.2.4}/src/py_wecom_toolkit/server/_clients.py

@@ -13,7 +13,7 @@ from ._caches import (
     AccessTokenDiskcacheCache,
     build_access_token_cache_key,
 )
-from ._models import AccessTokenResponse, ConfigError, NetworkError
+from ._models import AccessTokenResponse
 
 
 class Client:
@@ -47,9 +47,9 @@ class Client:
     ) -> None:
         """使用企业凭证、缓存配置和 HTTP 参数初始化客户端。"""
         if not corpid:
-            raise ConfigError("corpid is required")
+            raise ValueError("corpid is required")
         if not corpsecret:
-            raise ConfigError("corpsecret is required")
+            raise ValueError("corpsecret is required")
         self.corpid = corpid
         self.corpsecret = corpsecret
         self.cache = cache or AccessTokenDiskcacheCache()
@@ -95,7 +95,7 @@ class Client:
 
         Raises
         ------
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         cache_key = self._cache_key()
@@ -124,7 +124,7 @@ class Client:
         try:
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"gettoken request failed: {exc}") from exc
+            raise ConnectionError(f"gettoken request failed: {exc}") from exc
 
         data = resp.json()
         return AccessTokenResponse(**data)
@@ -152,9 +152,9 @@ class AsyncClient:
     ) -> None:
         """使用企业凭证、缓存配置和 HTTP 参数初始化异步客户端。"""
         if not corpid:
-            raise ConfigError("corpid is required")
+            raise ValueError("corpid is required")
         if not corpsecret:
-            raise ConfigError("corpsecret is required")
+            raise ValueError("corpsecret is required")
         self.corpid = corpid
         self.corpsecret = corpsecret
         self.cache = cache or AccessTokenDiskcacheCache()
@@ -202,7 +202,7 @@ class AsyncClient:
 
         Raises
         ------
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         cache_key = self._cache_key()
@@ -231,7 +231,7 @@ class AsyncClient:
         try:
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"gettoken request failed: {exc}") from exc
+            raise ConnectionError(f"gettoken request failed: {exc}") from exc
 
         data = resp.json()
         return AccessTokenResponse(**data)

{py_wecom_toolkit-4.2.3 → py_wecom_toolkit-4.2.4}/src/py_wecom_toolkit/server/_models.py

@@ -1,20 +1,12 @@
 #!/usr/bin/env python3
 # -*- coding: UTF-8 -*-
-"""企业应用服务异常及 API 响应模型。"""
+"""企业应用服务 API 响应模型。"""
 
 from __future__ import annotations
 
 from pydantic import BaseModel, ConfigDict
 
 
-class ConfigError(Exception):
-    """凭证或客户端配置无效时抛出。"""
-
-
-class NetworkError(Exception):
-    """企业微信 API 网络请求失败时抛出。"""
-
-
 class BaseResponse(BaseModel):
     """企业微信 API 响应的公共字段，并保留服务端附加字段。"""
 

{py_wecom_toolkit-4.2.3 → py_wecom_toolkit-4.2.4}/src/py_wecom_toolkit/server/materials/_clients.py

@@ -11,7 +11,6 @@ import httpx
 
 from .._clients import AsyncClient as BaseAsyncClient
 from .._clients import Client as BaseClient
-from .._models import ConfigError, NetworkError
 from ._models import MaterialTypeLiteral, UploadImgResponse, UploadResponse
 
 
@@ -78,14 +77,14 @@ class Client(BaseClient):
 
         Raises
         ------
-        ConfigError
+        ValueError
             当 access_token 获取失败时抛出。
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         token_response = self.get_access_token()
         if not token_response.ok:
-            raise ConfigError(
+            raise ValueError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
                 f"errmsg={token_response.errmsg}"
             )
@@ -104,10 +103,10 @@ class Client(BaseClient):
             resp = self._client.post(url, files=files)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"upload material request failed: {exc}") from exc
+            raise ConnectionError(f"upload material request failed: {exc}") from exc
         data = resp.json()
         if data.get("errcode", 0) != 0:
-            raise NetworkError(
+            raise ConnectionError(
                 f"upload material failed: errcode={data.get('errcode')}, "
                 f"errmsg={data.get('errmsg')}"
             )
@@ -136,14 +135,14 @@ class Client(BaseClient):
 
         Raises
         ------
-        ConfigError
+        ValueError
             当 access_token 获取失败时抛出。
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         token_response = self.get_access_token()
         if not token_response.ok:
-            raise ConfigError(
+            raise ValueError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
                 f"errmsg={token_response.errmsg}"
             )
@@ -162,10 +161,10 @@ class Client(BaseClient):
             resp = self._client.post(url, files=files)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"upload image request failed: {exc}") from exc
+            raise ConnectionError(f"upload image request failed: {exc}") from exc
         data = resp.json()
         if data.get("errcode", 0) != 0:
-            raise NetworkError(
+            raise ConnectionError(
                 f"upload image failed: errcode={data.get('errcode')}, "
                 f"errmsg={data.get('errmsg')}"
             )
@@ -179,7 +178,7 @@ class Client(BaseClient):
 
         文档: https://developer.work.weixin.qq.com/document/path/90254
 
-        正确时返回媒体文件二进制流；错误时返回 JSON 响应，会抛出异常。
+        正确时返回媒体文件二进制流；错误时返回 JSON 响应，会抛出内置异常。
 
         Parameters
         ----------
@@ -188,14 +187,14 @@ class Client(BaseClient):
 
         Raises
         ------
-        ConfigError
+        ValueError
             当 access_token 获取失败时抛出。
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         token_response = self.get_access_token()
         if not token_response.ok:
-            raise ConfigError(
+            raise ValueError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
                 f"errmsg={token_response.errmsg}"
             )
@@ -205,14 +204,14 @@ class Client(BaseClient):
             resp = self._client.get(url)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"download material request failed: {exc}") from exc
+            raise ConnectionError(f"download material request failed: {exc}") from exc
 
         # 企业微信下载接口：成功返回二进制流，错误返回 JSON
         content_type = resp.headers.get("content-type", "")
         if "application/json" in content_type:
             data = resp.json()
             if data.get("errcode", 0) != 0:
-                raise NetworkError(
+                raise ConnectionError(
                     f"download material failed: errcode={data.get('errcode')}, "
                     f"errmsg={data.get('errmsg')}"
                 )
@@ -282,14 +281,14 @@ class AsyncClient(BaseAsyncClient):
 
         Raises
         ------
-        ConfigError
+        ValueError
             当 access_token 获取失败时抛出。
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         token_response = await self.get_access_token()
         if not token_response.ok:
-            raise ConfigError(
+            raise ValueError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
                 f"errmsg={token_response.errmsg}"
             )
@@ -308,10 +307,10 @@ class AsyncClient(BaseAsyncClient):
             resp = await self._client.post(url, files=files)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"upload material request failed: {exc}") from exc
+            raise ConnectionError(f"upload material request failed: {exc}") from exc
         data = resp.json()
         if data.get("errcode", 0) != 0:
-            raise NetworkError(
+            raise ConnectionError(
                 f"upload material failed: errcode={data.get('errcode')}, "
                 f"errmsg={data.get('errmsg')}"
             )
@@ -338,14 +337,14 @@ class AsyncClient(BaseAsyncClient):
 
         Raises
         ------
-        ConfigError
+        ValueError
             当 access_token 获取失败时抛出。
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         token_response = await self.get_access_token()
         if not token_response.ok:
-            raise ConfigError(
+            raise ValueError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
                 f"errmsg={token_response.errmsg}"
             )
@@ -364,10 +363,10 @@ class AsyncClient(BaseAsyncClient):
             resp = await self._client.post(url, files=files)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"upload image request failed: {exc}") from exc
+            raise ConnectionError(f"upload image request failed: {exc}") from exc
         data = resp.json()
         if data.get("errcode", 0) != 0:
-            raise NetworkError(
+            raise ConnectionError(
                 f"upload image failed: errcode={data.get('errcode')}, "
                 f"errmsg={data.get('errmsg')}"
             )
@@ -381,7 +380,7 @@ class AsyncClient(BaseAsyncClient):
 
         文档: https://developer.work.weixin.qq.com/document/path/90254
 
-        正确时返回媒体文件二进制流；错误时返回 JSON 响应，会抛出异常。
+        正确时返回媒体文件二进制流；错误时返回 JSON 响应，会抛出内置异常。
 
         Parameters
         ----------
@@ -390,14 +389,14 @@ class AsyncClient(BaseAsyncClient):
 
         Raises
         ------
-        ConfigError
+        ValueError
             当 access_token 获取失败时抛出。
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         token_response = await self.get_access_token()
         if not token_response.ok:
-            raise ConfigError(
+            raise ValueError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
                 f"errmsg={token_response.errmsg}"
             )
@@ -407,14 +406,14 @@ class AsyncClient(BaseAsyncClient):
             resp = await self._client.get(url)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"download material request failed: {exc}") from exc
+            raise ConnectionError(f"download material request failed: {exc}") from exc
 
         # 企业微信下载接口：成功返回二进制流，错误返回 JSON
         content_type = resp.headers.get("content-type", "")
         if "application/json" in content_type:
             data = resp.json()
             if data.get("errcode", 0) != 0:
-                raise NetworkError(
+                raise ConnectionError(
                     f"download material failed: errcode={data.get('errcode')}, "
                     f"errmsg={data.get('errmsg')}"
                 )

{py_wecom_toolkit-4.2.3 → py_wecom_toolkit-4.2.4}/src/py_wecom_toolkit/server/messages/_clients.py

@@ -10,7 +10,7 @@ import httpx
 
 from .._clients import AsyncClient as BaseAsyncClient
 from .._clients import Client as BaseClient
-from .._models import BaseResponse, ConfigError, NetworkError
+from .._models import BaseResponse
 from ._msgtypes import BaseMessage
 
 
@@ -73,18 +73,18 @@ class Client(BaseClient):
 
         Raises
         ------
-        ConfigError
+        ValueError
             当 access_token 获取失败或 agentid 为空时抛出。
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         resolved_agentid = agentid if agentid is not None else self.agentid
         if resolved_agentid is None:
-            raise ConfigError("agentid is required")
+            raise ValueError("agentid is required")
 
         token_response = self.get_access_token()
         if not token_response.ok:
-            raise ConfigError(
+            raise ValueError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
                 f"errmsg={token_response.errmsg}"
             )
@@ -96,7 +96,7 @@ class Client(BaseClient):
             resp = self._client.post(url, json=payload)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"send message request failed: {exc}") from exc
+            raise ConnectionError(f"send message request failed: {exc}") from exc
         return BaseResponse(**resp.json())
 
 
@@ -159,18 +159,18 @@ class AsyncClient(BaseAsyncClient):
 
         Raises
         ------
-        ConfigError
+        ValueError
             当 access_token 获取失败或 agentid 为空时抛出。
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         resolved_agentid = agentid if agentid is not None else self.agentid
         if resolved_agentid is None:
-            raise ConfigError("agentid is required")
+            raise ValueError("agentid is required")
 
         token_response = await self.get_access_token()
         if not token_response.ok:
-            raise ConfigError(
+            raise ValueError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
                 f"errmsg={token_response.errmsg}"
             )
@@ -182,5 +182,5 @@ class AsyncClient(BaseAsyncClient):
             resp = await self._client.post(url, json=payload)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"send message request failed: {exc}") from exc
+            raise ConnectionError(f"send message request failed: {exc}") from exc
         return BaseResponse(**resp.json())

{py_wecom_toolkit-4.2.3 → py_wecom_toolkit-4.2.4}/src/py_wecom_toolkit/webhook/__init__.py

@@ -7,10 +7,7 @@ from __future__ import annotations
 from ._clients import AsyncClient as WebhookAsyncClient
 from ._clients import Client as WebhookClient
 from ._models import BaseResponse as WebhookBaseResponse
-from ._models import ConfigError as WebhookConfigError
-from ._models import NetworkError as WebhookNetworkError
 from ._models import Response as WebhookResponse
-from ._models import UploadError as WebhookUploadError
 from ._models import UploadMediaResponse as WebhookUploadMediaResponse
 from ._msgtypes import Article as WebhookArticle
 from ._msgtypes import CardAction as WebhookCardAction
@@ -44,7 +41,6 @@ __all__ = [
     "WebhookBaseResponse",
     "WebhookCardAction",
     "WebhookClient",
-    "WebhookConfigError",
     "WebhookEmphasisContent",
     "WebhookFileContent",
     "WebhookFileMsgType",
@@ -57,7 +53,6 @@ __all__ = [
     "WebhookMarkdownMsgType",
     "WebhookMarkdownV2Content",
     "WebhookMarkdownV2MsgType",
-    "WebhookNetworkError",
     "WebhookNewsContent",
     "WebhookNewsMsgType",
     "WebhookQuoteArea",
@@ -67,7 +62,6 @@ __all__ = [
     "WebhookTemplateCardMsgType",
     "WebhookTextContent",
     "WebhookTextMsgType",
-    "WebhookUploadError",
     "WebhookUploadMediaResponse",
     "WebhookVoiceContent",
     "WebhookVoiceMsgType",

{py_wecom_toolkit-4.2.3 → py_wecom_toolkit-4.2.4}/src/py_wecom_toolkit/webhook/_clients.py

@@ -11,10 +11,7 @@ import httpx
 from pydantic import BaseModel
 
 from ._models import (
-    ConfigError,
-    NetworkError,
     Response,
-    UploadError,
     UploadMediaResponse,
 )
 from ._msgtypes import (
@@ -61,7 +58,7 @@ class Client:
 
     Raises
     ------
-    ConfigError
+    ValueError
         当 ``key`` 为空时抛出。
     """
 
@@ -76,7 +73,7 @@ class Client:
         httpx_client_kwargs: Optional[dict[str, Any]] = None,
     ) -> None:
         if not key:
-            raise ConfigError("webhook key is required")
+            raise ValueError("webhook key is required")
         self.key = key
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
@@ -136,7 +133,7 @@ class Client:
 
         Raises
         ------
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         payload = message.model_dump(mode="json", exclude_none=True)
@@ -144,7 +141,7 @@ class Client:
             resp = self._client.post(self._send_url(), json=payload)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"request failed: {exc}") from exc
+            raise ConnectionError(f"request failed: {exc}") from exc
         return Response(**resp.json())
 
     def send_text(
@@ -335,9 +332,7 @@ class Client:
 
         Raises
         ------
-        UploadError
-            当上传失败或 API 返回 errcode 不为 0 时抛出。
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         if isinstance(file, (str, Path)):
@@ -353,11 +348,12 @@ class Client:
             resp = self._client.post(self._upload_url(media_type), files=files)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"upload request failed: {exc}") from exc
+            raise ConnectionError(f"upload request failed: {exc}") from exc
         data = resp.json()
         if data.get("errcode", 0) != 0:
-            raise UploadError(
-                data.get("errmsg", "upload failed"), errcode=data.get("errcode", -1)
+            raise ConnectionError(
+                f"upload failed: {data.get('errmsg', 'upload failed')} "
+                f"(errcode: {data.get('errcode', -1)})"
             )
         return UploadMediaResponse(**data)
 
@@ -395,7 +391,7 @@ class AsyncClient:
         httpx_client_kwargs: Optional[dict[str, Any]] = None,
     ) -> None:
         if not key:
-            raise ConfigError("webhook key is required")
+            raise ValueError("webhook key is required")
         self.key = key
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
@@ -455,7 +451,7 @@ class AsyncClient:
 
         Raises
         ------
-        NetworkError
+        ConnectionError
             当网络请求失败时抛出。
         """
         payload = message.model_dump(mode="json", exclude_none=True)
@@ -463,7 +459,7 @@ class AsyncClient:
             resp = await self._client.post(self._send_url(), json=payload)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"request failed: {exc}") from exc
+            raise ConnectionError(f"request failed: {exc}") from exc
         return Response(**resp.json())
 
     async def send_text(
@@ -665,10 +661,11 @@ class AsyncClient:
             resp = await self._client.post(self._upload_url(media_type), files=files)
             resp.raise_for_status()
         except httpx.RequestError as exc:
-            raise NetworkError(f"upload request failed: {exc}") from exc
+            raise ConnectionError(f"upload request failed: {exc}") from exc
         data = resp.json()
         if data.get("errcode", 0) != 0:
-            raise UploadError(
-                data.get("errmsg", "upload failed"), errcode=data.get("errcode", -1)
+            raise ConnectionError(
+                f"upload failed: {data.get('errmsg', 'upload failed')} "
+                f"(errcode: {data.get('errcode', -1)})"
             )
         return UploadMediaResponse(**data)

{py_wecom_toolkit-4.2.3 → py_wecom_toolkit-4.2.4}/src/py_wecom_toolkit/webhook/_models.py

@@ -1,36 +1,12 @@
 #!/usr/bin/env python3
 # -*- coding: UTF-8 -*-
-"""Webhook 异常及 API 响应模型。"""
+"""Webhook API 响应模型。"""
 
 from __future__ import annotations
 
-from typing import Optional
-
 from pydantic import BaseModel, ConfigDict
 
 
-class ConfigError(Exception):
-    """Webhook 客户端配置无效时抛出。"""
-
-
-class NetworkError(Exception):
-    """Webhook API 网络请求失败时抛出。"""
-
-
-class UploadError(Exception):
-    """文件上传失败时抛出，包含接口错误信息及可用的错误码。"""
-
-    def __init__(self, message: str, errcode: Optional[int] = None) -> None:
-        super().__init__(message)
-        self.message = message
-        self.errcode = errcode
-
-    def __str__(self) -> str:
-        if self.errcode is not None:
-            return f"[{self.errcode}] {self.message}"
-        return self.message
-
-
 class BaseResponse(BaseModel):
     """企业微信 API 响应的公共字段；保留服务端返回的额外字段。"""