alpha-dc-client 0.1.23__py2.py3-none-any.whl

alpha_dc_client-0.1.23.dist-info/METADATA

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: alpha-dc-client
+Version: 0.1.23
+Author-email: Hang GuangLiang <hanguangliang@alphaaidig.com>
+Requires-Dist: dc-common==0.1.23
+Requires-Dist: httpx

alpha_dc_client-0.1.23.dist-info/RECORD

@@ -0,0 +1,11 @@
+dc_client/__init__.py,sha256=kkr3Y8U6OWF2oWYYjLF0HRJ2pnLnoALjzyGJIBWsSSU,338
+dc_client/base.py,sha256=k5X3-kMQq7ULH_N1NVloI0ji8Ks6ZPifVxZ_LaVcEx4,2584
+dc_client/client.py,sha256=oDvvtp1CV1hyRE6-8T85r13jfCGxZfOt6gj46yJ0LMI,7463
+dc_client/client.pyi,sha256=q7C7TeS7GUUylMOxxojvKt7-6d-yNogIvCR4CQB1Go8,3460
+dc_client/exceptions.py,sha256=AHt-PVeBaly7-ehPrMRJlZrC6Ew_o1nuX_5gxcJUwaY,927
+dc_client/run_tests.py,sha256=QGPDge-ZLUd9yNZxlQgX-n2LsgHwT72myZSkREyIPKw,10831
+dc_client/tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dc_client/tests/base.py,sha256=p4txw8eWvD2-JnMOgADGlFgWLOTcxznIcKz7RzhuQ3U,5535
+alpha_dc_client-0.1.23.dist-info/METADATA,sha256=S8LqqCS5nOZIeQ1DQlQe38HyLy2YTqKB0d059N7czVc,175
+alpha_dc_client-0.1.23.dist-info/WHEEL,sha256=aha0VrrYvgDJ3Xxl3db_g_MDIW-ZexDdrc_m-Hk8YY4,105
+alpha_dc_client-0.1.23.dist-info/RECORD,,

alpha_dc_client-0.1.23.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py2-none-any
+Tag: py3-none-any

dc_client/__init__.py

@@ -0,0 +1,13 @@
+from .exceptions import APIError, AuthenticationError, NotFoundError, InvalidRequestError
+from .client import DataApi, init, PageDataFrame, DatacenterAPIError
+
+__all__ = [
+    "DataApi",
+    "init",
+    "PageDataFrame",
+    "DatacenterAPIError",
+    "APIError",
+    "AuthenticationError",
+    "NotFoundError",
+    "InvalidRequestError",
+]

dc_client/base.py

@@ -0,0 +1,69 @@
+import httpx
+from typing import Optional, Dict, Any
+
+from .exceptions import APIError, AuthenticationError, NotFoundError, InvalidRequestError
+
+class BaseClient:
+    """
+    A base client for making requests to the Datacenter API.
+    """
+    def __init__(self, base_url: str, token: Optional[str] = None, timeout: int = 30):
+        """
+        Initializes the API client.
+
+        Args:
+            base_url: The base URL for the API, e.g., "http://localhost:10000".
+            token: An optional token for authentication.
+            timeout: The request timeout in seconds.
+        """
+        self._base_url = base_url.rstrip('/')
+        self._token = token
+        self._timeout = timeout
+        
+        headers = {"Content-Type": "application/json"}
+        if self._token:
+            headers["X-API-Key"] = self._token
+            
+        self._http_client = httpx.Client(base_url=self._base_url, headers=headers, timeout=self._timeout)
+
+    def _request(self, method: str, endpoint: str, params: Optional[Dict[str, Any]] = None, json: Optional[Dict[str, Any]] = None) -> Any:
+        """
+        Makes an HTTP request and handles potential errors.
+        """
+        try:
+            response = self._http_client.request(method, endpoint, params=params, json=json)
+            response.raise_for_status()
+            
+            response_data = response.json()
+            if response_data.get("status") == "success":
+                return response_data
+            
+            raise APIError(f"API returned non-success status: {response_data.get('status', 'N/A')}", status_code=response.status_code)
+
+        except httpx.HTTPStatusError as e:
+            status_code = e.response.status_code
+            try:
+                detail = e.response.json().get("detail", e.response.text)
+            except Exception:
+                detail = e.response.text
+
+            if status_code == 404:
+                raise NotFoundError(detail) from e
+            elif status_code in [401, 403]:
+                raise AuthenticationError(detail) from e
+            elif status_code == 400:
+                raise InvalidRequestError(detail) from e
+            else:
+                raise APIError(f"HTTP Error: {detail}", status_code=status_code) from e
+        except httpx.RequestError as e:
+            raise APIError(f"Request failed: {e}") from e
+
+    def close(self):
+        """Closes the underlying HTTP client."""
+        self._http_client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()

