dataops-sdk 0.3.0__py3-none-any.whl

dataops_sdk/services/widget.py

@@ -0,0 +1,143 @@
+"""卡片 SDK 模块.
+
+封装卡片 (widget) 相关的 API 调用。
+"""
+
+from typing import Any
+
+from pydantic_core import to_json
+
+from dataops_sdk.exceptions import DataOpsError
+from dataops_sdk.schemas import MetaRelease, MetaType, PageParam, SqlQueryParam
+from dataops_sdk.services.meta import release_list_get_by_code, release_list_list
+from dataops_sdk.session import get_session
+from dataops_sdk.utils import encrypt_body
+
+
+def service_list_widgets() -> list[MetaRelease]:
+    """搜索卡片列表.
+
+    Returns:
+        MetaRelease 对象列表
+
+    Raises:
+        DataOpsError: API 请求失败时
+        AuthenticationError: 未认证时
+    """
+    return release_list_list(MetaType.WIDGET)
+
+
+def service_get_widget_detail_by_code(code: str):
+    """指定卡片详情.
+
+    Args:
+        code: 卡片编码
+
+    Returns:
+        卡片元数据模型。meta.data 为 dict，结构为:
+        subType: chart|metric|detail|topology|table|gis|statistic
+
+
+    Raises:
+        ValueError: 无效类型
+        NotFoundError: 卡片不存在
+        DataOpsError: API 请求失败
+        AuthenticationError: 未认证
+    """
+    # 不传 _class，让 meta.data 保持为 dict，避免 schema 与后端实际数据不一致
+    return release_list_get_by_code(MetaType.WIDGET, code)
+
+
+def service_get_widget_data_by_code(
+    code: str,
+    page_param: PageParam | None = None,
+    query_param: SqlQueryParam | None = None,
+) -> list[dict[str, Any]]:
+    """获取卡片实际数据（通过后端 /data/widget/findData 接口）.
+
+    Args:
+        code: 卡片编码
+        page_param: 分页参数，默认为第一页，每页 20 条
+        query_param: 查询过滤条件
+
+    Returns:
+        数据行列表（每行为字典）
+
+    Raises:
+        NotFoundError: 卡片不存在
+        DataOpsError: API 请求失败
+        AuthenticationError: 未认证
+    """
+    # 先获取卡片元数据，以提取 tenantId / subSystem / prodCode
+    meta = service_get_widget_detail_by_code(code)
+    sub_system = getattr(meta, "subSystem", None) or "default"
+
+    if page_param is None:
+        page_param = PageParam(limit=20)
+    if query_param is None:
+        query_param = SqlQueryParam()  # pyright: ignore[reportCallIssue]
+
+    body = {
+        "subSystem": sub_system,
+        "type": "widget",
+        "code": code,
+        "pageParam": page_param,
+        "queryParam": query_param,
+    }
+
+    with get_session(timeout=30) as session:
+        resp = session.post("/data/widget/findData", content=to_json(encrypt_body(body)))
+        resp_body = resp.json()
+
+    if not (200 <= resp.status_code < 300):
+        raise DataOpsError(f"请求失败({resp.status_code}): {resp_body}")
+
+    data = resp_body.get("data")
+    if data is None:
+        raise DataOpsError("查询异常")
+    return data
+
+
+def service_count_widget_by_code(
+    code: str,
+    query_param: SqlQueryParam | None = None,
+) -> int:
+    """获取卡片数据数量.
+
+    通过 `/data/widget/findData` 接口（请求体 `count=true`）。
+
+    Args:
+        code: 卡片编码
+        query_param: 查询条件
+
+    Returns:
+        卡片数据数量
+
+    Raises:
+        NotFoundError: 卡片不存在时
+        DataOpsError: API 请求失败时
+        AuthenticationError: 未认证时
+    """
+    meta = service_get_widget_detail_by_code(code)
+    sub_system = getattr(meta, "subSystem", None) or "default"
+
+    if query_param is None:
+        query_param = SqlQueryParam()  # pyright: ignore[reportCallIssue]
+
+    body = {
+        "subSystem": sub_system,
+        "type": MetaType.WIDGET,
+        "code": code,
+        "queryParam": query_param,
+        "count": True,
+    }
+
+    with get_session() as session:
+        resp = session.post("/data/widget/findData", content=to_json(encrypt_body(body)))
+        resp_body = resp.json()
+    if resp.status_code != 200:
+        raise DataOpsError(f"查询失败，{resp_body.get('msg')}", resp.status_code)
+    data = resp_body.get("data")
+    if data is None:
+        return 0
+    return int(data)

