dataops-sdk 0.3.1__tar.gz → 0.3.2__tar.gz

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dataops-sdk
-Version: 0.3.1
+Version: 0.3.2
 Summary: Python SDK for the DataOps platform.
 Requires-Python: >=3.11
 Requires-Dist: pydantic<3,>=2
@@ -8,7 +8,7 @@ Requires-Dist: pydantic-core
 Requires-Dist: pydantic-settings>=2.14.2
 Requires-Dist: httpx2>=2.5.0
 Requires-Dist: jinja2>=3.1.6
-Requires-Dist: markdown-it-py<4,>=3
+Requires-Dist: markdown-it-py[plugins]
 Requires-Dist: cryptography>=49.0.0
 Provides-Extra: runner
 Requires-Dist: paramiko>4; extra == "runner"

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/pyproject.toml

@@ -13,7 +13,7 @@ dependencies = [
     "pydantic-settings>=2.14.2",
     "httpx2>=2.5.0",
     "jinja2>=3.1.6",
-    "markdown-it-py>=3,<4",
+    "markdown-it-py[plugins]",
     "cryptography>=49.0.0",
 ]
 

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/src/dataops_sdk/__init__.py

@@ -1,3 +1,10 @@
+"""DataOps 平台 SDK.
+
+对外暴露子模块 ``runner``、``schemas``、``utils`` 以及 ``services`` 中的全部平台操作函数，
+供 ``data-ops-cli`` 命令行工具及外部调用方复用。可选的 ``runner`` extra 提供数据库与
+Nacos 集成能力，未安装时仍可独立导入本包核心功能。
+"""
+
 from . import runner, schemas, utils
 from .services import (  # noqa: F401
     release_list_create,
@@ -89,4 +96,4 @@ from .services import (  # noqa: F401
     service_update_data_table_record_by_id_list,
 )
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"

dataops_sdk-0.3.2/src/dataops_sdk/constants.py

@@ -0,0 +1,15 @@
+"""dataops_sdk 的全局常量定义.
+
+集中维护 SDK 内部使用的固定文件名、默认值等常量，便于在多个模块间共享：
+
+- ``USER_INFO_FILE``：本地缓存用户信息（含 access_token / refresh_token）的文件名。
+- ``APPLICATION_FILE``：本地缓存当前应用上下文（应用编码、版本等）的文件名。
+- ``DEFAULT_SECRET_KEY``：未显式配置时用于本地凭据加密的内置密钥（仅用于本地持久化场景）。
+"""
+
+from typing import Final
+
+USER_INFO_FILE: Final[str] = "user_info.json"
+APPLICATION_FILE: Final[str] = "application.json"
+
+DEFAULT_SECRET_KEY: Final[str] = "e0XxEhkWSJcA6Aps"

dataops_sdk-0.3.2/src/dataops_sdk/exceptions.py

@@ -0,0 +1,45 @@
+"""dataops_sdk 自定义异常层级.
+
+定义 SDK 与后端交互过程中可能抛出的异常类型。``DataOpsError`` 作为基类，聚合消息
+与可选的 HTTP 状态码；下层异常类用于在 SDK 与 CLI 中区分典型错误场景（资源缺失、
+认证失败、写入失败等），便于调用方按类型进行捕获与分支处理。
+"""
+
+
+class DataOpsError(Exception):
+    """DataOps API 错误基类。"""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        """初始化 DataOps 错误。
+
+        Args:
+            message: 人类可读的错误描述，会同时用于 ``args`` 与 ``str(exc)`` 输出。
+            status_code: 可选的 HTTP 状态码，便于上层根据响应码分类处理。
+        """
+        self.message = message
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class NotFoundError(DataOpsError):
+    """资源未找到。"""
+
+    pass
+
+
+class AuthenticationError(DataOpsError):
+    """认证失败异常。"""
+
+    pass
+
+
+class FailedToCreateError(DataOpsError):
+    """创建失败异常。"""
+
+    pass
+
+
+class FailedToUpdateError(DataOpsError):
+    """更新失败异常。"""
+
+    pass

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/src/dataops_sdk/runner/__init__.py

@@ -4,11 +4,11 @@
 可作为独立模块被导入使用。
 
 Modules:
-    schemas: Nacos 配置数据模型
-    utils: 通用工具（数据库连接、加密、日志等）
+    schemas: Nacos 配置数据模型.
+    utils: 通用工具（数据库连接、加密、日志等）.
 
 Example:
-    >>> from runner.utils import DatabaseConn, DuckDBManager
+    >>> from dataops_sdk.runner import DatabaseConn, getLogger
 """
 
 from .datasource_factory import get_datasource_instent
@@ -23,7 +23,6 @@ from .utils import (
     encrypt_body,
     generate_uuid,
     get_service_instance,
-    getLogger,
     parse_args,
     print_json,
 )
@@ -36,7 +35,6 @@ __all__ = [
     "Neo4jConn",
     "decrypt_body",
     "encrypt_body",
-    "getLogger",
     "print_json",
     "generate_uuid",
     "parse_args",

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/src/dataops_sdk/runner/datasource_factory.py

@@ -1,5 +1,4 @@
-"""
-数据源实例工厂模块。
+"""数据源实例工厂模块。
 
 根据数据源元数据动态创建对应的连接实例（数据库或消息队列）。
 """

dataops_sdk-0.3.2/src/dataops_sdk/runner/schemas/nacos/__init__.py

@@ -0,0 +1,11 @@
+"""Nacos 配置中心 schema 集合。
+
+聚合 Nacos 配置、服务发现与命名空间相关的数据模型，对外暴露
+``NacosSettings``、``Service`` 与 ``Instance`` 等常用模型。
+"""
+
+from .config import NacosSettings
+from .instance import Instance
+from .service import Service
+
+__all__ = ["Service", "Instance", "NacosSettings"]

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/src/dataops_sdk/runner/schemas/nacos/config.py

@@ -24,17 +24,19 @@ class NacosSettings(BaseSettings):
     子系统连接和 Nacos 服务发现参数。
 
     Attributes:
-        nacos_addrs: NACOS服务地址
-        nacos_user: NACOS用户名
-        nacos_password: NACOS密码
-        nacos_discovery_namespace: NACOS服务发现命名空间
-        nacos_group_name: NACOS服务发现组名
+        nacos_addrs: Nacos 服务地址（IP:PORT 形式，多个地址以英文逗号分隔）。
+        nacos_user: Nacos 鉴权用户名。
+        nacos_password: Nacos 鉴权密码。
+        nacos_discovery_namespace: Nacos 服务发现使用的命名空间 ID。
+        nacos_group_name: Nacos 服务发现使用的默认分组名，缺省 ``DEFAULT_GROUP``。
     """
 
-    nacos_addrs: Annotated[str, Field(description="NACOS服务地址")]
-    nacos_user: Annotated[str, Field(description="NACOS用户名")]
-    nacos_password: Annotated[str, Field(description="NACOS密码")]
-    nacos_discovery_namespace: Annotated[str, Field(description="NACOS服务发现命名空间")]
-    nacos_group_name: Annotated[str, Field(description="NACOS服务发现组名")] = "DEFAULT_GROUP"
+    nacos_addrs: Annotated[str, Field(description="Nacos 服务地址")]
+    nacos_user: Annotated[str, Field(description="Nacos 用户名")]
+    nacos_password: Annotated[str, Field(description="Nacos 密码")]
+    nacos_discovery_namespace: Annotated[str, Field(description="Nacos 服务发现命名空间 ID")]
+    nacos_group_name: Annotated[str, Field(description="Nacos 服务发现默认分组名")] = (
+        "DEFAULT_GROUP"
+    )
 
     model_config = SettingsConfigDict(extra="ignore")

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/src/dataops_sdk/runner/schemas/nacos/constants.py

@@ -1,4 +1,13 @@
+"""Nacos 客户端常量集合。
+
+集中定义 Nacos 客户端在协议、HTTP 头、超时与命名空间等场景下
+复用的常量值，来源参考 Nacos 官方 OpenAPI 与 Python 客户端实现。
+"""
+
+
 class Constants:
+    """Nacos 客户端常量集合。"""
+
     NAMING_MODULE = "naming"
 
     CONFIG_MODULE = "config"

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/src/dataops_sdk/runner/schemas/nacos/instance.py

@@ -1,3 +1,9 @@
+"""Nacos 服务实例模型。
+
+定义 Nacos 服务发现场景下的注册实例数据结构，并提供与官方 Java
+客户端行为对齐的合法性校验与元数据辅助方法。
+"""
+
 from __future__ import annotations
 
 import re
@@ -11,16 +17,34 @@ from .preserved_metadata_key import PreservedMetadataKeys
 
 
 class Instance(BaseModel):
-    instanceId: Annotated[str, Field(description="实例ID")] = ""
-    ip: Annotated[str, Field(description="实例IP地址")]
-    port: Annotated[int, Field(description="实例端口号")]
-    weight: Annotated[float, Field(description="实例权重")] = 1.0
-    healthy: Annotated[bool, Field(description="实例健康状态")] = True
+    """Nacos 服务注册实例。
+
+    用于描述一个注册到 Nacos 服务发现体系中的服务实例，包含网络
+    信息、健康状态、所属集群以及自定义元数据。
+
+    Attributes:
+        instanceId: 实例唯一标识，缺省时由客户端按 IP、端口、集群等规则生成。
+        ip: 实例对外提供服务的 IP 地址。
+        port: 实例对外提供服务的端口号，范围 ``0``-``65535``。
+        weight: 实例权重，默认为 ``1.0``，用于负载均衡。
+        healthy: 实例是否处于健康状态，默认为 ``True``。
+        enabled: 实例是否启用，禁用后不会出现在订阅结果中。
+        ephemeral: 是否为临时实例，临时实例通过心跳维持注册状态。
+        clusterName: 实例所属集群名称，缺省为 ``DEFAULT``。
+        serviceName: 实例所属服务名称。
+        metadata: 实例自定义元数据键值对。
+    """
+
+    instanceId: Annotated[str, Field(description="实例唯一标识")] = ""
+    ip: Annotated[str, Field(description="实例对外提供服务的 IP 地址")]
+    port: Annotated[int, Field(description="实例对外提供服务的端口号")]
+    weight: Annotated[float, Field(description="实例权重，负载均衡时使用")] = 1.0
+    healthy: Annotated[bool, Field(description="实例是否处于健康状态")] = True
     enabled: Annotated[bool, Field(description="实例是否启用")] = True
-    ephemeral: Annotated[bool, Field(description="实例是否临时实例")] = True
-    clusterName: Annotated[str, Field(description="实例所在集群名称")] = ""
-    serviceName: Annotated[str, Field(description="实例所在服务名称")] = ""
-    metadata: Annotated[dict, Field(description="实例元数据")] = {}
+    ephemeral: Annotated[bool, Field(description="是否为临时实例")] = True
+    clusterName: Annotated[str, Field(description="实例所属集群名称")] = ""
+    serviceName: Annotated[str, Field(description="实例所属服务名称")] = ""
+    metadata: Annotated[dict, Field(description="实例自定义元数据")] = {}
 
     def __str__(self):
         return f"Instance({', '.join(f'{key}={value!r}' for key, value in self.__dict__.items())})"

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/src/dataops_sdk/runner/schemas/nacos/nacos_exception.py

@@ -1,3 +1,8 @@
+"""Nacos 客户端异常与错误码定义。
+
+集中声明 Nacos 客户端在调用过程中使用的错误码常量及统一异常类。
+"""
+
 CLIENT_INVALID_PARAM = -400
 
 CLIENT_DISCONNECT = -401
@@ -36,7 +41,7 @@ HTTP_CLIENT_ERROR_CODE = -500
 
 
 class NacosException(Exception):
-    """Custom exception class with an error code attribute."""
+    """Nacos 客户端统一异常，携带错误码与可读消息。"""
 
     def __init__(self, error_code, message="An error occurred"):
         self.error_code = error_code

dataops_sdk-0.3.2/src/dataops_sdk/runner/schemas/nacos/naming_param.py

@@ -0,0 +1,140 @@
+"""Nacos 命名空间 API 调用参数模型。
+
+定义调用 Nacos OpenAPI 命名空间相关接口时使用的请求参数模型，
+覆盖实例注册、注销、查询、订阅与服务列表等常见场景。
+"""
+
+from collections.abc import Callable
+from typing import Annotated
+
+from pydantic import BaseModel, Field
+
+from .constants import Constants
+
+
+class RegisterInstanceParam(BaseModel):
+    """注册单个实例到 Nacos 服务时的入参。
+
+    Attributes:
+        ip: 待注册实例的 IP 地址。
+        port: 待注册实例的端口号。
+        weight: 实例权重，默认 ``1.0``。
+        enabled: 是否启用实例，默认 ``True``。
+        healthy: 实例初始健康状态，默认 ``True``。
+        metadata: 实例自定义元数据键值对。
+        cluster_name: 所属集群名称，缺省为空（实际生效为默认集群）。
+        service_name: 目标服务名称。
+        group_name: 服务所在分组，默认 ``DEFAULT_GROUP``。
+        ephemeral: 是否注册为临时实例，默认 ``True``。
+    """
+
+    ip: Annotated[str, Field(description="待注册实例的 IP 地址")]
+    port: Annotated[int, Field(description="待注册实例的端口号")]
+    weight: Annotated[float, Field(description="实例权重，负载均衡时使用")] = 1.0
+    enabled: Annotated[bool, Field(description="是否启用实例")] = True
+    healthy: Annotated[bool, Field(description="实例初始健康状态")] = True
+    metadata: Annotated[dict[str, str], Field(description="实例自定义元数据")] = {}
+    cluster_name: Annotated[str, Field(description="所属集群名称")] = ""
+    service_name: Annotated[str, Field(description="目标服务名称")]
+    group_name: Annotated[str, Field(description="服务所在分组")] = Constants.DEFAULT_GROUP
+    ephemeral: Annotated[bool, Field(description="是否注册为临时实例")] = True
+
+
+class BatchRegisterInstanceParam(BaseModel):
+    """批量注册实例的入参。
+
+    Attributes:
+        service_name: 目标服务名称。
+        group_name: 服务所在分组，默认 ``DEFAULT_GROUP``。
+        instances: 待注册的实例参数列表。
+    """
+
+    service_name: Annotated[str, Field(description="目标服务名称")]
+    group_name: Annotated[str, Field(description="服务所在分组")] = Constants.DEFAULT_GROUP
+    instances: Annotated[
+        list[RegisterInstanceParam], Field(description="待注册的实例参数列表")
+    ] = []
+
+
+class DeregisterInstanceParam(BaseModel):
+    """注销实例的入参。
+
+    Attributes:
+        ip: 待注销实例的 IP 地址。
+        port: 待注销实例的端口号。
+        cluster_name: 所属集群名称，缺省为空（实际生效为默认集群）。
+        service_name: 目标服务名称。
+        group_name: 服务所在分组，默认 ``DEFAULT_GROUP``。
+        ephemeral: 待注销实例是否为临时实例，默认 ``True``。
+    """
+
+    ip: Annotated[str, Field(description="待注销实例的 IP 地址")]
+    port: Annotated[int, Field(description="待注销实例的端口号")]
+    cluster_name: Annotated[str, Field(description="所属集群名称")] = ""
+    service_name: Annotated[str, Field(description="目标服务名称")]
+    group_name: Annotated[str, Field(description="服务所在分组")] = Constants.DEFAULT_GROUP
+    ephemeral: Annotated[bool, Field(description="待注销实例是否为临时实例")] = True
+
+
+class ListInstanceParam(BaseModel):
+    """查询服务实例列表的入参。
+
+    Attributes:
+        service_name: 目标服务名称。
+        group_name: 服务所在分组，默认 ``DEFAULT_GROUP``。
+        clusters: 仅查询指定集群的实例列表。
+        subscribe: 是否同时订阅该服务的变更，默认 ``True``。
+        healthy_only: 是否仅返回健康实例，``None`` 表示不过滤。
+    """
+
+    service_name: Annotated[str, Field(description="目标服务名称")]
+    group_name: Annotated[str, Field(description="服务所在分组")] = Constants.DEFAULT_GROUP
+    clusters: Annotated[list[str], Field(description="仅查询指定集群的实例列表")] = []
+    subscribe: Annotated[bool, Field(description="是否同时订阅该服务的变更")] = True
+    healthy_only: Annotated[bool | None, Field(description="是否仅返回健康实例")] = None
+
+
+class SubscribeServiceParam(BaseModel):
+    """订阅服务变更的入参。
+
+    Attributes:
+        service_name: 目标服务名称。
+        group_name: 服务所在分组，默认 ``DEFAULT_GROUP``。
+        clusters: 仅订阅指定集群的实例变更。
+        subscribe_callback: 服务变更回调函数，``None`` 表示无回调。
+    """
+
+    service_name: Annotated[str, Field(description="目标服务名称")]
+    group_name: Annotated[str, Field(description="服务所在分组")] = Constants.DEFAULT_GROUP
+    clusters: Annotated[list[str], Field(description="仅订阅指定集群的实例变更")] = []
+    subscribe_callback: Annotated[Callable | None, Field(description="服务变更回调函数")] = None
+
+
+class GetServiceParam(BaseModel):
+    """获取单个服务信息的入参。
+
+    Attributes:
+        service_name: 目标服务名称。
+        group_name: 服务所在分组，默认 ``DEFAULT_GROUP``。
+        clusters: 仅查询指定集群的实例。
+    """
+
+    service_name: Annotated[str, Field(description="目标服务名称")]
+    group_name: Annotated[str, Field(description="服务所在分组")] = Constants.DEFAULT_GROUP
+    clusters: Annotated[list[str], Field(description="仅查询指定集群的实例")] = []
+
+
+class ListServiceParam(BaseModel):
+    """分页查询服务列表的入参。
+
+    Attributes:
+        namespace_id: 命名空间 ID，缺省为 ``Constants.DEFAULT_NAMESPACE_ID``。
+        group_name: 服务所在分组，默认 ``DEFAULT_GROUP``。
+        page_no: 查询页码，从 ``1`` 开始，默认 ``1``。
+        page_size: 每页返回数量，默认 ``10``。
+    """
+
+    namespace_id: Annotated[str, Field(description="命名空间 ID")] = Constants.DEFAULT_NAMESPACE_ID
+    group_name: Annotated[str, Field(description="服务所在分组")] = Constants.DEFAULT_GROUP
+    page_no: Annotated[int, Field(description="查询页码，从 1 开始")] = 1
+    page_size: Annotated[int, Field(description="每页返回数量")] = 10

dataops_sdk-0.3.2/src/dataops_sdk/runner/schemas/nacos/naming_request.py

@@ -0,0 +1,148 @@
+"""Nacos 命名空间 gRPC 请求模型。
+
+定义通过 gRPC 通道向 Nacos 服务器发起命名空间相关操作时的请求结构，
+包含抽象基类及若干具体操作类型的请求模型。
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from typing import Annotated
+
+from pydantic import Field
+from v2.nacos.naming.model.instance import Instance
+from v2.nacos.transport.model.rpc_request import Request
+
+from .service import Service
+
+
+class AbstractNamingRequest(Request, ABC):
+    """命名空间相关 gRPC 请求的抽象基类。
+
+    统一携带命名空间、服务名和分组等公共字段，子类需实现
+    :meth:`get_request_type` 标识具体请求类型。
+
+    Attributes:
+        namespace: 命名空间 ID，缺省为空字符串。
+        serviceName: 目标服务名称，缺省为空字符串。
+        groupName: 服务所在分组名称，缺省为空字符串。
+    """
+
+    namespace: Annotated[str | None, Field(description="命名空间 ID")] = ""
+    serviceName: Annotated[str | None, Field(description="目标服务名称")] = ""
+    groupName: Annotated[str | None, Field(description="服务所在分组名称")] = ""
+
+    def get_module(self):
+        return "naming"
+
+    def get_request_type(self) -> str:
+        """返回请求类型标识，子类必须重写。"""
+        raise NotImplementedError("Subclasses should implement this method.")
+
+
+NOTIFY_SUBSCRIBER_REQUEST_TYPE = "NotifySubscriberRequest"
+
+
+class ServiceQueryRequest(AbstractNamingRequest):
+    """服务信息查询请求。
+
+    Attributes:
+        cluster: 目标集群名称。
+        healthOnly: 是否仅返回健康实例。
+        udpPort: 客户端 UDP 推送端口，默认 ``None``。
+    """
+
+    cluster: Annotated[str | None, Field(description="目标集群名称")]
+    healthOnly: Annotated[bool | None, Field(description="是否仅返回健康实例")]
+    udpPort: Annotated[int | None, Field(description="客户端 UDP 推送端口")] = None
+
+    def get_request_type(self) -> str:
+        return "ServiceQueryRequest"
+
+
+class InstanceRequest(AbstractNamingRequest):
+    """单个实例的注册、注销或更新请求。
+
+    Attributes:
+        type: 操作类型，例如 ``registerInstance``、``deregisterInstance`` 等。
+        instance: 待操作的实例对象。
+    """
+
+    type: Annotated[str | None, Field(description="实例操作类型")]
+    instance: Annotated[Instance | None, Field(description="待操作的实例对象")]
+
+    def get_request_type(self) -> str:
+        return "InstanceRequest"
+
+
+class PersistentInstanceRequest(AbstractNamingRequest):
+    """持久化实例请求。
+
+    Attributes:
+        type: 操作类型，例如注册、注销等。
+        instance: 待操作的实例对象。
+    """
+
+    type: Annotated[str | None, Field(description="持久化实例操作类型")]
+    instance: Annotated[Instance | None, Field(description="待操作的实例对象")]
+
+    def get_request_type(self) -> str:
+        return "PersistentInstanceRequest"
+
+
+class BatchInstanceRequest(AbstractNamingRequest):
+    """批量实例请求。
+
+    Attributes:
+        type: 批量操作类型。
+        instances: 待操作的实例对象列表。
+    """
+
+    type: Annotated[str | None, Field(description="批量实例操作类型")]
+    instances: Annotated[list[Instance] | None, Field(description="待操作的实例对象列表")]
+
+    def get_request_type(self) -> str:
+        return "BatchInstanceRequest"
+
+
+class NotifySubscriberRequest(AbstractNamingRequest):
+    """订阅变更通知请求。
+
+    Attributes:
+        serviceInfo: 推送的服务信息。
+    """
+
+    serviceInfo: Annotated[Service | None, Field(description="推送的服务信息")]
+
+    def get_request_type(self) -> str:
+        return "NotifySubscriberRequest"
+
+
+class ServiceListRequest(AbstractNamingRequest):
+    """服务列表查询请求。
+
+    Attributes:
+        pageNo: 查询页码，从 ``1`` 开始。
+        pageSize: 每页返回数量。
+    """
+
+    pageNo: Annotated[int | None, Field(description="查询页码")]
+    pageSize: Annotated[int | None, Field(description="每页返回数量")]
+
+    def get_request_type(self) -> str:
+        return "ServiceListRequest"
+
+
+class SubscribeServiceRequest(AbstractNamingRequest):
+    """服务订阅请求。
+
+    Attributes:
+        subscribe: 是否开启订阅。
+        clusters: 关注的集群名称列表。
+    """
+
+    subscribe: Annotated[bool | None, Field(description="是否开启订阅")]
+    clusters: Annotated[str | None, Field(description="关注的集群名称列表")]
+
+    def get_request_type(self) -> str:
+        return "SubscribeServiceRequest"

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/src/dataops_sdk/runner/schemas/nacos/naming_response.py

@@ -1,3 +1,9 @@
+"""Nacos 命名空间 gRPC 响应模型。
+
+定义通过 gRPC 通道从 Nacos 服务器接收命名空间相关操作的响应结构，
+覆盖订阅通知、服务查询、实例操作及服务列表查询等场景。
+"""
+
 from __future__ import annotations
 
 from typing import Annotated
@@ -8,12 +14,20 @@ from v2.nacos.transport.model.rpc_response import Response
 
 
 class NotifySubscriberResponse(Response):
+    """订阅变更通知响应。"""
+
     def get_response_type(self) -> str:
         return "NotifySubscriberResponse"
 
 
 class QueryServiceResponse(Response):
-    serviceInfo: Annotated[Service | None, Field(description="服务信息")] = None
+    """服务信息查询响应。
+
+    Attributes:
+        serviceInfo: 服务信息负载。
+    """
+
+    serviceInfo: Annotated[Service | None, Field(description="服务信息负载")] = None
 
     def get_service_info(self) -> Service:
         return self.serviceInfo
@@ -23,7 +37,13 @@ class QueryServiceResponse(Response):
 
 
 class SubscribeServiceResponse(Response):
-    serviceInfo: Annotated[Service | None, Field(description="服务信息")] = None
+    """服务订阅响应。
+
+    Attributes:
+        serviceInfo: 服务信息负载。
+    """
+
+    serviceInfo: Annotated[Service | None, Field(description="服务信息负载")] = None
 
     def get_response_type(self) -> str:
         return "SubscribeServiceResponse"
@@ -33,17 +53,28 @@ class SubscribeServiceResponse(Response):
 
 
 class InstanceResponse(Response):
+    """实例操作响应。"""
+
     def get_response_type(self) -> str:
         return "InstanceResponse"
 
 
 class BatchInstanceResponse(Response):
+    """批量实例操作响应。"""
+
     def get_response_type(self) -> str:
         return "BatchInstanceResponse"
 
 
 class ServiceListResponse(Response):
-    count: Annotated[int, Field(description="服务数量")]
+    """服务列表查询响应。
+
+    Attributes:
+        count: 满足条件的服务总数。
+        serviceNames: 服务名称列表。
+    """
+
+    count: Annotated[int, Field(description="满足条件的服务总数")]
     serviceNames: Annotated[list[str], Field(description="服务名称列表")]
 
     def get_response_type(self) -> str:

{dataops_sdk-0.3.1 → dataops_sdk-0.3.2}/src/dataops_sdk/runner/schemas/nacos/preserved_metadata_key.py

@@ -1,3 +1,10 @@
+"""Nacos 实例保留元数据键常量。
+
+集中定义 Nacos 客户端在实例元数据中识别的保留键，这些键用于
+控制心跳超时、IP 删除超时以及实例 ID 生成策略等行为。
+"""
+
+
 class PreservedMetadataKeys:
     REGISTER_SOURCE = "preserved.register.source"