py-wecom-toolkit 4.0.2__tar.gz → 4.0.4__tar.gz

{py_wecom_toolkit-4.0.2 → py_wecom_toolkit-4.0.4}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.5
 Name: py_wecom_toolkit
-Version: 4.0.2
+Version: 4.0.4
 Summary: Enterprise WeChat (WeCom) API toolkit for Python / 企业微信（WeCom）API 工具包
-Project-URL: homepage, https://gitee.com/guolei19850528/py_wecom_toolkit
-Project-URL: repository, https://gitee.com/guolei19850528/py_wecom_toolkit
+Project-URL: HomePage, https://gitee.com/guolei19850528/py_wecom_toolkit
+Project-URL: Repository, https://gitee.com/guolei19850528/py_wecom_toolkit
 Author-email: 郭磊 <174000902@qq.com>
 License: MIT
 License-File: LICENSE
@@ -58,7 +58,7 @@ Description-Content-Type: text/markdown
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-[中文文档](readme.md) | [English Documentation](readme.en.md)
+[中文文档](README.md) | [English Documentation](README.en.md)
 
 ## 📄 文档
 
@@ -88,7 +88,7 @@ py_wecom_toolkit/
 27: │   │   │   └── AsyncClient      # 异步客户端
 29: │   │   ├── exception.py         # 异常类定义（Error, ConfigError, NetworkError）
 30: │   │   ├── response.py          # 响应模型（BaseResponse, AccessTokenResponse）
-31: │   │   ├── cache.py             # 缓存管理（TokenCache, MemoryCache, DiskCache, RedisCache, build_cache_key）
+31: │   │   ├── cache.py             # 缓存管理（AccessTokenCache, AccessTokenMemoryCache, AccessTokenDiskcacheCache, AccessTokenRedisCache, build_access_token_cache_key）
 32: │   │   ├── message/             # 消息发送子模块
 33: │   │   │   ├── __init__.py
 34: │   │   │   ├── client.py        # WeCom 消息客户端（同步/异步）
@@ -134,7 +134,7 @@ py_wecom_toolkit/
 | `server/client.py` | 企业微信 access_token 获取客户端，支持同步和异步调用，自动缓存 access_token |
 | `server/exception.py` | 定义基础异常类 `Error`、`ConfigError`、`NetworkError` |
 | `server/response.py` | 定义响应模型 `BaseResponse`、`AccessTokenResponse`，支持 `ok` 属性判断 |
-| `server/cache.py` | 缓存抽象层，支持内存缓存（`MemoryCache`）、磁盘缓存（`DiskCache`）、Redis 缓存（`RedisCache`） |
+| `server/cache.py` | 缓存抽象层，支持内存缓存（`AccessTokenMemoryCache`）、磁盘缓存（`AccessTokenDiskcacheCache`）、Redis 缓存（`AccessTokenRedisCache`） |
 | `server/message/client.py` | 企业微信应用消息客户端，支持文本、markdown、图片、图文、文件、语音、模版卡片等消息类型 |
 | `server/message/msgtype.py` | 消息类型定义，支持 text、markdown、markdown_v2、image、news、file、voice、template_card |
 | `server/material/client.py` | 素材管理客户端，支持上传临时素材、上传图片、下载素材 |
@@ -166,10 +166,10 @@ uv add py_wecom_toolkit
 pip install py_wecom_toolkit
 ```
 
-### 方式三：从源码安装
+### 方式三：从源码安装（dev 分支）
 
 ```bash