dataops_sdk/services/workflow.py

@@ -0,0 +1,102 @@
+from pydantic_core import to_json
+
+from dataops_sdk.exceptions import AuthenticationError, DataOpsError
+from dataops_sdk.schemas import DataWorkflow, MetaRelease, MetaType
+from dataops_sdk.services.meta import (
+    release_list_get_by_code,
+    release_list_get_by_name,
+    release_list_list,
+)
+from dataops_sdk.session import get_session
+from dataops_sdk.utils import encrypt_body, filter_nodes_by_pattern
+
+__all__ = [
+    "service_get_workflow_by_name",
+    "service_get_workflow_by_code",
+    "service_list_workflows",
+    "service_start_workflow",
+    "service_start_workflow_async",
+]
+
+
+def service_list_workflows(query: str | None = None) -> list[MetaRelease]:
+    """列出工作流（可选正则过滤）.
+
+    Args:
+        query: 正则表达式，匹配 NAME / TITLE / REMARK / DIGEST
+
+    Returns:
+        MetaRelease 对象列表
+
+    Raises:
+        DataOpsError: API 请求失败时
+        AuthenticationError: 未认证时
+    """
+    nodes = release_list_list(MetaType.WORKFLOW)
+    if query:
+        nodes = filter_nodes_by_pattern(nodes, query, include_digest=True)
+    return nodes
+
+
+def service_get_workflow_by_name(name: str):
+    return release_list_get_by_name(MetaType.WORKFLOW, name, _class=DataWorkflow)
+
+
+def service_get_workflow_by_code(code: str):
+    return release_list_get_by_code(MetaType.WORKFLOW, code, _class=DataWorkflow)
+
+
+def _post_workflow(url: str, body: dict) -> dict:
+    """通用工作流 POST 请求，返回 resp_body["data"].
+
+    Raises:
+        DataOpsError: API 返回错误时
+        AuthenticationError: 未认证或认证失败时
+    """
+    try:
+        with get_session() as session:
+            resp = session.post(url, content=to_json(encrypt_body(body)))
+            resp_body = resp.json()
+            if resp.status_code == 401:
+                raise AuthenticationError("认证失败，请先登录")
+            if resp.status_code != 200:
+                raise DataOpsError(
+                    resp_body.get("msg", f"HTTP {resp.status_code}"), resp.status_code
+                )
+        return resp_body.get("data") or {}
+    except SystemExit as e:
+        raise AuthenticationError("认证失败，请先登录") from e
+
+
+def service_start_workflow(code: str, params: dict | None = None) -> dict:
+    """同步启动工作流实例.
+
+    Args:
+        code: 工作流编码
+        params: 启动参数（透传给流程节点的入参）
+
+    Returns:
+        后端返回的启动结果（包含 flowInstCuid 等字段）
+
+    Raises:
+        DataOpsError: API 请求失败时
+        AuthenticationError: 未认证或认证失败时
+    """
+    return _post_workflow("/workflow/start", {"code": code, "params": params or {}})
+
+
+def service_start_workflow_async(code: str, params: dict | None = None) -> dict:
+    """异步启动工作流实例.
+
+    Args:
+        code: 工作流编码
+        params: 启动参数（透传给流程节点的入参）
+
+    Returns:
+        后端返回的启动结果（通常包含 taskId 等字段）
+
+    Raises:
+        DataOpsError: API 请求失败时
+        AuthenticationError: 未认证或认证失败时
+    """
+    return _post_workflow("/workflow/startAsync", {"code": code, "params": params or {}})

dataops_sdk/session.py

