py-wecom-toolkit 1.0.0__py3-none-any.whl

py_wecom_toolkit/__init__.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+py_wecom - 企业微信API Python SDK
+
+提供企业微信API的完整Python封装，支持以下功能模块：
+
+1. **Webhook模块** (`py_wecom.webhook`)
+   - 企业微信Webhook消息发送
+   - 支持文本、Markdown、图片、图文、文件、语音、模板卡片等消息类型
+   - 支持同步和异步两种调用方式
+
+2. **Server模块** (`py_wecom.server`)
+   - 企业微信Server API集成
+   - 支持获取access_token、发送消息、上传素材等功能
+   - 支持同步和异步两种调用方式
+
+快速开始：
+
+**Webhook使用示例**：
+    >>>     from py_wecom_toolkit.webhook import Webhook
+    >>>     from py_wecom_toolkit.webhook.messages import Text, TextContent
+    >>>     webhook = Webhook(key="your_webhook_key")
+    >>>     response = webhook.send_text(content=Text(text=TextContent(content="Hello World")))
+    >>>     print(response.json())
+
+**Server使用示例**：
+    >>>     from py_wecom_toolkit.server import Base
+    >>>     from py_wecom_toolkit.server.messages import Sender, Text, TextContent
+    >>>     from diskcache import Cache
+    >>>     diskcache_default = Cache()
+    >>>     server = Base(corpid="your_corpid", corpsecret="your_corpsecret", cache_config={"instance": diskcache_default})
+    >>>     server = Base(corpid="your_corpid", corpsecret="your_corpsecret")
+    >>>     server.refresh_access_token()
+    >>>     sender = Sender(corpid="your_corpid", corpsecret="your_corpsecret", agentid="your_agentid", cache_config={"instance": diskcache_default})
+    >>>     sender.refresh_access_token()
+    >>>     response = sender.send_text(content=Text(text=TextContent(content="Hello from py-wecom!")), agentid="your_agentid")
+    >>>     print(response.json())
+
+参考文档：
+- Webhook API: https://developer.work.weixin.qq.com/document/path/91770
+- Server API: https://developer.work.weixin.qq.com/document/path/90664
+"""

py_wecom_toolkit/server/__init__.py

@@ -0,0 +1,559 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+企业微信Server模块
+
+提供企业微信Server API的客户端实现，支持同步和异步两种模式。
+
+主要功能：
+- 获取access_token（支持缓存）
+- 获取API域名IP
+- 获取回调IP
+
+参考文档：
+- https://developer.work.weixin.qq.com/document/path/90664
+"""
+
+from typing import Optional, Union
+
+import diskcache
+import httpx
+import redis
+from py_httpx_toolkit import Httpx
+
+from .utils import build_success_instance, success_is_valid
+
+
+class Base(Httpx):
+    """
+    企业微信Server API基础客户端类
+
+    提供企业微信Server API的核心功能，包括access_token管理、IP查询等。
+    支持同步和异步两种模式，支持使用diskcache或Redis缓存access_token。
+
+    Attributes:
+        base_url: 企业微信API基础URL，默认为官方地址
+        corpid: 企业ID，可在企业微信管理后台获取
+        corpsecret: 应用密钥，可在企业微信管理后台获取
+        agentid: 企业应用ID，可在企业微信管理后台获取
+        cache_config: 缓存配置字典，包含instance（缓存实例）、key（缓存键名）、expire（过期时间）
+        client_kwargs: HTTP客户端配置参数
+        access_token: 当前的access_token
+
+    代码演示：
+        >>>     from py_wecom_toolkit.server import Base
+        >>>     server = Base(corpid="your_corpid", corpsecret="your_corpsecret")
+        >>>     server.refresh_access_token()
+        >>>     print(server.access_token)
+    """
+
+    def __init__(
+            self,
+            base_url: Optional[str] = "https://qyapi.weixin.qq.com/",
+            corpid: Optional[str] = None,
+            corpsecret: Optional[str] = None,
+            agentid: Optional[Union[str, int]] = None,
+            cache_config: Optional[dict] = None,
+            client_kwargs: Optional[dict] = None,
+    ):
+        # 设置基础URL，去除末尾斜杠以确保URL格式统一
+        self.base_url = base_url[:-1] if base_url.endswith("/") else base_url
+        # 设置企业ID，若为None则设为空字符串
+        self.corpid = corpid or ""
+        # 设置应用密钥，若为None则设为空字符串
+        self.corpsecret = corpsecret or ""
+        # 设置企业应用ID，若为None则设为空字符串
+        self.agentid = agentid or ""
+        # 设置缓存配置，若为None则设为空字典
+        self.cache_config = cache_config or {}
+        # 合并默认缓存配置与用户配置，用户配置优先覆盖默认值
+        # 默认配置：不使用缓存实例，缓存键名为py_wecom_server_{corpid}_{agentid}，过期时间7100秒
+        self.cache_config = {
+            **{
+                "instance": None,
+                "key": f"py_wecom_server_{self.corpid}_{self.agentid}",
+                "expire": 7100,
+            },
+            **self.cache_config,
+        }
+        # 设置HTTP客户端配置，若为None则设为空字典
+        self.client_kwargs = client_kwargs or {}
+        # 合并默认客户端配置与用户配置，用户配置优先覆盖默认值
+        # 默认配置：基础URL、超时时间60秒
+        self.client_kwargs = {
+            **{
+                "base_url": self.base_url,
+                "timeout": 60,
+                "verify": False,
+            },
+            **self.client_kwargs,
+        }
+        # 初始化access_token为空字符串
+        self.access_token = None
+
+    def gettoken(
+            self,
+            client: Optional[httpx.Client] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        同步获取access_token
+
+        @see: https://developer.work.weixin.qq.com/document/path/91039
+
+        调用企业微信API /cgi-bin/gettoken 获取access_token，用于后续API调用的身份验证。
+        access_token的有效期为7200秒，需要定期刷新。
+
+        Args:
+            client: 可选的HTTP客户端实例，若提供则直接使用
+            client_kwargs: 创建临时客户端时的额外配置参数
+            **kwargs: 额外的请求参数，将与默认参数合并
+
+        Returns:
+            httpx.Response: HTTP响应对象，成功时包含access_token字段
+
+        响应结构：
+            {
+                "errcode": 0,
+                "errmsg": "ok",
+                "access_token": "ACCESS_TOKEN",
+                "expires_in": 7200
+            }
+
+        代码演示：
+            >>> server = Base(corpid="your_corpid", corpsecret="your_corpsecret")
+            >>> response = server.gettoken()
+            >>> print(response.json())
+        """
+        client_kwargs = client_kwargs or {}
+        # 处理None值，确保kwargs是字典类型
+        kwargs = kwargs or {}
+        # 合并默认请求参数与用户参数，用户参数优先覆盖默认值
+        kwargs = {
+            # 默认请求参数：获取token的路径、GET方法、企业ID和应用密钥参数
+            **{
+                "method": "GET",
+                "url": "/cgi-bin/gettoken",
+                "params": {
+                    "corpid": self.corpid,
+                    "corpsecret": self.corpsecret,
+                }
+            },
+            **kwargs
+        }
+        return self.request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    async def async_gettoken(
+            self,
+            client: Optional[httpx.AsyncClient] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        异步获取access_token
+
+        @see: https://developer.work.weixin.qq.com/document/path/91039
+
+        调用企业微信API /cgi-bin/gettoken 获取access_token，用于后续API调用的身份验证。
+        access_token的有效期为7200秒，需要定期刷新。
+
+        Args:
+            client: 可选的异步HTTP客户端实例，若提供则直接使用
+            client_kwargs: 创建临时客户端时的额外配置参数
+            **kwargs: 额外的请求参数，将与默认参数合并
+
+        Returns:
+            httpx.Response: HTTP响应对象，成功时包含access_token字段
+
+        代码演示：
+            >>> import asyncio
+            >>> server = Base(corpid="your_corpid", corpsecret="your_corpsecret")
+            >>> async def main():
+            >>>     response = await server.async_gettoken()
+            >>>     print(response.json())
+            >>> asyncio.run(main())
+        """
+        client_kwargs = client_kwargs or {}
+        # 处理None值，确保kwargs是字典类型
+        kwargs = kwargs or {}
+        # 合并默认请求参数与用户参数，用户参数优先覆盖默认值
+        kwargs = {
+            # 默认请求参数：获取token的路径、GET方法、企业ID和应用密钥参数
+            **{
+                "method": "GET",
+                "url": "/cgi-bin/gettoken",
+                "params": {
+                    "corpid": self.corpid,
+                    "corpsecret": self.corpsecret,
+                }
+            },
+            **kwargs
+        }
+        return await self.async_request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    def get_api_domain_ip(
+            self,
+            client: Optional[httpx.Client] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        同步获取企业微信API域名IP列表
+
+        @see: https://developer.work.weixin.qq.com/document/path/90960
+
+        获取企业微信API服务器的IP地址列表，用于白名单配置等场景。
+
+        Args:
+            client: 可选的HTTP客户端实例，若提供则直接使用
+            client_kwargs: 创建临时客户端时的额外配置参数
+            **kwargs: 额外的请求参数，将与默认参数合并
+
+        Returns:
+            httpx.Response: HTTP响应对象，成功时包含IP列表
+
+        响应结构：
+            {
+                "errcode": 0,
+                "errmsg": "ok",
+                "ip_list": ["IP1", "IP2", ...]
+            }
+
+        代码演示：
+            >>> server = Base(corpid="your_corpid", corpsecret="your_corpsecret")
+            >>> server.refresh_access_token()
+            >>> response = server.get_api_domain_ip()
+            >>> print(response.json())
+        """
+        client_kwargs = client_kwargs or {}
+        # 处理None值，确保kwargs是字典类型
+        kwargs = kwargs or {}
+        # 合并默认请求参数与用户参数，用户参数优先覆盖默认值
+        kwargs = {
+            **{
+                "method": "GET",
+                "url": "/cgi-bin/get_api_domain_ip",
+                "params": {
+                    "access_token": self.access_token,
+                }
+            },
+            **kwargs
+        }
+        return self.request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    async def async_get_api_domain_ip(
+            self,
+            client: Optional[httpx.AsyncClient] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        异步获取企业微信API域名IP列表
+
+        @see: https://developer.work.weixin.qq.com/document/path/90960
+
+        获取企业微信API服务器的IP地址列表，用于白名单配置等场景。
+
+        Args:
+            client: 可选的异步HTTP客户端实例，若提供则直接使用
+            client_kwargs: 创建临时客户端时的额外配置参数
+            **kwargs: 额外的请求参数，将与默认参数合并
+
+        Returns:
+            httpx.Response: HTTP响应对象，成功时包含IP列表
+
+        代码演示：
+            >>> import asyncio
+            >>> server = Base(corpid="your_corpid", corpsecret="your_corpsecret")
+            >>> await server.async_refresh_access_token()
+            >>> response = await server.async_get_api_domain_ip()
+            >>> print(response.json())
+        """
+        client_kwargs = client_kwargs or {}
+        # 处理None值，确保kwargs是字典类型
+        kwargs = kwargs or {}
+        # 合并默认请求参数与用户参数，用户参数优先覆盖默认值
+        kwargs = {
+            **{
+                "method": "GET",
+                "url": "/cgi-bin/get_api_domain_ip",
+                "params": {
+                    "access_token": self.access_token,
+                }
+            },
+            **kwargs
+        }
+        return await self.async_request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    def getcallbackip(
+            self,
+            client: Optional[httpx.Client] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        同步获取企业微信回调IP列表
+
+        @see: https://developer.work.weixin.qq.com/document/path/90961
+
+        获取企业微信服务器用于回调的IP地址列表，用于配置服务器白名单。
+
+        Args:
+            client: 可选的HTTP客户端实例，若提供则直接使用
+            client_kwargs: 创建临时客户端时的额外配置参数
+            **kwargs: 额外的请求参数，将与默认参数合并
+
+        Returns:
+            httpx.Response: HTTP响应对象，成功时包含回调IP列表
+
+        响应结构：
+            {
+                "errcode": 0,
+                "errmsg": "ok",
+                "ip_list": ["IP1", "IP2", ...]
+            }
+
+        代码演示：
+            >>> server = Base(corpid="your_corpid", corpsecret="your_corpsecret")
+            >>> server.refresh_access_token()
+            >>> response = server.getcallbackip()
+            >>> print(response.json())
+        """
+        client_kwargs = client_kwargs or {}
+        # 处理None值，确保kwargs是字典类型
+        kwargs = kwargs or {}
+        # 合并默认请求参数与用户参数，用户参数优先覆盖默认值
+        kwargs = {
+            **{
+                "method": "GET",
+                "url": "/cgi-bin/getcallbackip",
+                "params": {
+                    "access_token": self.access_token,
+                }
+            },
+            **kwargs
+        }
+        return self.request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    async def async_getcallbackip(
+            self,
+            client: Optional[httpx.AsyncClient] = None,
+            client_kwargs: Optional[dict] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        异步获取企业微信回调IP列表
+
+        @see: https://developer.work.weixin.qq.com/document/path/90961
+
+        获取企业微信服务器用于回调的IP地址列表，用于配置服务器白名单。
+
+        Args:
+            client: 可选的异步HTTP客户端实例，若提供则直接使用
+            client_kwargs: 创建临时客户端时的额外配置参数
+            **kwargs: 额外的请求参数，将与默认参数合并
+
+        Returns:
+            httpx.Response: HTTP响应对象，成功时包含回调IP列表
+
+        代码演示：
+            >>> import asyncio
+            >>> server = Base(corpid="your_corpid", corpsecret="your_corpsecret")
+            >>> await server.async_refresh_access_token()
+            >>> response = await server.async_getcallbackip()
+            >>> print(response.json())
+        """
+        client_kwargs = client_kwargs or {}
+        # 处理None值，确保kwargs是字典类型
+        kwargs = kwargs or {}
+        # 合并默认请求参数与用户参数，用户参数优先覆盖默认值
+        kwargs = {
+            **{
+                "method": "GET",
+                "url": "/cgi-bin/getcallbackip",
+                "params": {
+                    "access_token": self.access_token,
+                }
+            },
+            **kwargs
+        }
+        return await self.async_request(client=client, client_kwargs=client_kwargs, **kwargs)
+
+    def refresh_access_token(
+            self,
+            gettoken_func_kwargs: Optional[dict] = None,
+            get_api_domain_ip_func_kwargs: Optional[dict] = None,
+            cache_config: Optional[dict] = None,
+    ) -> "Base":
+        """
+        同步刷新access_token
+
+        获取并更新access_token，支持使用diskcache或Redis进行缓存，减少API调用次数。
+
+        逻辑流程：
+            1. 合并缓存配置（实例配置与调用时配置）
+            2. 判断是否配置了缓存实例（diskcache.Cache或redis.Redis）
+            3. 如果未配置缓存：直接调用gettoken获取access_token
+            4. 如果配置了缓存：
+               - 优先从缓存获取access_token
+               - 如果缓存中没有或无效，调用gettoken获取并写入缓存
+               - 调用get_api_domain_ip验证token有效性
+               - 如果验证失败，重新获取并更新缓存
+            5. 更新实例的access_token属性
+
+        Args:
+            gettoken_func_kwargs: gettoken方法的额外参数
+            get_api_domain_ip_func_kwargs: get_api_domain_ip方法的额外参数
+            cache_config: 缓存配置字典，包含：
+                - instance: 缓存实例（diskcache.Cache或redis.Redis）
+                - key: 缓存键名，默认为"pywecom_server_{corpid}_{agentid}"
+                - expire: 缓存过期时间，默认为7100秒（小于7200秒官方有效期）
+
+        Returns:
+            Base: 返回self，支持链式调用
+
+        代码演示：
+            >>> from py_wecom_toolkit.server import Base
+            >>> import diskcache
+            >>> # 创建带缓存的实例
+            >>> cache = diskcache.Cache("./cache")
+            >>> server = Base(corpid="your_corpid", corpsecret="your_corpsecret", 
+            ...              cache_config={"instance": cache})
+            >>> server.refresh_access_token()
+            >>> print(server.access_token)
+        """
+        gettoken_func_kwargs = gettoken_func_kwargs or {}
+        get_api_domain_ip_func_kwargs = get_api_domain_ip_func_kwargs or {}
+        cache_config = cache_config or {}
+        # 合并实例缓存配置与调用时的缓存配置，调用时配置优先
+        cache_config = {
+            **self.cache_config,
+            **cache_config,
+        }
+        cache_key = cache_config.get("key", f"pywecom_server_{self.corpid}_{self.agentid}")
+        cache_expire = cache_config.get("expire", 7100)
+        cache_inst = cache_config.get("instance", None)
+
+        # 【逻辑分支1】未配置缓存实例，直接获取token
+        if not isinstance(cache_inst, Union[diskcache.Cache, redis.Redis]):
+            response = self.gettoken(**gettoken_func_kwargs)
+            if success_is_valid(response):
+                self.access_token = response.json().get("access_token", None)
+        else:
+            # 【逻辑分支2】配置了缓存实例，优先使用缓存
+            # 从缓存获取access_token
+            self.access_token = cache_inst.get(cache_key)
+            # 如果缓存中没有有效token，重新获取
+            if not isinstance(self.access_token, str) or not len(self.access_token):
+                response = self.gettoken(**gettoken_func_kwargs)
+                if success_is_valid(response):
+                    self.access_token = response.json().get("access_token", None)
+                    # 根据缓存类型设置缓存
+                    if isinstance(cache_inst, diskcache.Cache):
+                        cache_inst.set(cache_key, self.access_token, expire=cache_expire)
+                    if isinstance(cache_inst, redis.Redis):
+                        cache_inst.set(cache_key, self.access_token, ex=cache_expire)
+
+            # 【验证机制】调用get_api_domain_ip验证token有效性
+            response = self.get_api_domain_ip(**get_api_domain_ip_func_kwargs)
+            if not success_is_valid(response):
+                # token失效，重新获取并更新缓存
+                response = self.gettoken(**gettoken_func_kwargs)
+                if success_is_valid(response):
+                    self.access_token = response.json().get("access_token", None)
+                    if isinstance(cache_inst, diskcache.Cache):
+                        cache_inst.set(cache_key, self.access_token, expire=cache_expire)
+                    if isinstance(cache_inst, redis.Redis):
+                        cache_inst.set(cache_key, self.access_token, ex=cache_expire)
+
+        return self
+
+    async def async_refresh_access_token(
+            self,
+            gettoken_func_kwargs: Optional[dict] = None,
+            get_api_domain_ip_func_kwargs: Optional[dict] = None,
+            cache_config: Optional[dict] = None,
+    ) -> "Base":
+        """
+        异步刷新access_token
+
+        获取并更新access_token，支持使用diskcache或Redis进行缓存，减少API调用次数。
+
+        逻辑流程：
+            1. 合并缓存配置（实例配置与调用时配置）
+            2. 判断是否配置了缓存实例（diskcache.Cache或redis.Redis）
+            3. 如果未配置缓存：直接调用async_gettoken获取access_token
+            4. 如果配置了缓存：
+               - 优先从缓存获取access_token
+               - 如果缓存中没有或无效，调用async_gettoken获取并写入缓存
+               - 调用async_get_api_domain_ip验证token有效性
+               - 如果验证失败，重新获取并更新缓存
+            5. 更新实例的access_token属性
+
+        Args:
+            gettoken_func_kwargs: async_gettoken方法的额外参数
+            get_api_domain_ip_func_kwargs: async_get_api_domain_ip方法的额外参数
+            cache_config: 缓存配置字典，包含：
+                - instance: 缓存实例（diskcache.Cache或redis.Redis）
+                - key: 缓存键名，默认为"pywecom_server_{corpid}_{agentid}"
+                - expire: 缓存过期时间，默认为7100秒
+
+        Returns:
+            Base: 返回self，支持链式调用
+
+        代码演示：
+            >>> import asyncio
+            >>> from py_wecom_toolkit.server import Base
+            >>> import redis
+            >>> # 创建带Redis缓存的实例
+            >>> r = redis.Redis(host='localhost', port=6379, db=0)
+            >>> server = Base(corpid="your_corpid", corpsecret="your_corpsecret",
+            ...              cache_config={"instance": r})
+            >>> await server.async_refresh_access_token()
+            >>> print(server.access_token)
+        """
+        gettoken_func_kwargs = gettoken_func_kwargs or {}
+        get_api_domain_ip_func_kwargs = get_api_domain_ip_func_kwargs or {}
+        cache_config = cache_config or {}
+        # 合并实例缓存配置与调用时的缓存配置，调用时配置优先
+        cache_config = {
+            **self.cache_config,
+            **cache_config,
+        }
+        cache_key = cache_config.get("key", f"pywecom_server_{self.corpid}_{self.agentid}")
+        cache_expire = cache_config.get("expire", 7100)
+        cache_inst = cache_config.get("instance", None)
+
+        # 【逻辑分支1】未配置缓存实例，直接获取token
+        if not isinstance(cache_inst, Union[diskcache.Cache, redis.Redis]):
+            response = await self.async_gettoken(**gettoken_func_kwargs)
+            if success_is_valid(response):
+                self.access_token = response.json().get("access_token", None)
+                if isinstance(cache_inst, diskcache.Cache):
+                    cache_inst.set(cache_key, self.access_token, expire=cache_expire)
+                if isinstance(cache_inst, redis.Redis):
+                    cache_inst.set(cache_key, self.access_token, ex=cache_expire)
+        else:
+            # 【逻辑分支2】配置了缓存实例，优先使用缓存
+            # 从缓存获取access_token
+            self.access_token = cache_inst.get(cache_key)
+            # 如果缓存中没有有效token，重新获取
+            if not isinstance(self.access_token, str) or not len(self.access_token):
+                response = await self.async_gettoken(**gettoken_func_kwargs)
+                if success_is_valid(response):
+                    self.access_token = response.json().get("access_token", None)
+
+            # 【验证机制】调用async_get_api_domain_ip验证token有效性
+            response = await self.async_get_api_domain_ip(**get_api_domain_ip_func_kwargs)
+            if not success_is_valid(response):
+                # token失效，重新获取并更新缓存
+                response = await self.async_gettoken(**gettoken_func_kwargs)
+                if success_is_valid(response):
+                    self.access_token = response.json().get("access_token", None)
+                    if isinstance(cache_inst, diskcache.Cache):
+                        cache_inst.set(cache_key, self.access_token, expire=cache_expire)
+                    if isinstance(cache_inst, redis.Redis):
+                        cache_inst.set(cache_key, self.access_token, ex=cache_expire)
+
+        return self