-git clone https://gitee.com/guolei19850528/py_wecom_toolkit.git
+git clone -b dev https://gitee.com/guolei19850528/py_wecom_toolkit.git
 cd py_wecom_toolkit
 uv sync --all-groups
 ```
@@ -194,7 +194,7 @@ from py_wecom_toolkit.server.response import AccessTokenResponse
 
 # 初始化客户端
 with Client(corpid=CORP_ID, corpsecret=CORP_SECRET) as client:
-    resp: AccessTokenResponse = client.get_token()
+    resp: AccessTokenResponse = client.get_access_token()
     if resp.ok:
         print(f"access_token: {resp.access_token}")
         print(f"expires_in: {resp.expires_in} 秒")
@@ -211,7 +211,7 @@ from py_wecom_toolkit.server.response import AccessTokenResponse
 
 async def main():
     async with AsyncClient(corpid=CORP_ID, corpsecret=CORP_SECRET) as client:
-        resp: AccessTokenResponse = await client.get_token()
+        resp: AccessTokenResponse = await client.get_access_token()
         if resp.ok:
             print(f"access_token: {resp.access_token}")
             print(f"expires_in: {resp.expires_in} 秒")

{py_wecom_toolkit-4.0.2 → py_wecom_toolkit-4.0.4}/README.md

@@ -2,7 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-[中文文档](readme.md) | [English Documentation](readme.en.md)
+[中文文档](README.md) | [English Documentation](README.en.md)
 
 ## 📄 文档
 
@@ -32,7 +32,7 @@ py_wecom_toolkit/
 27: │   │   │   └── AsyncClient      # 异步客户端
 29: │   │   ├── exception.py         # 异常类定义（Error, ConfigError, NetworkError）
 30: │   │   ├── response.py          # 响应模型（BaseResponse, AccessTokenResponse）
-31: │   │   ├── cache.py             # 缓存管理（TokenCache, MemoryCache, DiskCache, RedisCache, build_cache_key）
+31: │   │   ├── cache.py             # 缓存管理（AccessTokenCache, AccessTokenMemoryCache, AccessTokenDiskcacheCache, AccessTokenRedisCache, build_access_token_cache_key）
 32: │   │   ├── message/             # 消息发送子模块
 33: │   │   │   ├── __init__.py
 34: │   │   │   ├── client.py        # WeCom 消息客户端（同步/异步）
@@ -78,7 +78,7 @@ py_wecom_toolkit/
 | `server/client.py` | 企业微信 access_token 获取客户端，支持同步和异步调用，自动缓存 access_token |
 | `server/exception.py` | 定义基础异常类 `Error`、`ConfigError`、`NetworkError` |
 | `server/response.py` | 定义响应模型 `BaseResponse`、`AccessTokenResponse`，支持 `ok` 属性判断 |
-| `server/cache.py` | 缓存抽象层，支持内存缓存（`MemoryCache`）、磁盘缓存（`DiskCache`）、Redis 缓存（`RedisCache`） |
+| `server/cache.py` | 缓存抽象层，支持内存缓存（`AccessTokenMemoryCache`）、磁盘缓存（`AccessTokenDiskcacheCache`）、Redis 缓存（`AccessTokenRedisCache`） |
 | `server/message/client.py` | 企业微信应用消息客户端，支持文本、markdown、图片、图文、文件、语音、模版卡片等消息类型 |
 | `server/message/msgtype.py` | 消息类型定义，支持 text、markdown、markdown_v2、image、news、file、voice、template_card |
 | `server/material/client.py` | 素材管理客户端，支持上传临时素材、上传图片、下载素材 |
@@ -110,10 +110,10 @@ uv add py_wecom_toolkit
 pip install py_wecom_toolkit
 ```
 
-### 方式三：从源码安装
+### 方式三：从源码安装（dev 分支）
 
 ```bash
-git clone https://gitee.com/guolei19850528/py_wecom_toolkit.git
+git clone -b dev https://gitee.com/guolei19850528/py_wecom_toolkit.git
 cd py_wecom_toolkit
 uv sync --all-groups
 ```
@@ -138,7 +138,7 @@ from py_wecom_toolkit.server.response import AccessTokenResponse
 
 # 初始化客户端
 with Client(corpid=CORP_ID, corpsecret=CORP_SECRET) as client:
-    resp: AccessTokenResponse = client.get_token()
+    resp: AccessTokenResponse = client.get_access_token()
     if resp.ok:
         print(f"access_token: {resp.access_token}")
         print(f"expires_in: {resp.expires_in} 秒")
@@ -155,7 +155,7 @@ from py_wecom_toolkit.server.response import AccessTokenResponse
 
 async def main():
     async with AsyncClient(corpid=CORP_ID, corpsecret=CORP_SECRET) as client:
-        resp: AccessTokenResponse = await client.get_token()
+        resp: AccessTokenResponse = await client.get_access_token()
         if resp.ok:
             print(f"access_token: {resp.access_token}")
             print(f"expires_in: {resp.expires_in} 秒")

{py_wecom_toolkit-4.0.2 → py_wecom_toolkit-4.0.4}/py_wecom_toolkit/server/cache.py

@@ -5,18 +5,18 @@ import time
 from abc import ABC, abstractmethod
 from typing import Optional
 