@@ -0,0 +1,292 @@
+import os
+from collections.abc import Mapping
+from contextlib import contextmanager
+from os import getenv
+from typing import IO, BinaryIO
+
+import httpx2
+from dataops_sdk.constants import APPLICATION_FILE, USER_INFO_FILE
+from dataops_sdk.exceptions import AuthenticationError, DataOpsError
+from dataops_sdk.schemas.user import Application, UserInfo
+from dataops_sdk.utils import get_work_dir
+from pydantic import BaseModel
+from pydantic_core import from_json, to_json
+
+
+class DataOpsConfig(BaseModel):
+    """可编程配置的 DataOps 会话参数.
+
+    优先级: 显式传入的参数 > 环境变量 > 默认值
+    """
+
+    base_url: str = getenv("DATA_OPS_BASE_URL", "http://172.168.63.85/bgw/data-ops-service")
+    username: str | None = None
+    password: str | None = None
+    token: str | None = None
+    token_type: str = "Bearer"
+    app_code: str | None = None
+    app_release: str = "1.0.0"
+
+
+# 模块级配置，可通过 dataops_sdk.configure() 修改
+_config: DataOpsConfig = DataOpsConfig()
+
+
+def configure(
+    *,
+    base_url: str | None = None,
+    username: str | None = None,
+    password: str | None = None,
+    token: str | None = None,
+    token_type: str | None = None,
+    app_code: str | None = None,
+    app_release: str | None = None,
+) -> DataOpsConfig:
+    """配置 data-ops-cli 会话参数.
+
+    可用于替代登录或补充环境变量配置，使包可在无 CLI 登录的情况下使用。
+
+    Args:
+        base_url: API 基础 URL，覆盖环境变量 DATA_OPS_BASE_URL
+        username: DataOps 用户名
+        password: DataOps 密码（仅在使用内置 login 时需要）
+        token: 直接传入访问令牌
+        token_type: 令牌类型，默认 Bearer
+        app_code: 应用编码
+        app_release: 应用版本号
+
+    Returns:
+        更新后的配置对象
+    """
+    global _config
+    if base_url is not None:
+        _config.base_url = base_url
+    if username is not None:
+        _config.username = username
+    if password is not None:
+        _config.password = password
+    if token is not None:
+        _config.token = token
+    if token_type is not None:
+        _config.token_type = token_type
+    if app_code is not None:
+        _config.app_code = app_code
+    if app_release is not None:
+        _config.app_release = app_release
+    return _config
+
+
+def get_config() -> DataOpsConfig:
+    """返回当前配置。"""
+    return _config
+
+
+def get_user_info_file_path() -> str:
+    """返回用户信息文件路径。"""
+    return get_work_dir(USER_INFO_FILE)
+
+
+def get_application_file_path() -> str:
+    """返回应用信息文件路径。"""
+    return get_work_dir(APPLICATION_FILE)
+
+
+def _load_user_info_from_file() -> UserInfo | None:
+    """从 ~/.dataops_cli/user_info.json 加载用户信息。"""
+    target_path = get_work_dir(USER_INFO_FILE)
+    if not target_path.exists():
+        return None
+    return UserInfo.model_validate_json(target_path.read_bytes())
+
+
+def _load_application_from_file() -> Application | None:
+    """从 ~/.dataops_cli/application.json 加载应用信息。"""
+    target_path = get_work_dir(APPLICATION_FILE)
+    if not target_path.exists():
+        return None
+    return Application.model_validate_json(target_path.read_bytes())
+
+
+def get_user_info(strict: bool = True) -> UserInfo | None:
+    """获取本地存储的用户信息。
+
+    优先级: 显式配置的 token > user_info.json 文件
+    """
+    if _config.token:
+        return UserInfo(
+            token_type=_config.token_type,
+            access_token=_config.token,
+            refresh_token="",
+            expires_in=0,
+        )
+    user_info = _load_user_info_from_file()
+    if user_info is None and strict:
+        print("using `data-ops-cli auth` to login first")
+        raise SystemExit(401)
+    return user_info
+
+
+def get_headers(strict: bool = True) -> Mapping[str, str]:
+    # 优先从环境变量获取
+    fmind_auth_headers = os.getenv("FMIND_AUTH_HEADERS", None)
+    if fmind_auth_headers is not None:
+        headers = from_json(fmind_auth_headers)
+        assert isinstance(headers, dict), "FMIND_AUTH_HEADERS must be a JSON object string"
+        return headers
+    # 其次从配置获取
+    user_info = get_user_info(strict=strict)
+    application = get_application(strict=strict)
+    headers = {}
+    if application is not None:
+        headers["X-App-Code"] = application.CODE
+        headers["X-App-Release"] = "1.0.0"
+    elif _config.app_code:
+        headers["X-App-Code"] = _config.app_code
+        headers["X-App-Release"] = _config.app_release
+    if not strict and user_info is None:
+        return headers
+    headers["Fmind-Auth"] = f"{user_info.token_type} {user_info.access_token}"
+    return headers
+
+
+def get_application(strict: bool = True) -> Application | None:
+    """获取当前应用信息。
+
+    优先级: 显式配置的 app_code > application.json 文件
+    """
+    if _config.app_code:
+        app_file = _load_application_from_file()
+        if app_file is not None:
+            return app_file
+        if strict:
+            print("using `data-ops-cli auth application` to set application first")
+            raise SystemExit(401)
+        return None
+    app = _load_application_from_file()
+    if app is None and strict:
+        print("using `data-ops-cli auth application` to set application first")
+        raise SystemExit(401)
+    return app
+
+
+def refresh_token(response: httpx2.Response):
+    if response.url.path.endswith("/oauth/token"):
+        return
+    if response.status_code == 200:
+        result: dict = response.json()
+    else:
+        result = dict()
+    need_auth = response.status_code == 401 and result.get("code", 400) == 401
+    if not need_auth:
+        return
+    url = "/oauth/token"
+    user_info = get_user_info(strict=True)
+    params = {
+        "refresh_token": user_info.refresh_token,
+        "grant_type": "refresh_token",
+        "scope": "all",
+    }
+    with get_session(False) as session:
+        resp = session.post(url, params=params)
+        response_body = resp.json()
+
+    if response.status_code == 200 and response_body.get("code") == 200:
+        user_info = UserInfo.model_validate(response_body["data"])
+        target_path = get_work_dir(USER_INFO_FILE)
+        target_path.write_bytes(to_json(user_info))
+        print("refresh token successfully")
+        return user_info
+    else:
+        raise AuthenticationError(
+            f"Login failed: {response_body.get('msg', f'HTTP {response.status_code}')}"
+        )
+
+
+@contextmanager
+def get_session(strict: bool = True, timeout: int = 10):
+    """获取请求 Session。
+
+    使用 httpx2 管理 HTTP 连接，base_url 指向 DataOps 服务。
+    """
+    headers = get_headers(strict)
+    with httpx2.Client(
+        headers=headers,
+        base_url=_config.base_url,
+        verify=False,
+        timeout=timeout,
+        # event_hooks={"response": [refresh_token]},
+    ) as session:
+        try:
+            yield session
+        finally:
+            session.close()
+
+
+@contextmanager
+def post_multipart(
+    url: str,
+    *,
+    files: Mapping[str, tuple[str, IO[bytes] | BinaryIO] | IO[bytes] | BinaryIO],
+    data: Mapping[str, str] | None = None,
+    headers: Mapping[str, str] | None = None,
+    timeout: int = 30,
+):
+    """multipart/form-data POST 请求上下文管理器.
+
+    自动注入 base headers（含 ``Fmind-Auth``/``X-App-Code``），并做统一的异常映射：
+    - 401 → :class:`AuthenticationError`
+    - 非 200 → :class:`DataOpsError`
+    - 未登录抛出 ``SystemExit`` → :class:`AuthenticationError`
+
+    Args:
+        url: 相对 ``base_url`` 的路径，如 ``"/data/skill/import"``.
+        files: 表单文件字段，格式为 ``{"字段名": (filename, file_obj)}`` 或 ``{"字段名": file_obj}``.
+        data: 文本表单字段，如 ``{"subType": "llm"}``.
+        headers: 额外请求头，会与 base headers 合并.
+        timeout: 请求超时秒数，默认 30s（ZIP 等大文件可能需要更长时间）.
+
+    Yields:
+        httpx2.Response: 已通过状态码校验的响应对象.
+
+    Raises:
+        AuthenticationError: 未登录或认证失效.
+        DataOpsError: API 返回非 200.
+
+    Examples:
+        >>> from pathlib import Path
+        >>> with open("skill.zip", "rb") as f:
+        ...     with post_multipart(
+        ...         "/data/skill/import",
+        ...         files={"file": ("skill.zip", f)},
+        ...         data={"subType": "llm"},
+        ...     ) as resp:
+        ...         payload = resp.json()
+    """
+    extra_headers: dict[str, str] = dict(get_headers())  # type: ignore[arg-type]
+    if headers:
+        extra_headers.update(dict(headers))
+    try:
+        with httpx2.Client(
+            headers=extra_headers,
+            base_url=_config.base_url,
+            verify=False,
+            timeout=timeout,
+        ) as client:
+            try:
+                resp = client.post(url, files=files, data=data)
+                if resp.status_code == 401:
+                    raise AuthenticationError("认证失败，请先登录")
+                if resp.status_code != 200:
+                    body: dict = {}
+                    try:
+                        body = resp.json()
+                    except Exception:
+                        pass
+                    raise DataOpsError(
+                        body.get("msg", f"HTTP {resp.status_code}"), resp.status_code
+                    )
+                yield resp
+            finally:
+                client.close()
+    except SystemExit as e:
+        raise AuthenticationError("认证失败，请先登录") from e

