py-wecom 0.1.0__py3-none-any.whl

py_wecom/__init__.py

@@ -0,0 +1,2 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-

py_wecom/server/__init__.py

@@ -0,0 +1,352 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+from typing import List, Optional, Tuple, Union
+
+import diskcache
+import httpx
+import redis
+from pydantic import HttpUrl
+from .utils import convert_to_errcode_eq_0, errcode_eq_0_validator
+
+
+class Base:
+    def __init__(
+            self,
+            base_url: HttpUrl = "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,
+    ):
+        """
+        初始化Server实例
+
+        参数:
+            base_url: 企业微信API基础URL，默认"https://qyapi.weixin.qq.com"
+            corpid: 企业ID，可在企业微信管理后台获取
+            corpsecret: 应用密钥，可在企业微信管理后台获取
+            agentid: 企业应用ID，可在企业微信管理后台获取
+            cache_config: 缓存配置字典，包含instance（缓存实例）、key（缓存键名）、expire（过期时间）
+            client_kwargs: httpx客户端配置参数
+        """
+        self.base_url = base_url[:-1] if base_url.endswith("/") else base_url
+        self.corpid = corpid or ""
+        self.corpsecret = corpsecret or ""
+        self.agentid = agentid or ""
+        self.cache_config = cache_config or {}
+        self.cache_config = {
+            **{
+                "instance": None,
+                "key": f"pywecom_server_{self.corpid}_{self.agentid}",
+                "expire": 7100,
+            },
+            **self.cache_config,
+        }
+        self.client_kwargs = client_kwargs or {}
+        self.client_kwargs = {
+            **{
+                "base_url": self.base_url,
+                "timeout": 60,
+            },
+            **self.client_kwargs,
+        }
+        self.access_token = ""
+
+    def client(self) -> httpx.Client:
+        """
+        创建并返回同步HTTP客户端
+
+        Returns:
+            httpx.Client: 配置好的同步HTTP客户端实例
+        """
+        return httpx.Client(**self.client_kwargs)
+
+    def async_client(self) -> httpx.AsyncClient:
+        """
+        创建并返回异步HTTP客户端
+
+        Returns:
+            httpx.AsyncClient: 配置好的异步HTTP客户端实例
+        """
+        return httpx.AsyncClient(**self.client_kwargs)
+
+    def gettoken(
+            self,
+            client: Optional[httpx.Client] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        获取企业微信access_token
+
+        @see:https://developer.work.weixin.qq.com/document/path/91039
+        Args:
+            client: 可选的HTTP客户端实例，若不提供则自动创建
+            **kwargs: 请求参数，包含url、method、json等
+
+        Returns:
+            httpx.Response: 发送响应结果，包含错误码和错误信息
+        """
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "url": "/cgi-bin/gettoken",
+                "method": "GET",
+                "params": {
+                    "corpid": self.corpid,
+                    "corpsecret": self.corpsecret,
+                }
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.Client):
+            response = client.request(**kwargs)
+        else:
+            with self.client() as _client:
+                response = _client.request(**kwargs)
+        return response
+
+    def get_api_domain_ip(
+            self,
+            client: Optional[httpx.Client] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        获取企业微信API域名IP
+
+        @see:https://developer.work.weixin.qq.com/document/path/92520
+        Args:
+            client: 可选的HTTP客户端实例，若不提供则自动创建
+            **kwargs: 请求参数，包含url、method、json等
+
+        Returns:
+            httpx.Response: 发送响应结果，包含错误码和错误信息
+        """
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "url": "/cgi-bin/get_api_domain_ip",
+                "method": "GET",
+                "params": {
+                    "access_token": self.access_token,
+                }
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.Client):
+            response = client.request(**kwargs)
+        else:
+            with self.client() as _client:
+                response = _client.request(**kwargs)
+        return response
+
+    def getcallbackip(
+            self,
+            client: Optional[httpx.Client] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        获取企业微信回调IP
+
+        @see:https://developer.work.weixin.qq.com/document/path/92521
+        Args:
+            client: 可选的HTTP客户端实例，若不提供则自动创建
+            **kwargs: 请求参数，包含url、method、json等
+
+        Returns:
+            httpx.Response: 发送响应结果，包含错误码和错误信息
+        """
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "url": "/cgi-bin/getcallbackip",
+                "method": "GET",
+                "params": {
+                    "access_token": self.access_token,
+                }
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.Client):
+            response = client.request(**kwargs)
+        else:
+            with self.client() as _client:
+                response = _client.request(**kwargs)
+        return response
+
+    def refresh_access_token(
+            self,
+            gettoken_func_kwargs: Optional[dict] = None,
+            get_api_domain_ip_func_kwargs: Optional[dict] = None
+    ) -> "Base":
+        gettoken_func_kwargs = gettoken_func_kwargs or {}
+        get_api_domain_ip_func_kwargs = get_api_domain_ip_func_kwargs or {}
+        cache_key = self.cache_config.get("key", f"pywecom_server_{self.corpid}_{self.agentid}")
+        cache_expire = self.cache_config.get("expire", 7100)
+        cache_instance = self.cache_config.get("instance", None)
+        if not isinstance(cache_instance, Union[diskcache.Cache, redis.Redis]):
+            self.access_token = convert_to_errcode_eq_0(
+                self.gettoken(**gettoken_func_kwargs)
+            ).access_token
+        else:
+            self.access_token = cache_instance.get(cache_key)
+            if not isinstance(self.access_token, str) or not len(self.access_token):
+                self.access_token = convert_to_errcode_eq_0(
+                    self.gettoken(**gettoken_func_kwargs)
+                ).access_token
+                ip_list = convert_to_errcode_eq_0(
+                    self.get_api_domain_ip(**get_api_domain_ip_func_kwargs)
+                ).ip_list
+                if not isinstance(ip_list, list):
+                    self.access_token = convert_to_errcode_eq_0(
+                        self.gettoken(**gettoken_func_kwargs)
+                    ).access_token
+            ip_list = convert_to_errcode_eq_0(
+                self.get_api_domain_ip(**get_api_domain_ip_func_kwargs)
+            ).ip_list
+            if isinstance(ip_list, list):
+                if isinstance(cache_instance, diskcache.Cache):
+                    cache_instance.set(cache_key, self.access_token, expire=cache_expire)
+                elif isinstance(cache_instance, redis.Redis):
+                    cache_instance.set(cache_key, self.access_token, ex=cache_expire)
+        return self
+
+    async def async_gettoken(
+            self,
+            client: Optional[httpx.AsyncClient] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        获取企业微信access_token
+
+        @see:https://developer.work.weixin.qq.com/document/path/91039
+        Args:
+            client: 可选的HTTP客户端实例，若不提供则自动创建
+            **kwargs: 请求参数，包含url、method、json等
+
+        Returns:
+            httpx.Response: 发送响应结果，包含错误码和错误信息
+        """
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "url": "/cgi-bin/gettoken",
+                "method": "GET",
+                "params": {
+                    "corpid": self.corpid,
+                    "corpsecret": self.corpsecret,
+                }
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.AsyncClient):
+            response = await client.request(**kwargs)
+        else:
+            async with self.async_client() as _client:
+                response = await _client.request(**kwargs)
+        return response
+
+    async def async_get_api_domain_ip(
+            self,
+            client: Optional[httpx.AsyncClient] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        获取企业微信API域名IP
+
+        @see:https://developer.work.weixin.qq.com/document/path/92520
+        Args:
+            client: 可选的HTTP客户端实例，若不提供则自动创建
+            **kwargs: 请求参数，包含url、method、json等
+
+        Returns:
+            httpx.Response: 发送响应结果，包含错误码和错误信息
+        """
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "url": "/cgi-bin/get_api_domain_ip",
+                "method": "GET",
+                "params": {
+                    "access_token": self.access_token,
+                }
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.Client):
+            response = client.request(**kwargs)
+        else:
+            async with self.async_client() as _client:
+                response = await _client.request(**kwargs)
+        return response
+
+    async def async_getcallbackip(
+            self,
+            client: Optional[httpx.AsyncClient] = None,
+            **kwargs
+    ) -> httpx.Response:
+        """
+        获取企业微信回调IP
+
+        @see:https://developer.work.weixin.qq.com/document/path/92521
+        Args:
+            client: 可选的HTTP客户端实例，若不提供则自动创建
+            **kwargs: 请求参数，包含url、method、json等
+
+        Returns:
+            httpx.Response: 发送响应结果，包含错误码和错误信息
+        """
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "url": "/cgi-bin/getcallbackip",
+                "method": "GET",
+                "params": {
+                    "access_token": self.access_token,
+                }
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.AsyncClient):
+            response = await client.request(**kwargs)
+        else:
+            async with self.async_client() as _client:
+                response = await _client.request(**kwargs)
+        return response
+
+    async def async_refresh_access_token(
+            self,
+            gettoken_func_kwargs: Optional[dict] = None,
+            get_api_domain_ip_func_kwargs: Optional[dict] = None
+    ) -> "Base":
+        gettoken_func_kwargs = gettoken_func_kwargs or {}
+        get_api_domain_ip_func_kwargs = get_api_domain_ip_func_kwargs or {}
+        cache_key = self.cache_config.get("key", f"pywecom_server_{self.corpid}_{self.agentid}")
+        cache_expire = self.cache_config.get("expire", 7100)
+        cache_instance = self.cache_config.get("instance", None)
+        if not isinstance(cache_instance, Union[diskcache.Cache, redis.Redis]):
+            self.access_token = convert_to_errcode_eq_0(
+                await self.async_gettoken(**gettoken_func_kwargs)
+            ).access_token
+        else:
+            self.access_token = cache_instance.get(cache_key)
+            if not isinstance(self.access_token, str) or not len(self.access_token):
+                self.access_token = convert_to_errcode_eq_0(
+                    await self.async_gettoken(**gettoken_func_kwargs)
+                ).access_token
+                ip_list = convert_to_errcode_eq_0(
+                    await self.async_get_api_domain_ip(**get_api_domain_ip_func_kwargs)
+                ).ip_list
+                if not isinstance(ip_list, list):
+                    self.access_token = convert_to_errcode_eq_0(
+                        await self.async_gettoken(**gettoken_func_kwargs)
+                    ).access_token
+            ip_list = convert_to_errcode_eq_0(
+                await self.async_get_api_domain_ip(**get_api_domain_ip_func_kwargs)
+            ).ip_list
+            if isinstance(ip_list, list):
+                if isinstance(cache_instance, diskcache.Cache):
+                    cache_instance.set(cache_key, self.access_token, expire=cache_expire)
+                elif isinstance(cache_instance, redis.Redis):
+                    cache_instance.set(cache_key, self.access_token, ex=cache_expire)
+        return self

py_wecom/server/materials.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+# -*- coding: UTF-8 -*-
+"""
+企业微信素材上传模块
+
+该模块提供了企业微信素材上传的同步和异步方法，支持上传图片、视频、语音和普通文件。
+"""
+
+from typing import Optional
+
+import httpx
+
+from . import Base
+
+
+class Uploader(Base):
+    """
+    企业微信素材上传器类
+
+    继承自Base类，提供同步和异步的素材上传功能，支持多种文件类型的上传。
+    """
+
+    def upload(self, client: Optional[httpx.Client] = None, file_type: Optional[str] = "file", **kwargs):
+        """
+        同步上传临时素材
+
+        调用企业微信API /cgi-bin/media/upload 上传临时素材，有效期为3天。
+
+        @see:https://developer.work.weixin.qq.com/document/path/90253
+        Args:
+            client: 可选的httpx.Client实例，用于复用连接。如果不传，将自动创建新的client。
+            file_type: 上传文件类型，支持 image、video、voice、file，默认为 file。
+                若传入的类型不在支持列表中，将自动转为 file。
+            **kwargs: 额外的请求参数，将与默认参数合并。
+
+        Returns:
+            httpx.Response: API响应对象，包含上传后的素材ID等信息。
+        """
+        # 验证文件类型，只支持指定的四种类型
+        file_type = "file" if file_type.lower() not in ["image", "video", "voice", "file"] else file_type
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "url": "/cgi-bin/media/upload",
+                "method": "POST",
+                "params": {
+                    "access_token": self.access_token,
+                    "type": file_type,
+                }
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.Client):
+            response = client.request(**kwargs)
+        else:
+            with self.client() as _client:
+                response = _client.request(**kwargs)
+        return response
+
+    def uploadimg(self, client: Optional[httpx.Client] = None, **kwargs):
+        """
+        同步上传图片素材
+
+        调用企业微信API /cgi-bin/media/uploadimg 上传图片，返回的图片URL永久有效。
+
+        @see:https://developer.work.weixin.qq.com/document/path/90256
+        Args:
+            client: 可选的httpx.Client实例，用于复用连接。如果不传，将自动创建新的client。
+            **kwargs: 额外的请求参数，将与默认参数合并。
+
+        Returns:
+            httpx.Response: API响应对象，包含图片URL等信息。
+        """
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "url": "/cgi-bin/media/uploadimg",
+                "method": "POST",
+                "params": {
+                    "access_token": self.access_token,
+                }
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.Client):
+            response = client.request(**kwargs)
+        else:
+            with self.client() as _client:
+                response = _client.request(**kwargs)
+        return response
+
+    async def async_upload(self, client: Optional[httpx.AsyncClient] = None, file_type: Optional[str] = "file",
+                           **kwargs):
+        """
+        异步上传临时素材
+
+        调用企业微信API /cgi-bin/media/upload 异步上传临时素材，有效期为3天。
+
+        @see:https://developer.work.weixin.qq.com/document/path/90253
+        Args:
+            client: 可选的httpx.AsyncClient实例，用于复用连接。如果不传，将自动创建新的client。
+            file_type: 上传文件类型，支持 image、video、voice、file，默认为 file。
+                若传入的类型不在支持列表中，将自动转为 file。
+            **kwargs: 额外的请求参数，将与默认参数合并。
+
+        Returns:
+            httpx.Response: API响应对象，包含上传后的素材ID等信息。
+        """
+        # 验证文件类型，只支持指定的四种类型
+        file_type = "file" if file_type.lower() not in ["image", "video", "voice", "file"] else file_type
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "url": "/cgi-bin/media/upload",
+                "method": "POST",
+                "params": {
+                    "access_token": self.access_token,
+                    "type": file_type,
+                }
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.AsyncClient):
+            response = await client.request(**kwargs)
+        else:
+            async with self.async_client() as _client:
+                response = await _client.request(**kwargs)
+        return response
+
+    async def async_uploadimg(self, client: Optional[httpx.AsyncClient] = None, **kwargs):
+        """
+        异步上传图片素材
+
+        调用企业微信API /cgi-bin/media/uploadimg 异步上传图片，返回的图片URL永久有效。
+
+        @see:https://developer.work.weixin.qq.com/document/path/90256
+        Args:
+            client: 可选的httpx.AsyncClient实例，用于复用连接。如果不传，将自动创建新的client。
+            **kwargs: 额外的请求参数，将与默认参数合并。
+
+        Returns:
+            httpx.Response: API响应对象，包含图片URL等信息。
+        """
+        kwargs = kwargs or {}
+        kwargs = {
+            **{
+                "url": "/cgi-bin/media/uploadimg",
+                "method": "POST",
+                "params": {
+                    "access_token": self.access_token,
+                }
+            },
+            **kwargs
+        }
+        if isinstance(client, httpx.AsyncClient):
+            response = await client.request(**kwargs)
+        else:
+            async with self.async_client() as _client:
+                response = await _client.request(**kwargs)
+        return response