ddclient 0.1.0__tar.gz

ddclient-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.3
+Name: ddclient
+Version: 0.1.0
+Summary: 钉钉开放平台服务端接口调用客户端
+Author: luyifo
+Author-email: luyifo <luyifo@163.com>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# 使用指导
+## Step 1
+```bash
+pip install ddapi
+```
+
+## Step 2
+在项目根目录下新建.env文件
+配置环境变量
+```toml
+DINGTALK_APP_KEY="xxxxxxxx"
+DINGTALK_APP_SECRET="xxxxxxxx"
+```
+用你能想到的方法加载.env中的配置好的环境变量
+
+## Step 3
+
+```python
+from ddapi import default_client as client
+```
+
+## 宜搭
+配置环境变量
+```toml
+DINGTALK_APP_KEY="xxxxxxxx"
+DINGTALK_APP_SECRET="xxxxxxxx"
+DINGTALK_YIDA_APP_TYPE="xxxxxx"
+DINGTALK_YIDA_SYSTEM_TOKEN="xxxxxx"
+DINGTALK_USER_ID="xxxxxx"
+```
+
+### 默认使用
+```python
+from ddapi import default_client as client
+
+form_instance = client.yida.get_form_inst("FINST-XXXXXXX")
+```
+
+### 多应用
+```python
+from ddapi import default_client as client,YiDa,YiDaConfig
+
+yida1 =  YiDa(client,YiDaConfig(app_type="app_type1",system_token="system_token1",user_id="user_id1"))
+form_inst1 = yida1.get_form_inst("INST_ID")
+
+yida2 = YiDa(client,YiDaConfig(app_type="app_type2",system_token="system_token2",user_id="user_id2"))
+form_inst2 = yida2.get_form_inst("INST_ID")
+
+```

ddclient-0.1.0/README.md

@@ -0,0 +1,49 @@
+# 使用指导
+## Step 1
+```bash
+pip install ddapi
+```
+
+## Step 2
+在项目根目录下新建.env文件
+配置环境变量
+```toml
+DINGTALK_APP_KEY="xxxxxxxx"
+DINGTALK_APP_SECRET="xxxxxxxx"
+```
+用你能想到的方法加载.env中的配置好的环境变量
+
+## Step 3
+
+```python
+from ddapi import default_client as client
+```
+
+## 宜搭
+配置环境变量
+```toml
+DINGTALK_APP_KEY="xxxxxxxx"
+DINGTALK_APP_SECRET="xxxxxxxx"
+DINGTALK_YIDA_APP_TYPE="xxxxxx"
+DINGTALK_YIDA_SYSTEM_TOKEN="xxxxxx"
+DINGTALK_USER_ID="xxxxxx"
+```
+
+### 默认使用
+```python
+from ddapi import default_client as client
+
+form_instance = client.yida.get_form_inst("FINST-XXXXXXX")
+```
+
+### 多应用
+```python
+from ddapi import default_client as client,YiDa,YiDaConfig
+
+yida1 =  YiDa(client,YiDaConfig(app_type="app_type1",system_token="system_token1",user_id="user_id1"))
+form_inst1 = yida1.get_form_inst("INST_ID")
+
+yida2 = YiDa(client,YiDaConfig(app_type="app_type2",system_token="system_token2",user_id="user_id2"))
+form_inst2 = yida2.get_form_inst("INST_ID")
+
+```