dataops_sdk/tiptap/__init__.py

@@ -0,0 +1,30 @@
+"""TipTap module for converting between TipTap JSON and Markdown."""
+
+from dataops_sdk.tiptap.builder import TipTapBuilder
+from dataops_sdk.tiptap.constants import (
+    AttrTypes,
+    IndentStyle,
+    Markdown,
+    MarkTypes,
+    NodeTypes,
+    Style,
+    TableStyle,
+)
+from dataops_sdk.tiptap.models import DocNode, Mark, Node, TextNode
+from dataops_sdk.tiptap.tool import TipTapTool
+
+__all__ = [
+    "TipTapTool",
+    "TipTapBuilder",
+    "AttrTypes",
+    "IndentStyle",
+    "Markdown",
+    "MarkTypes",
+    "NodeTypes",
+    "Style",
+    "TableStyle",
+    "DocNode",
+    "Mark",
+    "Node",
+    "TextNode",
+]

dataops_sdk/tiptap/builder.py

@@ -0,0 +1,75 @@
+"""TipTapBuilder factory for creating TipTapTool instances."""
+
+from dataops_sdk.tiptap import constants
+from dataops_sdk.tiptap.tool import TipTapTool
+
+
+class TipTapBuilder:
+    """Builder for TipTapTool instances.
+
+    Supports creating TipTapTool with default or custom configurations.
+    """
+
+    @staticmethod
+    def build(
+        indent_style: str = constants.Style.INDENT_STYLE_SPACE,
+        indent_size: int = constants.Style.DEFAULT_INDENT_SIZE,
+        table_style: str = constants.Style.DEFAULT_TABLE_STYLE,
+    ) -> TipTapTool:
+        """Build with configuration.
+
+        Args:
+            indent_style: Indent style (space or tab)
+            indent_size: Number of indent characters
+            table_style: Table rendering style (markdown or html)
+
+        Returns:
+            TipTapTool instance with settings
+        """
+        return TipTapTool(
+            indent_style=indent_style,
+            indent_size=indent_size,
+            table_style=table_style,
+        )
+
+    @staticmethod
+    def create_default() -> TipTapTool:
+        """Create with default configuration.
+
+        Returns:
+            TipTapTool instance with default settings
+        """
+        return TipTapTool()
+
+    @staticmethod
+    def create_with_table_style(table_style: str) -> TipTapTool:
+        """Create with custom table style.
+
+        Args:
+            table_style: Table rendering style (markdown or html)
+
+        Returns:
+            TipTapTool instance with custom table style
+        """
+        return TipTapTool(
+            indent_style=constants.Style.INDENT_STYLE_SPACE,
+            indent_size=constants.Style.DEFAULT_INDENT_SIZE,
+            table_style=table_style,
+        )
+
+    @staticmethod
+    def create_with_indent_config(indent_style: str, indent_size: int) -> TipTapTool:
+        """Create with custom indent configuration.
+
+        Args:
+            indent_style: Indent style (space or tab)
+            indent_size: Number of indent characters
+
+        Returns:
+            TipTapTool instance with custom indent settings
+        """
+        return TipTapTool(
+            indent_style=indent_style,
+            indent_size=indent_size,
+            table_style=constants.Style.DEFAULT_TABLE_STYLE,
+        )