dc_client/client.py

@@ -0,0 +1,221 @@
+"""
+通用客户端
+提供简洁的数据查询接口
+"""
+import pandas as pd
+import json
+import requests
+from functools import partial
+from dc_common.schemas import ResultType
+
+
+class PageDataFrame(pd.DataFrame):
+    """
+    带分页信息的DataFrame
+
+    继承自pandas.DataFrame，添加分页相关的属性和方法
+    """
+
+    _metadata = ['_pagination']
+
+    def __init__(self, data=None, index=None, columns=None, dtype=None, copy=False, pagination=None):
+        super().__init__(data=data, index=index, columns=columns, dtype=dtype, copy=copy)
+        self._pagination = pagination or {}
+
+    @property
+    def pagination(self):
+        """获取分页信息"""
+        return self._pagination
+
+    @property
+    def has_pagination(self):
+        """是否有分页信息"""
+        return bool(self._pagination)
+
+    @property
+    def current_page(self):
+        """当前页码"""
+        return self._pagination.get('page', 1)
+
+    @property
+    def page_size(self):
+        """每页大小"""
+        return self._pagination.get('page_size', len(self))
+
+    @property
+    def total_count(self):
+        """总记录数"""
+        return self._pagination.get('total', len(self))
+
+    @property
+    def total_pages(self):
+        """总页数"""
+        total = self.total_count
+        size = self.page_size
+        return (total + size - 1) // size if size > 0 else 1
+
+    def __repr__(self):
+        base_repr = super().__repr__()
+        if self.has_pagination:
+            pagination_info = f"Page {self.current_page}/{self.total_pages} (Total: {self.total_count})"
+            return f"{base_repr}\n[Pagination: {pagination_info}]"
+        return base_repr
+
+
+class DatacenterAPIError(Exception):
+    """数据中心API异常类"""
+
+    def __init__(self, code: int, message: str):
+        self.code = code
+        self.message = message
+        super().__init__(f"API错误 (code: {code}): {message}")
+
+
+class DataApi:
+    """
+    简洁通用数据API客户端
+
+    使用方式：
+    ```python
+    import dc_client as dc
+
+    # 初始化客户端
+    client = dc.api(token='your_token', base_url='http://localhost:10000')
+
+    # 查询HSGT分页数据
+    df = client.hsgt_page_list(page=1, page_size=20)
+
+    # 查询指定字段的HSGT分页数据
+    df = client.hsgt_page_list(page=1, page_size=10, fields='trade_date,stock_code,stock_name,hold_market_cap')
+
+    # 按股票代码查询HSGT数据
+    df = client.hsgt_by_stock(stock_code='00700.HK', limit=50)
+
+    # 按股票代码查询并指定字段
+    df = client.hsgt_by_stock(stock_code='00700.HK', limit=10, fields='trade_date,stock_code,stock_name,hold_market_cap')
+    ```
+    """
+
+    def __init__(self, token: str, base_url: str = '', local: bool = False, timeout: int = 30):
+        """
+        初始化客户端
+
+        Args:
+            token: API认证token
+            base_url: API服务基础URL，为空时根据local参数使用默认值
+            local: 是否为本地环境，为True时默认使用http://localhost:10000
+            timeout: 请求超时时间
+        """
+        self.__token = token
+
+        # 处理base_url逻辑
+        if not base_url:
+            base_url = 'http://localhost:10000' if local else 'https://data.alphaaidig.com'
+
+        # base_url.rstrip('/') 的作用是移除URL末尾的斜杠
+        # 例如: 'http://localhost:10000/' -> 'http://localhost:10000'
+        #      'http://localhost:10000'  -> 'http://localhost:10000'
+        # 这样可以确保拼接API路径时不会出现双斜杠
+        self.__base_url = base_url.rstrip('/')
+        self.__timeout = timeout
+        self.__dataapi_url = f"{self.__base_url}/api/v1/dataapi"
+
+    def query(self, api_name: str, fields: str = '', **kwargs) -> pd.DataFrame:
+        """
+        通用查询方法，与tushare的query方法完全一致
+
+        Args:
+            api_name: API名称，如'hsgt_south_fund'
+            fields: 需要返回的字段，逗号分隔，如'trade_date,stock_code,stock_name'
+            **kwargs: 查询参数
+
+        Returns:
+            pd.DataFrame: 查询结果
+        """
+        # 扁平化参数格式，与API期望格式一致
+        req_params = kwargs.copy()
+        req_params['fields'] = fields
+
+        try:
+            # 发送HTTP请求
+            url = f"{self.__dataapi_url}/{api_name}"
+            headers = {
+                'X-API-Key': self.__token,
+                'Content-Type': 'application/json'
+            }
+            res = requests.post(url, json=req_params, headers=headers, timeout=self.__timeout)
+
+            if res.status_code != 200:
+                raise Exception(f"HTTP请求失败，状态码: {res.status_code}")
+
+            result = res.json()
+
+            # 检查响应状态
+            if result.get('code') != 0:
+                raise DatacenterAPIError(
+                    code=result.get('code', -1),
+                    message=result.get('msg', '未知错误')
+                )
+
+            # 解析数据
+            data = result.get('data', {})
+            if not data:
+                return pd.DataFrame()
+
+            # 根据结果类型转换为DataFrame
+            result_type = ResultType(result.get('result_type', 'table'))
+
+            if result_type == ResultType.DICT:
+                # 字典结果，转换为单行DataFrame
+                return pd.DataFrame([data])
+            elif result_type == ResultType.SINGLE:
+                # 单条记录，转换为单行DataFrame
+                return pd.DataFrame([data])
+            elif result_type == ResultType.PAGE:
+                # 分页结果，转换为PageDataFrame并保留分页信息
+                items = data.get('items', [])
+                if not items:
+                    return pd.DataFrame()
+                pagination_info = result.get('pagination', {})
+                return PageDataFrame(items, pagination=pagination_info)
+            else:
+                # 默认表格结果
+                items = data.get('items', [])
+                if not items:
+                    return pd.DataFrame()
+                return pd.DataFrame(items)
+
+        except requests.exceptions.Timeout:
+            raise Exception(f"请求超时: {self.__timeout}秒")
+        except requests.exceptions.ConnectionError:
+            raise Exception(f"无法连接到服务器: {self.__base_url}")
+        except json.JSONDecodeError:
+            raise Exception("响应数据格式错误")
+        except Exception as e:
+            raise Exception(f"查询失败: {str(e)}")
+
+    def __getattr__(self, name: str):
+        """
+        魔术方法，动态创建API方法
+        例如：pro.hsgt_south_fund() 等价于 pro.query('hsgt_south_fund')
+        """
+        return partial(self.query, name)
+
+
+def init(token: str = '', base_url: str = '', local: bool = False, timeout: int = 30) -> DataApi:
+    """
+    初始化API客户端
+
+    Args:
+        token: API认证token，必传参数
+        base_url: API服务基础URL，非必填，为空时默认是https://data.alphaaidig.com，如果是local=true则使用本地url
+        local: 是否为本地环境，非必填，默认为False，为True时默认使用http://localhost:10000
+        timeout: 请求超时时间，非必填
+
+    Returns:
+        DataApi: API客户端实例
+    """
+    if not token:
+        raise ValueError('token不能为空')
+
+    return DataApi(token=token, base_url=base_url, local=local, timeout=timeout)