-CACHE_KEY_PREFIX = "py_wecom_toolkit:server:access_token"
+ACCESS_TOKEN_CACHE_KEY_PREFIX = "py_wecom_toolkit:server:access_token"
 
 
-def build_cache_key(corpid: str) -> str:
+def build_access_token_cache_key(corpid: str) -> str:
     """构造 access_token 缓存 key。
 
     格式: py_wecom_toolkit:server:access_token:{corpid}
     """
-    return f"{CACHE_KEY_PREFIX}:{corpid}"
+    return f"{ACCESS_TOKEN_CACHE_KEY_PREFIX}:{corpid}"
 
 
-class TokenCache(ABC):
+class AccessTokenCache(ABC):
     """access_token 缓存抽象基类。"""
 
     @abstractmethod
@@ -28,7 +28,7 @@ class TokenCache(ABC):
         """设置缓存值，ttl 为秒。"""
 
 
-class MemoryCache(TokenCache):
+class AccessTokenMemoryCache(AccessTokenCache):
     """内存缓存实现（默认，不依赖第三方库）。"""
 
     def __init__(self) -> None:
@@ -48,7 +48,7 @@ class MemoryCache(TokenCache):
         self._store[key] = (value, time.time() + ttl)
 
 
-class DiskCache(TokenCache):
+class AccessTokenDiskcacheCache(AccessTokenCache):
     """基于 diskcache 的缓存实现。"""
 
     def __init__(self, directory: str = ".cache/py_wecom_toolkit") -> None:
@@ -63,7 +63,7 @@ class DiskCache(TokenCache):
         self._cache.set(key, value, expire=ttl)
 
 