ddclient-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "ddclient"
+version = "0.1.0"
+description = "钉钉开放平台服务端接口调用客户端"
+readme = "README.md"
+authors = [
+    { name = "luyifo", email = "luyifo@163.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.12.5",
+    "pydantic-settings>=2.12.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

ddclient-0.1.0/src/ddclient/__init__.py

@@ -0,0 +1,9 @@
+from .core import DingTalkClient, DingTalkConfig
+from .yida import YiDa,YiDaConfig
+
+
+_default_config = DingTalkConfig()
+
+default_client = DingTalkClient(_default_config)
+
+__all__ = ["DingTalkClient", "DingTalkConfig", "default_client","YiDa","YiDaConfig"]

ddclient-0.1.0/src/ddclient/contact.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .core import DingTalkClient
+
+
+class Contact:
+    def __init__(self, client: DingTalkClient) -> None:
+        self.client = client
+
+    def get_dept_list(self, dept_id: int = 1, lang: str = "zh_CN") -> dict[str, Any]:
+        """
+        获取部门列表
+        https://open.dingtalk.com/document/development/user-management-acquires-the-list-departments
+
+        :param dept_id: 部门ID
+        :param lang: 语言 zh_CN en_US
+        :return {"errcode":0,"errmsg":"ok","result":[{"auto_add_user":true,"create_dept_group":true,"dept_id":37xxxx95,"name":"市场部","parent_id":1}],"request_id":"5um7ykyaalsj"}:
+        """
+        url = "https://oapi.dingtalk.com/topapi/v2/department/listsub"
+        return self.client._request(
+            url, "POST", json={"dept_id": dept_id, "language": lang}
+        )
+
+    def get_det_detail(self, dept_id: int, lang: str = "zh_CN") -> dict[str, Any]:
+        """
+        获取部门详情
+        https://open.dingtalk.com/document/development/query-department-details0-v2
+
+        :param dept_id: 部门ID
+        :param lang: 语言 zh_CN en_US
+        :return {"errcode":0,"errmsg":"ok","result":{"dept_permits":[3,4,5],"outer_permit_users":["user123","1234"],"dept_manager_userid_list":["1020302901-431772414"],"org_dept_owner":"manager9153","outer_dept":false,"dept_group_chat_id":"chat1fccdb4b921f2bde18c26xxxx","group_contain_sub_dept":true,"auto_add_user":true,"hide_dept":false,"name":"测试","outer_permit_depts":[500,600],"user_permits":[],"dept_id":1,"create_dept_group":true,"order":0,"code":"100","union_dept_ext":{"corp_id":"test","dept_id":1234567}},"request_id":"4e7ljtq91rgo"}:
+        """
+        url = "https://oapi.dingtalk.com/topapi/v2/department/get"
+        return self.client._request(
+            url, "POST", json={"dept_id": dept_id, "language": lang}
+        )
+    
+    def search_dept(self,query_word:str,offset:int = 0,size:int = 10):
+        """
+        搜索部门ID
+        https://open.dingtalk.com/document/development/address-book-search-department-id
+        
+        :param query_word: 部门名称或者部门名称拼音
+        :param offset: 分页页码
+        :param size: 分页大小
+        :return {"hasMore":false,"totalCount":2,"list":[220141953,220207936]}:
+        """
+        
+        url = "https://api.dingtalk.com/v1.0/contact/departments/search"
+        return self.client._request(url,"POST",json={
+            "queryWord":query_word,
+            "offset":offset,
+            "size":size
+        })
+    
+
+

ddclient-0.1.0/src/ddclient/core.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import time
+import httpx
+import atexit
+from typing_extensions import Self
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from typing import Literal, TYPE_CHECKING
+from functools import cached_property
+
+if TYPE_CHECKING:
+    from .yida import YiDa
+
+HttpMethod = Literal["GET", "PUT", "POST", "DELETE"]
+
+
+class DingTalkConfig(BaseSettings):
+    app_key: str = ""
+    app_secret: str = ""
+
+    model_config = SettingsConfigDict(
+        env_prefix="DINGTALK_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="allow",
+    )
+
+
+class Token(BaseModel):
+    access_token: str
+    expire_at: float
+
+
+class TokenManager:
+    _instance = None
+    _tokens: dict[str, Token] = {}
+
+    def __new__(cls) -> Self:
+        if cls._instance is None:
+            cls._instance = super(TokenManager, cls).__new__(cls)
+
+        return cls._instance
+
+    def get_token(self, app_key: str, app_secret: str) -> str:
+        token = self._tokens.get(app_key)
+
+        if not token or token.expire_at < time.time():
+            token = self._refresh_token(app_key, app_secret)
+
+        return token.access_token
+
+    def _refresh_token(self, app_key: str, app_secret: str) -> Token:
+        url = "https://api.dingtalk.com/v1.0/oauth2/accessToken"
+        body = {"appKey": app_key, "appSecret": app_secret}
+
+        with httpx.Client() as client:
+            res = client.post(url, json=body)
+
+            try:
+                res.raise_for_status()
+            except httpx.HTTPStatusError as ex:
+                raise Exception(ex.response.text)
+
+            data = res.json()
+
+        self._tokens[app_key] = Token(
+            access_token=data["accessToken"], expire_at=time.time() + 3600
+        )
+
+        return self._tokens[app_key]
+
+
+class DingTalkClient:
+    def __init__(self, config: DingTalkConfig):
+        self.config = config
+        self.token_manager = TokenManager()
+        self.http_client = httpx.Client(
+            transport=httpx.HTTPTransport(retries=3), timeout=30.0
+        )
+
+        atexit.register(self.close)
+
+    @property
+    def acccess_token(self):
+        return self.token_manager.get_token(self.config.app_key, self.config.app_secret)
+
+    def _request(self, url: str, method: HttpMethod, **kwargs) -> dict:
+        if "oapi.dingtalk.com" in url:
+            params = kwargs.get("params", {})
+            params["access_token"] = self.acccess_token
+            kwargs["params"] = params
+        else:
+            headers = kwargs.get("headers", {})
+            headers.setdefault("x-acs-dingtalk-access-token", self.acccess_token)
+            kwargs["headers"] = headers
+
+        res = self.http_client.request(method, url, **kwargs)
+        try:
+            res.raise_for_status()
+            data = res.json()
+        except httpx.HTTPStatusError as ex:
+            try:
+                error_detail = ex.response.json()
+            except:  # noqa: E722
+                error_detail = ex.response.text
+
+            raise Exception(
+                f"Http Error:{ex.response.status_code}, Detail:{error_detail}"
+            )
+
+        if "errcode" in data and data["errcode"] != 0:
+            raise Exception(
+                f"dingtalk api err: {data.get('errmsg', 'unknown')} code:{data.get['errcode']}"
+            )
+        return data
+
+    def close(self):
+        if hasattr(self, "http_client"):
+            self.http_client.close()
+
+    @cached_property
+    def yida(self) -> YiDa:
+        from .yida import YiDa, YiDaConfig
+
+        return YiDa(self, YiDaConfig())

ddclient-0.1.0/src/ddclient/yida.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, Any
+from pydantic_settings import BaseSettings, SettingsConfigDict
+import json
+
+if TYPE_CHECKING:
+    from .core import DingTalkClient
+
+
+class YiDaConfig(BaseSettings):
+    app_type: str | None = None
+    system_token: str | None = None
+    user_id: str | None = None
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_prefix="DINGTALK_YIDA_",
+        env_file_encoding="utf-8",
+        extra="allow",
+    )
+
+
+class YiDa:
+    def __init__(self, client: DingTalkClient, config: YiDaConfig) -> None:
+        self.client = client
+        self.config = config
+
+    @property
+    def _common_params(self):
+        return {
+            "appType": self.config.app_type,
+            "systemToken": self.config.system_token,
+            "userId": self.config.user_id,
+        }
+
+    def _prepare_params(
+        self, base_params: dict[str, Any], use_alias: bool, form_uuid: str | None
+    ):
+        params = {**base_params, "useAlias": use_alias}
+
+        if use_alias:
+            if form_uuid is None:
+                raise ValueError(
+                    "when the 'use_alias' is true,the 'form_uuid' cannot be empty"
+                )
+
+            params["formUuid"] = form_uuid
+        return params
+
+    def get_form_inst(
+        self, inst_id: str, use_alias=False, form_uuid: str | None = None
+    ) -> dict[str, Any]:
+        """
+        获取表单实例
+
+        :param inst_id: 表单实例ID
+        :param use_alias: 是否使用组件别名
+        :param form_uuid: 表单UUID 当使用组件别名时必填
+
+        :return {"originator":{"userId":"user123","name":{"nameInChinese":"张三","nameInEnglish":"ZhangSan","type":"i18n"},"departmentName":"开发部","email":"abc@alimail.com"},"modifiedTimeGMT":"2021-05-01","formInstId":"FORM_INST_12345"}:
+
+        """
+        url = f"https://api.dingtalk.com/v2.0/yida/forms/instances/{inst_id}"
+
+        params = self._prepare_params(self._common_params, use_alias, form_uuid)
+        return self.client._request(url, "GET", params=params)
+
+    def del_form_inst(self, inst_id: str):
+        url = "https://api.dingtalk.com/v1.0/yida/forms/instances"
+        return self.client._request(
+            url,
+            "DELETE",
+            params={**self._common_params, "formInstanceId": inst_id},
+        )
+
+    def save_form_inst(
+        self, form_uuid: str, form_data: dict[str, Any], use_alias: bool = False
+    ) -> dict[str, str]:
+        """
+        新增表单实例
+
+        :param form_uuid: 表单UUID
+        :param form_data: 表单数据
+        :param use_alias: 是否使用组件别名
+        :return {"result":["FINST-SASNOO39NSIFF780"]}:
+
+        """
+        url = "https://api.dingtalk.com/v2.0/yida/forms/instances"
+        return self.client._request(
+            url,
+            "POST",
+            json={
+                **self._common_params,
+                "formUuid": form_uuid,
+                "formDataJson": json.dumps(form_data),
+                "useAlias": use_alias,
+            },
+        )
+
+    def update_form_inst(
+        self,
+        inst_id: str,
+        form_data: dict[str, Any],
+        use_alias: bool = False,
+        form_uuid: str | None = None,
+        use_latest_version=False,
+    ):
+        """
+        更新表单实例
+        https://open.dingtalk.com/document/development/api-updateformdata-v2
+
+        :param inst_id: 表单实例ID
+        :param form_data: 表单数据
+        :param use_alias: 是否使用组件别名
+        :param form_uuid: 表单UUID 当使用组件别名时必填
+        :param use_latest_version: 是否使用最新表单版本更新
+        """
+
+        url = "https://api.dingtalk.com/v2.0/yida/forms/instances"
+        body = {
+            **self._common_params,
+            "formInstanceId": inst_id,
+            "updateFormDataJson": json.dumps(form_data),
+            "useAlias": use_alias,
+            "useLatestVersion": use_latest_version,
+        }
+
+        body = self._prepare_params(
+            {
+                **self._common_params,
+                "formInstanceId": inst_id,
+                "updateFormDataJson": json.dumps(form_data),
+                "useLatestVersion": use_latest_version,
+            },
+            use_alias,
+            form_uuid,
+        )
+
+        self.client._request(url, "PUT", json=body)
+
+    def save_update_form_inst(
+        self,
+        form_uuid: str,
+        search_condition: dict[str, Any],
+        form_data: dict[str, Any],
+        use_alias: bool = False,
+        execute_expression: bool = True,
+    ):
+        """
+        新增或更新表单实例
+        https://open.dingtalk.com/document/development/api-createorupdateformdata-v2
+
+        :param form_uuid: 表单UUID
+        :param search_condition: 检索条件
+        :param form_data: 表单数据
+        :param use_alias: 是否使用组件别名
+        :param execute_expression: 是否触发表单校验规则，关联业务规则和第三方服务回调
+
+        :return {"result":["FINST-SASNOO39NSIFF780"]}:
+        """
+
+        url = "https://api.dingtalk.com/v2.0/yida/forms/instances/insertOrUpdate"
+
+        return self.client._request(
+            url,
+            "POST",
+            json={
+                **self._common_params,
+                "formUuid": form_uuid,
+                "searchCondition": search_condition,
+                "formDataJson": json.dumps(form_data),
+                "noExecuteExpression": not execute_expression,
+                "useAlias": use_alias,
+            },
+        )