dc_client/client.pyi

@@ -0,0 +1,75 @@
+"""
+DataCenter Client 类型存根文件
+为IDE提供类型提示和代码补全支持
+"""
+from typing import Any, Dict, Optional, Union
+import pandas as pd
+
+class PageDataFrame(pd.DataFrame):
+    """带分页信息的DataFrame"""
+    _pagination: Dict[str, Any]
+
+    @property
+    def pagination(self) -> Dict[str, Any]: ...
+    @property
+    def has_pagination(self) -> bool: ...
+    @property
+    def current_page(self) -> int: ...
+    @property
+    def page_size(self) -> int: ...
+    @property
+    def total_count(self) -> int: ...
+    @property
+    def total_pages(self) -> int: ...
+
+class DatacenterAPIError(Exception):
+    """数据中心API异常类"""
+    code: int
+    message: str
+
+class DataApi:
+    """通用数据API客户端"""
+    __token: str
+    __base_url: str
+    __timeout: int
+    __dataapi_url: str
+
+    def __init__(self, token: str, base_url: str = '', local: bool = False, timeout: int = 30) -> None: ...
+
+    def query(self, api_name: str, fields: str = '', **kwargs) -> Union[pd.DataFrame, PageDataFrame]: ...
+
+    # HSGT 相关接口
+    def hsgt_fund_page_list(self, page: int = 1, page_size: int = 20, **kwargs) -> PageDataFrame: ...
+    def hsgt_north_fundxx(self, **kwargs) -> pd.DataFrame: ...
+    def hsgt_south_fundxx(self, **kwargs) -> pd.DataFrame: ...
+
+    # A股相关接口
+    def a_stock_page_list(self, page: int = 1, page_size: int = 20, **kwargs) -> PageDataFrame: ...
+    def a_stock_list(self, limit: int = 50, **kwargs) -> pd.DataFrame: ...
+
+    # 港股相关接口
+    def hk_stock_page_list(self, page: int = 1, page_size: int = 20, **kwargs) -> PageDataFrame: ...
+    def hk_stock_list(self, limit: int = 50, **kwargs) -> pd.DataFrame: ...
+
+    # 行业相关接口
+    def hs_industry_page_list(self, page: int = 1, page_size: int = 20, **kwargs) -> PageDataFrame: ...
+    def hs_industry_list(self, limit: int = 50, **kwargs) -> pd.DataFrame: ...
+    def hs_industry_company_page_list(self, page: int = 1, page_size: int = 20, **kwargs) -> PageDataFrame: ...
+    def hs_industry_company_list(self, limit: int = 50, **kwargs) -> pd.DataFrame: ...
+    def sw_industry_page_list(self, page: int = 1, page_size: int = 20, **kwargs) -> PageDataFrame: ...
+    def sw_industry_list(self, limit: int = 50, **kwargs) -> pd.DataFrame: ...
+    def sw_industry_company_page_list(self, page: int = 1, page_size: int = 20, level_type: str = 'level1', **kwargs) -> PageDataFrame: ...
+    def sw_industry_company_list(self, limit: int = 50, level_type: str = 'level1', **kwargs) -> pd.DataFrame: ...
+
+    # 融资融券相关接口
+    def margin_account_page_list(self, page: int = 1, page_size: int = 20, **kwargs) -> PageDataFrame: ...
+    def margin_account_list(self, limit: int = 50, **kwargs) -> pd.DataFrame: ...
+    def margin_analysis_page_list(self, page: int = 1, page_size: int = 20, **kwargs) -> PageDataFrame: ...
+    def margin_analysis_list(self, limit: int = 50, **kwargs) -> pd.DataFrame: ...
+    def margin_detail_page_list_by_date(self, page: int = 1, page_size: int = 20, **kwargs) -> PageDataFrame: ...
+    def margin_detail_page_list_by_stock(self, page: int = 1, page_size: int = 20, **kwargs) -> PageDataFrame: ...
+    def margin_detail_list_by_stock(self, stock_code: str, limit: int = 50, **kwargs) -> pd.DataFrame: ...
+
+def init(token: str = '', base_url: str = '', local: bool = False, timeout: int = 30) -> DataApi: ...
+
+__all__ = ["DataApi", "init", "PageDataFrame", "DatacenterAPIError"]