-class RedisCache(TokenCache):
+class AccessTokenRedisCache(AccessTokenCache):
     """基于 redis 的缓存实现。"""
 
     def __init__(

{py_wecom_toolkit-4.0.2 → py_wecom_toolkit-4.0.4}/py_wecom_toolkit/server/client.py

@@ -8,7 +8,7 @@ import httpx
 
 from .exception import ConfigError, NetworkError
 from .response import AccessTokenResponse
-from .cache import TokenCache, DiskCache, build_cache_key
+from .cache import AccessTokenCache, AccessTokenDiskcacheCache, build_access_token_cache_key
 
 
 class Client:
@@ -35,7 +35,7 @@ class Client:
         corpid: str,
         corpsecret: str,
         *,
-        cache: Optional[TokenCache] = None,
+        cache: Optional[AccessTokenCache] = None,
         base_url: str = "https://qyapi.weixin.qq.com",
         timeout: float = 30.0,
         **httpx_kwargs: Any,
@@ -46,7 +46,7 @@ class Client:
             raise ConfigError("corpsecret is required")
         self.corpid = corpid
         self.corpsecret = corpsecret
-        self.cache = cache or DiskCache()
+        self.cache = cache or AccessTokenDiskcacheCache()
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
         self._client = httpx.Client(
@@ -70,9 +70,9 @@ class Client:
         self._client.close()
 
     def _cache_key(self) -> str:
-        return build_cache_key(self.corpid)
+        return build_access_token_cache_key(self.corpid)
 
-    def get_token(self, force_refresh: bool = False) -> AccessTokenResponse:
+    def get_access_token(self, force_refresh: bool = False) -> AccessTokenResponse:
         """获取 access_token。
 
         优先从缓存读取，缓存未命中或 force_refresh 为 True 时重新获取。
@@ -100,12 +100,12 @@ class Client:
                     expires_in=self._get_ttl(),
                 )
 
-        response = self._fetch_token()
+        response = self._fetch_access_token()
         if response.ok:
             self.cache.set(cache_key, response.access_token, ttl=self._get_ttl())
         return response
 
-    def _fetch_token(self) -> AccessTokenResponse:
+    def _fetch_access_token(self) -> AccessTokenResponse:
         resp = self._client.get(
             "/cgi-bin/gettoken",
             params={"corpid": self.corpid, "corpsecret": self.corpsecret},
@@ -131,7 +131,7 @@ class AsyncClient:
         corpid: str,
         corpsecret: str,
         *,
-        cache: Optional[TokenCache] = None,
+        cache: Optional[AccessTokenCache] = None,
         base_url: str = "https://qyapi.weixin.qq.com",
         timeout: float = 30.0,
         **httpx_kwargs: Any,
@@ -142,7 +142,7 @@ class AsyncClient:
             raise ConfigError("corpsecret is required")
         self.corpid = corpid
         self.corpsecret = corpsecret
-        self.cache = cache or DiskCache()
+        self.cache = cache or AccessTokenDiskcacheCache()
         self.base_url = base_url.rstrip("/")
         self.timeout = timeout
         self._client = httpx.AsyncClient(
@@ -166,9 +166,9 @@ class AsyncClient:
         await self._client.aclose()
 
     def _cache_key(self) -> str:
-        return build_cache_key(self.corpid)
+        return build_access_token_cache_key(self.corpid)
 
-    async def get_token(self, force_refresh: bool = False) -> AccessTokenResponse:
+    async def get_access_token(self, force_refresh: bool = False) -> AccessTokenResponse:
         """获取 access_token（异步）。
 
         优先从缓存读取，缓存未命中或 force_refresh 为 True 时重新获取。
@@ -196,12 +196,12 @@ class AsyncClient:
                     expires_in=self._get_ttl(),
                 )
 
-        response = await self._fetch_token()
+        response = await self._fetch_access_token()
         if response.ok:
             self.cache.set(cache_key, response.access_token, ttl=self._get_ttl())
         return response
 
-    async def _fetch_token(self) -> AccessTokenResponse:
+    async def _fetch_access_token(self) -> AccessTokenResponse:
         resp = await self._client.get(
             "/cgi-bin/gettoken",
             params={"corpid": self.corpid, "corpsecret": self.corpsecret},

{py_wecom_toolkit-4.0.2 → py_wecom_toolkit-4.0.4}/py_wecom_toolkit/server/material/client.py

@@ -80,7 +80,7 @@ class Client(BaseClient):
         NetworkError
             当网络请求失败时抛出。
         """
-        token_response = self.get_token()
+        token_response = self.get_access_token()
         if not token_response.ok:
             raise ConfigError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
@@ -138,7 +138,7 @@ class Client(BaseClient):
         NetworkError
             当网络请求失败时抛出。
         """
-        token_response = self.get_token()
+        token_response = self.get_access_token()
         if not token_response.ok:
             raise ConfigError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
@@ -190,7 +190,7 @@ class Client(BaseClient):
         NetworkError
             当网络请求失败时抛出。
         """
-        token_response = self.get_token()
+        token_response = self.get_access_token()
         if not token_response.ok:
             raise ConfigError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
@@ -283,7 +283,7 @@ class AsyncClient(BaseAsyncClient):
         NetworkError
             当网络请求失败时抛出。
         """
-        token_response = await self.get_token()
+        token_response = await self.get_access_token()
         if not token_response.ok:
             raise ConfigError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
@@ -339,7 +339,7 @@ class AsyncClient(BaseAsyncClient):
         NetworkError
             当网络请求失败时抛出。
         """
-        token_response = await self.get_token()
+        token_response = await self.get_access_token()
         if not token_response.ok:
             raise ConfigError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
@@ -391,7 +391,7 @@ class AsyncClient(BaseAsyncClient):
         NetworkError
             当网络请求失败时抛出。
         """
-        token_response = await self.get_token()
+        token_response = await self.get_access_token()
         if not token_response.ok:
             raise ConfigError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "

{py_wecom_toolkit-4.0.2 → py_wecom_toolkit-4.0.4}/py_wecom_toolkit/server/message/client.py

@@ -78,7 +78,7 @@ class Client(BaseClient):
         if resolved_agentid is None:
             raise ConfigError("agentid is required")
 
-        token_response = self.get_token()
+        token_response = self.get_access_token()
         if not token_response.ok:
             raise ConfigError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "
@@ -161,7 +161,7 @@ class AsyncClient(BaseAsyncClient):
         if resolved_agentid is None:
             raise ConfigError("agentid is required")
 
-        token_response = await self.get_token()
+        token_response = await self.get_access_token()
         if not token_response.ok:
             raise ConfigError(
                 f"获取 access_token 失败: errcode={token_response.errcode}, "

{py_wecom_toolkit-4.0.2 → py_wecom_toolkit-4.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "py_wecom_toolkit"
-version = "4.0.2"
+version = "4.0.4"
 description = "Enterprise WeChat (WeCom) API toolkit for Python / 企业微信（WeCom）API 工具包"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -46,8 +46,8 @@ dependencies = [
 ]
 
 [project.urls]
-homepage = "https://gitee.com/guolei19850528/py_wecom_toolkit"
-repository = "https://gitee.com/guolei19850528/py_wecom_toolkit"
+HomePage = "https://gitee.com/guolei19850528/py_wecom_toolkit"
+Repository = "https://gitee.com/guolei19850528/py_wecom_toolkit"
 
 [project.optional-dependencies]
 dev = [