dc_client/exceptions.py

@@ -0,0 +1,26 @@
+"""
+Custom exceptions for the Datacenter API client.
+"""
+
+from typing import Optional
+
+class APIError(Exception):
+    """Base class for all API-related errors."""
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        self.status_code = status_code
+        super().__init__(f"API Error (Status: {status_code}): {message}")
+
+class AuthenticationError(APIError):
+    """Raised for authentication errors (401, 403)."""
+    def __init__(self, message: str = "Authentication failed"):
+        super().__init__(message, status_code=401)
+
+class NotFoundError(APIError):
+    """Raised when a resource is not found (404)."""
+    def __init__(self, message: str = "Resource not found"):
+        super().__init__(message, status_code=404)
+
+class InvalidRequestError(APIError):
+    """Raised for client-side errors (400)."""
+    def __init__(self, message: str):
+        super().__init__(message, status_code=400)

dc_client/run_tests.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+"""
+DataCenter Client 测试运行脚本
+Handler模式迁移后的简化版本
+"""
+
+import sys
+import os
+import pandas as pd
+
+# 添加当前目录到 Python 路径
+current_dir = os.path.dirname(os.path.abspath(__file__))
+parent_dir = os.path.dirname(current_dir)
+sys.path.insert(0, parent_dir)
+
+try:
+    import dc_client as dc
+    from dc_client import DataApi, PageDataFrame, DatacenterAPIError
+except ImportError as e:
+    print(f"❌ 导入错误: {e}")
+    print("请确保已正确安装依赖: uv sync")
+    sys.exit(1)
+
+
+def test_client_initialization():
+    """测试客户端初始化功能"""
+    print("\n" + "=" * 50)
+    print("🧪 测试 1: 客户端初始化功能")
+    print("=" * 50)
+
+    try:
+        # 测试使用 local=True 初始化
+        print("✅ 测试 local=True 初始化...")
+        client = dc.init(token='test_token', local=True)
+        assert client._DataApi__base_url == 'http://localhost:10000'
+        assert client._DataApi__token == 'test_token'
+        print("   ✓ local 参数工作正常")
+
+        # 测试使用显式 base_url 初始化
+        print("✅ 测试显式 base_url 初始化...")
+        client2 = dc.init(token='test_token', base_url='https://api.example.com')
+        assert client2._DataApi__base_url == 'https://api.example.com'
+        print("   ✓ base_url 参数工作正常")
+
+        # 测试默认值（非本地）
+        print("✅ 测试默认值初始化...")
+        client3 = dc.init(token='test_token')
+        assert client3._DataApi__base_url == 'https://data.alphaaidig.com'
+        print("   ✓ 默认生产环境URL工作正常")
+
+        # 测试空token错误
+        print("✅ 测试空token错误处理...")
+        try:
+            dc.init(token='')
+            assert False, "应该抛出ValueError"
+        except ValueError as e:
+            assert 'token不能为空' in str(e)
+            print("   ✓ 空token错误处理正常")
+
+        print("\n🎉 客户端初始化测试全部通过!")
+        return True
+
+    except Exception as e:
+        print(f"\n❌ 客户端初始化测试失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+def test_dynamic_method_creation():
+    """测试动态方法创建功能"""
+    print("\n" + "=" * 50)
+    print("🧪 测试 2: 动态方法创建功能")
+    print("=" * 50)
+
+    try:
+        # 创建客户端（使用模拟token）
+        client = dc.init(token='test_token', local=True, timeout=5)
+
+        # 测试动态方法是否可创建
+        print("✅ 测试动态方法创建...")
+        dynamic_method = getattr(client, 'hsgt_fund_page_list', None)
+        assert dynamic_method is not None, "动态方法应该被创建"
+        print("   ✓ hsgt_fund_page_list 方法创建成功")
+
+        # 测试其他动态方法
+        methods_to_test = [
+            'margin_account_page_list',
+            'a_stock_page_list',
+            'hk_stock_page_list',
+            'hs_industry_page_list'
+        ]
+
+        for method_name in methods_to_test:
+            method = getattr(client, method_name, None)
+            assert method is not None, f"{method_name} 方法应该被创建"
+        print(f"   ✓ {len(methods_to_test)} 个动态方法创建成功")
+
+        # 测试方法调用（会失败，但验证方法存在）
+        print("✅ 测试动态方法调用...")
+        try:
+            # 这个调用会因为服务未运行或token无效而失败，但验证了方法存在
+            client.hsgt_fund_page_list(page=1, page_size=1)
+        except Exception as e:
+            # 期望的异常，说明方法可以被调用
+            print(f"   ✓ 动态方法调用正常 (预期异常: {type(e).__name__})")
+
+        # 测试query方法
+        print("✅ 测试query方法...")
+        try:
+            client.query('test_handler', param1='value1')
+        except Exception as e:
+            # 期望的异常
+            print(f"   ✓ query方法调用正常 (预期异常: {type(e).__name__})")
+
+        print("\n🎉 动态方法创建测试全部通过!")
+        return True
+
+    except Exception as e:
+        print(f"\n❌ 动态方法创建测试失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+def test_real_api_call():
+    """测试真实API调用功能"""
+    print("\n" + "=" * 50)
+    print("🧪 测试 3: 真实API调用功能")
+    print("=" * 50)
+
+    try:
+        # 创建客户端（使用测试token）
+        client = dc.init(token='test_token', local=True, timeout=10)
+
+        # 测试一个简单的API调用
+        print("✅ 测试 HSGT 基金查询接口...")
+        try:
+            result = client.hsgt_fund_page_list(page=1, page_size=5)
+
+            # 验证返回结果
+            assert isinstance(result, pd.DataFrame), "返回结果应该是DataFrame"
+            print(f"   ✓ API调用成功，返回DataFrame类型")
+            print(f"   ✓ 返回数据行数: {len(result)}")
+
+            # 如果有数据，验证数据结构
+            if len(result) > 0:
+                print(f"   ✓ 数据列: {list(result.columns)}")
+                print(f"   ✓ 示例数据:\n{result.head(2).to_string()}")
+            else:
+                print("   ⚠️  返回空数据，这可能是因为数据库中没有数据")
+
+        except DatacenterAPIError as e:
+            if e.code == 401:
+                print(f"   ✓ API认证正常工作 (401未授权，测试token无效): {e.message}")
+            else:
+                print(f"   ⚠️  API返回其他错误: {e}")
+        except Exception as e:
+            # 检查是否是401认证错误（在异常消息中）
+            if "401" in str(e) or "HTTP请求失败，状态码: 401" in str(e):
+                print(f"   ✓ API认证正常工作 (401未授权，测试token无效)")
+            else:
+                print(f"   ❌ API调用失败: {e}")
+                return False
+
+        print("\n🎉 真实API调用测试完成!")
+        return True
+
+    except Exception as e:
+        print(f"\n❌ 真实API调用测试失败: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+
+def run_unit_tests():
+    """运行单元测试"""
+    print("\n🚀 开始运行 DataCenter Client 单元测试...")
+
+    tests = [
+        test_client_initialization,
+        test_dynamic_method_creation,
+        test_real_api_call
+    ]
+
+    passed = 0
+    total = len(tests)
+
+    for test in tests:
+        if test():
+            passed += 1
+
+    print("\n" + "=" * 50)
+    print("📊 测试结果汇总")
+    print("=" * 50)
+    print(f"✅ 通过: {passed}/{total}")
+    print(f"❌ 失败: {total - passed}/{total}")
+
+    if passed == total:
+        print("\n🎉 所有测试通过! DataCenter Client 工作正常!")
+    else:
+        print(f"\n⚠️  有 {total - passed} 个测试失败，请检查问题")
+
+    return passed == total
+
+
+def print_usage_info():
+    """打印使用说明"""
+    print("\n" + "=" * 70)
+    print("🎉 DataCenter Client 已完全迁移到 Handler 架构!")
+    print("=" * 70)
+    print("")
+    print("📦 架构变更:")
+    print("  ✅ 所有模块特定的 client 文件已被移除")
+    print("  ✅ 所有对应的 DTO 文件已被移除")
+    print("  ✅ 所有模块特定的测试文件已被移除")
+    print("  ✅ 现在使用统一的 Universal Client 模式")
+    print("")
+    print("🚀 推荐的使用方式:")
+    print("  1. 使用 Universal Client (datacenter_client.init_client)")
+    print("  2. 通过统一的 Handler 接口访问所有功能")
+    print("  3. 直接通过 HTTP 调用测试 API 接口")
+    print("")
+    print("💡 使用示例:")
+    print("  import dc_client as dc")
+    print("  # 本地开发")
+    print("  client = dc.init_client(token='your_token', local=True)")
+    print("  # 或指定显式URL")
+    print("  client = dc.init_client(token='your_token', base_url='http://localhost:10000')")
+    print("")
+    print("  # Margin Account")
+    print("  result = client.margin_account_page_list(page=1, page_size=10)")
+    print("  result = client.margin_account_list(limit=20)")
+    print("")
+    print("  # Margin Analysis")
+    print("  result = client.margin_analysis_page_list(page=1, page_size=10)")
+    print("  result = client.margin_analysis_list(limit=20)")
+    print("")
+    print("  # Margin Detail")
+    print("  result = client.margin_detail_page_list_by_date(page=1, page_size=10)")
+    print("  result = client.margin_detail_page_list_by_stock(page=1, page_size=10)")
+    print("  result = client.margin_detail_list_by_stock(stock_code='000001.SZ', limit=20)")
+    print("")
+    print("  # AStock")
+    print("  result = client.a_stock_page_list(page=1, page_size=10)")
+    print("  result = client.a_stock_list(limit=20)")
+    print("")
+    print("  # HKStock")
+    print("  result = client.hk_stock_page_list(page=1, page_size=10)")
+    print("  result = client.hk_stock_list(limit=20)")
+    print("")
+    print("  # Industry")
+    print("  result = client.hs_industry_page_list(page=1, page_size=10)")
+    print("  result = client.hs_industry_list(limit=20)")
+    print("  result = client.hs_industry_company_page_list(page=1, page_size=10)")
+    print("  result = client.hs_industry_company_list(limit=20)")
+    print("  result = client.sw_industry_page_list(page=1, page_size=10)")
+    print("  result = client.sw_industry_list(limit=20)")
+    print("  result = client.sw_industry_company_page_list(page=1, page_size=10, level_type='level1')")
+    print("  result = client.sw_industry_company_list(limit=20, level_type='level1')")
+    print("")
+    print("🔍 查看所有可用的 Handler 接口:")
+    print("  curl 'http://localhost:10000/api/v1/docs/json' | python3 -c \"import sys, json; data=json.load(sys.stdin); [print(f'- {api[\"name\"]}: {api[\"description\"]}') for api in data['apis']]\"")
+    print("")
+    print("🔍 搜索特定的接口:")
+    print("  curl 'http://localhost:10000/api/v1/docs/search?q=margin'")
+    print("")
+    print("📖 Handler 模式文档:")
+    print("  - 所有接口都通过 /api/v1/dataapi/{handler_name} 访问")
+    print("  - 支持 POST 请求，JSON 格式参数")
+    print("  - 统一的响应格式和错误处理")
+    print("")
+    print("=" * 70)
+
+
+def main():
+    """主函数"""
+    if len(sys.argv) > 1:
+        arg = sys.argv[1]
+        if arg in ['-h', '--help', 'help']:
+            print_usage_info()
+            return 0
+        else:
+            print(f"Unknown argument: {arg}")
+            print("Use -h or --help for usage information.")
+            return 1
+    else:
+        # 默认运行单元测试
+        success = run_unit_tests()
+        return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

dc_client/tests/base.py

@@ -0,0 +1,123 @@
+import unittest
+from typing import Dict, Any, List
+
+from dc_client.client import DatacenterClient
+
+
+class BaseClientTest(unittest.TestCase):
+    """基础测试类，提供通用的测试设置和方法"""
+    
+    BASE_URL = "http://127.0.0.1:10000"
+    TOKEN = "4e2e929a1ba14b06b8e8ca7e7e560efe"
+    
+    def setUp(self):
+        """设置测试环境"""
+        self.client = DatacenterClient(base_url=self.BASE_URL, token=self.TOKEN)
+    
+    def check_success_response(self, result: Dict[str, Any]) -> bool:
+        """检查响应是否成功"""
+        # 检查result是否为字典且包含status和data字段
+        return isinstance(result, dict) and result.get('status') == 'success' and 'data' in result
+    
+    def check_pagination_response(self, result: Any) -> bool:
+        """检查分页响应格式"""
+        # 检查是否有status和data字段，且data中有items和pagination
+        if isinstance(result, dict) and result.get('status') == 'success' and 'data' in result:
+            data = result['data']
+            return isinstance(data, dict) and 'items' in data and 'pagination' in data
+        # 兼容旧格式
+        return isinstance(result, dict) and 'items' in result and 'pagination' in result
+    
+    def print_pagination_info(self, result: Any):
+        """打印分页信息"""
+        # 检查是否是DTO对象
+        if hasattr(result, 'status') and hasattr(result, 'data'):
+            # DTO对象
+            print(f"返回记录数: {len(result.items)}")
+            if hasattr(result, 'pagination') and result.pagination:
+                print(f"分页信息: {result.pagination}")
+            if result.items:
+                print(f"第一条记录: {result.items[0]}")
+        elif isinstance(result, dict) and result.get('status') == 'success' and 'data' in result:
+            # 新的响应格式
+            data = result['data']
+            if isinstance(data, dict) and 'items' in data:
+                print(f"返回记录数: {len(data['items'])}")
+                if 'pagination' in data:
+                    print(f"分页信息: {data['pagination']}")
+                if data['items']:
+                    print(f"第一条记录: {data['items'][0]}")
+            else:
+                print("返回数据格式不符合预期")
+        elif isinstance(result, dict) and 'items' in result and 'pagination' in result:
+            # 旧格式
+            print(f"返回记录数: {len(result['items'])}")
+            print(f"分页信息: {result['pagination']}")
+            if result['items']:
+                print(f"第一条记录: {result['items'][0]}")
+        else:
+            print("返回数据格式不符合预期")
+    
+    def print_list_info(self, result: Any):
+        """打印列表信息"""
+        # 检查是否是DTO对象
+        if hasattr(result, 'status') and hasattr(result, 'data'):
+            # DTO对象
+            print(f"返回记录数: {len(result.items)}")
+            if hasattr(result, 'total'):
+                print(f"总记录数: {result.total}")
+            if result.items:
+                print(f"第一条记录: {result.items[0]}")
+        elif isinstance(result, dict) and result.get('status') == 'success' and 'data' in result:
+            # 新的响应格式
+            data = result['data']
+            if isinstance(data, dict) and 'items' in data:
+                print(f"返回记录数: {len(data['items'])}")
+                if 'total' in data:
+                    print(f"总记录数: {data['total']}")
+                if data['items']:
+                    print(f"第一条记录: {data['items'][0]}")
+            elif isinstance(data, list):
+                print(f"返回记录数: {len(data)}")
+                if data:
+                    print(f"第一条记录: {data[0]}")
+            else:
+                print("返回数据格式不符合预期")
+        elif isinstance(result, list):
+            # 纯列表格式
+            print(f"返回记录数: {len(result)}")
+            if result:
+                print(f"第一条记录: {result[0]}")
+        elif isinstance(result, dict):
+            # 如果是字典，可能是分页数据
+            if 'items' in result:
+                print(f"返回记录数: {len(result['items'])}")
+                if result['items']:
+                    print(f"第一条记录: {result['items'][0]}")
+            else:
+                print("返回数据格式不符合预期")
+        else:
+            print("返回数据格式不符合预期")
+    
+    def print_item_info(self, result: Any):
+        """打印单项信息"""
+        # 检查是否是DTO对象
+        if hasattr(result, 'status') and hasattr(result, 'data'):
+            # DTO对象
+            # 根据不同的DTO类型，访问不同的属性
+            if hasattr(result, 'industries'):
+                print(f"返回数据: {result.industries}")
+            elif hasattr(result, 'industry'):
+                print(f"返回数据: {result.industry}")
+            elif hasattr(result, 'summary'):
+                print(f"返回数据: {result.summary}")
+            else:
+                print(f"返回数据: {result.data}")
+        elif isinstance(result, dict) and result.get('status') == 'success' and 'data' in result:
+            # 新的响应格式
+            print(f"返回数据: {result['data']}")
+        elif isinstance(result, dict):
+            # 旧格式或其他格式
+            print(f"返回数据: {result}")
+        else:
+            print("请求失败")