alpha-dc-client 0.3.0__tar.gz → 0.3.2__tar.gz

alpha_dc_client-0.3.2/PKG-INFO

@@ -0,0 +1,486 @@
+Metadata-Version: 2.5
+Name: alpha-dc-client
+Version: 0.3.2
+Author-email: Hang GuangLiang <hanguangliang@alphaaidig.com>
+Requires-Python: >=3.10
+Requires-Dist: alpha-dc-common>=0.1.26
+Requires-Dist: requests
+Provides-Extra: parquet
+Requires-Dist: duckdb>=0.10; extra == 'parquet'
+Requires-Dist: pandas>=2.0; extra == 'parquet'
+Requires-Dist: paramiko>=3.0; extra == 'parquet'
+Requires-Dist: python-dotenv; extra == 'parquet'
+Description-Content-Type: text/markdown
+
+# DataCenter Client 使用指南
+
+> 因子 Parquet 数据（本地镜像同步与读取）见 [DATA.md](DATA.md)。
+
+## 1. 🚀 安装
+
+```bash
+pip install alpha-dc-client
+```
+
+## 1.5 🖥 命令行工具（CLI）
+
+安装后自带 `dcx` 命令（等价 `python -m dc_client.cli`），两条数据出口通道各一个命令面：
+
+```bash
+# ── 认证（推荐一次性 login；环境变量优先级更高，CI/临时切换用）──
+dcx login                              # 交互输入 Key（不回显），写 ~/.dc_data/auth.json
+# export DC_API_KEY=<你的 API Key>     # 环境变量方式（优先于 auth.json）
+# export DC_API_URL=https://data.alphaaiming.com   # 可选；本机调试用 --local
+dcx whoami                             # 查看当前认证来源与目标（Key 打码）
+
+# ── HTTP 通道：小表/维表/公告/快讯等（dc_api）──
+dcx api list                          # 列出全部接口（服务端新 handler 自动出现）
+dcx api list -k margin                # 按关键字过滤
+dcx api docs margin_analysis_list     # 看单接口的参数与返回字段
+dcx api query margin_analysis_list limit=50                     # 通用查询（tushare query 风格）
+dcx api query hsgt_fund_page_list stock_code=00700.HK --all    # 自动翻页拉全
+dcx api query margin_detail_page_list_by_stock stock_code=000001.SZ limit=100 \
+    -o detail.csv                                                # 导出文件（csv/json/parquet 按扩展名推断）
+
+# ── Parquet 通道：日线/因子宽表批量读（本地 duckdb，零网络）──
+dcx data sync --market cn             # 增量同步（首次 --full）
+dcx data datasets                     # 看有哪些语义入口
+dcx data load cn.stock_daily --start 2026-09-01 -o daily.parquet
+dcx data load cn.market --columns trade_date,mkt_above_ma20_ratio  # 跨层视图（columns 必填）
+dcx data status                       # 新鲜度面板
+```
+
+分工纪律：**小查询用 `dcx api`；批量大数据量（全市场日线/因子）一定走 `dcx data`**——
+HTTP 接口有分页/limit 上限，拉宽表又慢又挤服务端；本地 Parquet 读是并行 duckdb，秒级出全量。
+
+
+## 2. 🔑 认证设置
+
+### 获取API Token
+1. 联系管理员申请API Token
+2. 或者访问数据管理后台获取访问权限
+
+### 初始化客户端
+```python
+import datacenter_client as dcx
+
+# 基础初始化
+client = dcx.init(
+    token='your_api_token_here'
+)
+
+# 使用环境变量
+import os
+client = dcx.init(token=os.getenv('DATACENTER_API_TOKEN'))
+```
+
+## 3. 🔍 查找需要的接口
+
+### 方法一：查看完整API列表
+```python
+import requests
+
+# 获取所有API
+response = requests.get('http://data.alphaaidig.com/api/v1/docs/json')
+if response.status_code == 200:
+    docs = response.json()
+    print(f"总共有 {docs['total_count']} 个API")
+    for api in docs['apis']:
+        print(f"- {api['name']}: {api['description']}")
+```
+
+### 方法二：搜索特定功能
+```python
+# 搜索融资融券相关接口
+response = requests.get('http://data.alphaaidig.com/api/v1/docs/search?q=margin')
+if response.status_code == 200:
+    results = response.json()
+    for api in results['results']:
+        print(f"- {api['name']}: {api['description']}")
+```
+
+### 方法三：按类别查看
+```python
+# 获取API分类
+response = requests.get('http://data.alphaaidig.com/api/v1/docs/categories')
+if response.status_code == 200:
+    categories = response.json()
+    print(f"API分类: {categories['categories']}")
+```
+
+## 4. 📋 访问接口
+
+### 基本调用方式
+```python
+# 方式一：通过动态方法调用
+result = client.hsgt_fund_page_list(page=1, page_size=20)
+
+# 方式二：通过通用query方法
+result = client.query('hsgt_fund_page_list', page=1, page_size=20)
+
+# 方式三：指定返回字段
+result = client.hsgt_fund_page_list(
+    page=1,
+    page_size=10,
+    fields='trade_date,stock_code,stock_name,hold_market_cap'
+)
+```
+
+### 常用接口示例
+```python
+# 沪深港通数据
+df = client.hsgt_fund_page_list(page=1, page_size=20)
+df = client.hsgt_north_fundxx()
+df = client.hsgt_south_fundxx()
+
+# A股数据
+df = client.a_stock_page_list(page=1, page_size=20)
+df = client.a_stock_list(limit=50)
+
+# 港股数据
+df = client.hk_stock_page_list(page=1, page_size=20)
+df = client.hk_stock_list(limit=50)
+
+# 行业数据
+df = client.hs_industry_page_list(page=1, page_size=20)
+df = client.hs_industry_company_page_list(page=1, page_size=20)
+df = client.sw_industry_page_list(page=1, page_size=20)
+df = client.sw_industry_company_page_list(page=1, page_size=20, level1_industry_code='801010.SI')  # 指数码；数字码如 '110000' 亦可
+
+# 融资融券数据
+df = client.margin_account_page_list(page=1, page_size=20)
+df = client.margin_account_list(limit=50)
+df = client.margin_analysis_page_list(page=1, page_size=20)
+df = client.margin_analysis_list(limit=50)
+df = client.margin_detail_page_list_by_date(page=1, page_size=20)
+df = client.margin_detail_page_list_by_stock(page=1, page_size=20)
+df = client.margin_detail_list_by_stock(stock_code='000001.SZ', limit=50)
+```
+
+## 5. ❌ 错误处理
+
+```python
+import datacenter_client as dcx
+from datacenter_client.exceptions import (
+    DatacenterAPIError,
+    APIError,
+    AuthenticationError,
+    NotFoundError,
+    InvalidRequestError
+)
+
+def safe_api_call():
+    try:
+        client = dcx.init(token='your_api_token')
+        df = client.hsgt_fund_page_list(page=1, page_size=10)
+        return df
+
+    except AuthenticationError:
+        print("❌ 认证失败：请检查API token是否正确")
+        return None
+
+    except NotFoundError:
+        print("❌ API不存在：请检查API名称是否正确")
+        return None
+
+    except InvalidRequestError as e:
+        print(f"❌ 请求参数错误：{e}")
+        return None
+
+    except DatacenterAPIError as e:
+        print(f"❌ API错误：{e.message}")
+        return None
+
+    except Exception as e:
+        print(f"❌ 未知错误：{e}")
+        return None
+
+# 使用
+result = safe_api_call()
+if result is not None:
+    print(f"✅ 成功获取 {len(result)} 条数据")
+```
+
+## 6. 📊 分页数据解析
+
+### 识别分页数据
+```python
+import datacenter_client as dcx
+
+client = dcx.init(token='your_api_token')
+
+# 调用分页接口
+result = client.hsgt_fund_page_list(page=1, page_size=20)
+
+# 检查是否为分页数据
+if hasattr(result, 'has_pagination') and result.has_pagination:
+    print("✅ 这是分页数据")
+    print(f"当前页: {result.current_page}")
+    print(f"每页大小: {result.page_size}")
+    print(f"总记录数: {result.total_count}")
+    print(f"总页数: {result.total_pages}")
+else:
+    print("✅ 这是普通数据")
+    print(f"数据行数: {len(result)}")
+```
+
+### 遍历所有分页数据
+```python
+def get_all_paginated_data(client, api_method, **kwargs):
+    """获取所有分页数据的通用函数"""
+    all_data = []
+    page = 1
+    page_size = 100  # 每页大小
+
+    while True:
+        try:
+            # 调用分页接口
+            result = api_method(page=page, page_size=page_size, **kwargs)
+
+            if hasattr(result, 'has_pagination') and result.has_pagination:
+                # 分页数据处理
+                all_data.extend(result.to_dict('records'))
+                print(f"✅ 第 {page} 页，累计 {len(all_data)} 条数据")
+
+                # 检查是否还有下一页
+                if page >= result.total_pages:
+                    break
+                page += 1
+            else:
+                # 非分页数据
+                all_data.extend(result.to_dict('records'))
+                break
+
+        except Exception as e:
+            print(f"❌ 获取第 {page} 页数据失败：{e}")
+            break
+
+    return all_data
+
+# 使用示例
+client = dcx.init(token='your_api_token')
+all_hsgt_data = get_all_paginated_data(
+    client,
+    client.hsgt_fund_page_list
+)
+print(f"总共获取 {len(all_hsgt_data)} 条数据")
+```
+
+## 7. 📄 非分页数据解析
+
+### 处理普通数据
+```python
+import pandas as pd
+import datacenter_client as dcx
+
+client = dcx.init(token='your_api_token')
+
+# 调用非分页接口
+result = client.hsgt_north_fundxx()
+
+# 检查数据类型
+if isinstance(result, pd.DataFrame):
+    print(f"✅ 获取到DataFrame，共 {len(result)} 行")
+    print(f"列名: {list(result.columns)}")
+    print("前5行数据:")
+    print(result.head())
+else:
+    print("✅ 获取到其他格式数据")
+    print(f"数据类型: {type(result)}")
+    print(f"数据内容: {result}")
+```
+
+### 指定返回字段
+```python
+# 只获取需要的字段
+result = client.hsgt_fund_page_list(
+    page=1,
+    page_size=10,
+    fields='trade_date,stock_code,stock_name,hold_market_cap'
+)
+
+print("返回的字段:", result.columns.tolist())
+print("数据示例:")
+print(result.head())
+```
+
+## 8. 🛠️ 高级用法
+
+### 配置化客户端
+```python
+import os
+from pathlib import Path
+import json
+
+class DataCenterConfig:
+    def __init__(self):
+        self.api_token = os.getenv('DATACENTER_API_TOKEN')
+        self.base_url = os.getenv('DATACENTER_BASE_URL', 'https://data.alphaaidig.com')
+        self.timeout = int(os.getenv('DATACENTER_TIMEOUT', '30'))
+
+        # 从配置文件读取
+        config_file = Path.home() / '.datacenter' / 'config.json'
+        if config_file.exists():
+            with open(config_file, 'r') as f:
+                config = json.load(f)
+                self.api_token = config.get('api_token', self.api_token)
+                self.base_url = config.get('base_url', self.base_url)
+                self.timeout = config.get('timeout', self.timeout)
+
+    def get_client(self):
+        if not self.api_token:
+            raise ValueError("❌ API Token未设置，请设置DATACENTER_API_TOKEN环境变量或配置文件")
+
+        return dcx.init(
+            token=self.api_token,
+            base_url=self.base_url,
+            timeout=self.timeout
+        )
+
+# 使用
+config = DataCenterConfig()
+client = config.get_client()
+```
+
+### 批量查询
+```python
+import pandas as pd
+from typing import List
+import time
+
+def batch_query_stocks(stock_codes: List[str]) -> pd.DataFrame:
+    """批量查询多只股票数据"""
+    client = dcx.init(token='your_api_token')
+    all_data = []
+
+    for i, stock_code in enumerate(stock_codes):
+        try:
+            print(f"📊 查询股票 {stock_code} ({i+1}/{len(stock_codes)})")
+
+            # 这里可以根据需要调用不同的接口
+            result = client.a_stock_list(limit=1)  # 示例调用
+
+            # 添加股票代码到结果中（如果接口没有返回）
+            if hasattr(result, 'to_dict'):
+                data_dict = result.to_dict()
+                if isinstance(data_dict, list):
+                    all_data.extend(data_dict)
+                else:
+                    all_data.append(data_dict)
+
+            # 添加延迟避免频率限制
+            time.sleep(0.1)
+
+        except Exception as e:
+            print(f"❌ 查询股票 {stock_code} 失败：{e}")
+            continue
+
+    if all_data:
+        return pd.DataFrame(all_data)
+    else:
+        return pd.DataFrame()
+
+# 使用示例
+stock_codes = ['000001', '000002', '600000', '600036']
+df = batch_query_stocks(stock_codes)
+print(f"总共获取 {len(df)} 条股票数据")
+```
+
+### 动态接口调用
+```python
+def dynamic_api_call(client, api_name: str, **params):
+    """动态调用任意API接口"""
+    try:
+        # 方法一：通过动态属性调用
+        api_method = getattr(client, api_name)
+        result = api_method(**params)
+
+        # 方法二：通过query方法调用
+        # result = client.query(api_name, **params)
+
+        return result
+
+    except AttributeError:
+        print(f"❌ 接口 {api_name} 不存在")
+        return None
+    except Exception as e:
+        print(f"❌ 调用接口 {api_name} 失败：{e}")
+        return None
+
+# 使用示例
+client = dcx.init(token='your_api_token')
+result = dynamic_api_call(client, 'hsgt_fund_page_list', page=1, page_size=10)
+if result is not None:
+    print(f"成功获取 {len(result)} 条数据")
+```
+
+## 9. ❓ 常见问题
+
+### Q1: 如何获取API Token？
+**A**: 请联系系统管理员或访问数据管理后台申请API访问权限。
+
+### Q2: 支持哪些股票代码格式？
+**A**:
+- A股：基础格式6位数字或带后缀格式，如 "000001", "600000"，"000001.SZ", "600000.SH"
+- 港股：基础格式5位数字，如 "00700", "00941", "00700.HK"
+- 指数：通常包含后缀，如 "000300.SH", "000905.SZ"
+
+### Q3: 如何知道某个接口是否存在？
+**A**:
+```python
+# 搜索接口
+import requests
+response = requests.get('http://data.alphaaidig.com/api/v1/docs/search?q=接口名')
+if response.status_code == 200:
+    results = response.json()
+    print(f"找到 {results['total_count']} 个相关接口")
+```
+
+### Q4: 如何处理大量数据？
+**A**:
+1. 每次请求适量数据
+2. 正确处理分页信息，避免遗漏数据
+3. 添加适当的延迟避免频率限制
+4. 使用批量处理提高效率
+
+### Q5: API调用失败怎么办？
+**A**:
+1. 检查网络连接和base_url是否正确
+2. 验证API token是否有效
+3. 确认接口名称和参数是否正确
+4. 查看错误信息进行针对性处理
+5. 使用错误处理机制捕获异常
+
+### Q6: 返回的数据格式是什么？
+**A**:
+- **分页数据**: PageDataFrame，包含分页信息和数据
+- **普通数据**: pandas DataFrame
+- **单条记录**: pandas DataFrame（单行）
+- **其他**: 根据具体接口可能返回不同格式
+
+### Q7: 如何获取完整的接口文档？
+**A**:
+```python
+import requests
+
+# 获取完整文档
+response = requests.get('http://data.alphaaidig.com/api/v1/docs/json')
+if response.status_code == 200:
+    docs = response.json()
+    print(f"总共有 {docs['total_count']} 个接口")
+    for api in docs['apis']:
+        print(f"- {api['name']}: {api['description']}")
+```
+
+### Q8: IDE无法识别动态方法怎么办？
+**A**: 现代IDE（如PyCharm、VSCode）会通过运行时学习动态方法，使用几次后就能识别。也可以：
+1. 使用 `client.query('方法名')` 的方式调用
+2. 添加类型提示注释
+3. 确保导入正确的异常类
+
+## 📞 技术支持
+
+如果遇到问题，可以：
+1. 查看API错误信息进行调试
+2. 访问 http://data.alphaaidig.com/api/v1/docs 查看完整API文档
+3. 联系技术支持团队

{alpha_dc_client-0.3.0 → alpha_dc_client-0.3.2}/pyproject.toml

@@ -4,10 +4,13 @@ build-backend = "hatchling.build"
 
 [project]
 name = "alpha-dc-client"
-version = "0.3.0"  # 0.3.0 起：dcx 命令行（api/data 双通道）；common 锁定放宽为 >=
+version = "0.3.2"  # 0.3.2：requires-python 放宽 >=3.10（3.11 收紧导致 uvx 默认解释器解析失败）；0.3.0 起：dcx 命令行
 authors = [
     {name = "Hang GuangLiang", email = "hanguangliang@alphaaidig.com"},
 ]
+# 3.11 = 开发/测试环境（workspace python 3.11；3.10 未验证）
+requires-python = ">=3.10"
+readme = "USAGE.md"
 dependencies = [
     # client.py 直接使用 requests（POST + Timeout/ConnectionError 异常处理），
     # workspace 内曾靠 tushare 等传递带入未暴露，独立安装必炸，必须显式声明

alpha_dc_client-0.3.0/PKG-INFO

@@ -1,11 +0,0 @@
-Metadata-Version: 2.5
-Name: alpha-dc-client
-Version: 0.3.0
-Author-email: Hang GuangLiang <hanguangliang@alphaaidig.com>
-Requires-Dist: alpha-dc-common>=0.1.26
-Requires-Dist: requests
-Provides-Extra: parquet
-Requires-Dist: duckdb>=0.10; extra == 'parquet'
-Requires-Dist: pandas>=2.0; extra == 'parquet'
-Requires-Dist: paramiko>=3.0; extra == 'parquet'
-Requires-Dist: python-dotenv; extra == 'parquet'

alpha_dc_client-0.3.0/build-env-p4x8ot24/Lib/site-packages/pip/__init__.py

@@ -1,13 +0,0 @@
-from typing import List, Optional
-
-__version__ = "24.0"
-
-
-def main(args: Optional[List[str]] = None) -> int:
-    """This is an internal API only meant for use by pip's own console scripts.
-
-    For additional details, see https://github.com/pypa/pip/issues/7498.
-    """
-    from pip._internal.utils.entrypoints import _wrapper
-
-    return _wrapper(args)

alpha_dc_client-0.3.0/build-env-p4x8ot24/Lib/site-packages/pip/__main__.py

@@ -1,24 +0,0 @@
-import os
-import sys
-
-# Remove '' and current working directory from the first entry
-# of sys.path, if present to avoid using current directory
-# in pip commands check, freeze, install, list and show,
-# when invoked as python -m pip <command>
-if sys.path[0] in ("", os.getcwd()):
-    sys.path.pop(0)
-
-# If we are running from a wheel, add the wheel to sys.path
-# This allows the usage python pip-*.whl/pip install pip-*.whl
-if __package__ == "":
-    # __file__ is pip-*.whl/pip/__main__.py
-    # first dirname call strips of '/__main__.py', second strips off '/pip'
-    # Resulting path is the name of the wheel itself
-    # Add that to sys.path so we can import pip
-    path = os.path.dirname(os.path.dirname(__file__))
-    sys.path.insert(0, path)
-
-if __name__ == "__main__":
-    from pip._internal.cli.main import main as _main
-
-    sys.exit(_main())

alpha_dc_client-0.3.0/build-env-p4x8ot24/Lib/site-packages/pip/__pip-runner__.py

@@ -1,50 +0,0 @@
-"""Execute exactly this copy of pip, within a different environment.
-
-This file is named as it is, to ensure that this module can't be imported via
-an import statement.
-"""
-
-# /!\ This version compatibility check section must be Python 2 compatible. /!\
-
-import sys
-
-# Copied from setup.py
-PYTHON_REQUIRES = (3, 7)
-
-
-def version_str(version):  # type: ignore
-    return ".".join(str(v) for v in version)
-
-
-if sys.version_info[:2] < PYTHON_REQUIRES:
-    raise SystemExit(
-        "This version of pip does not support python {} (requires >={}).".format(
-            version_str(sys.version_info[:2]), version_str(PYTHON_REQUIRES)
-        )
-    )
-
-# From here on, we can use Python 3 features, but the syntax must remain
-# Python 2 compatible.
-
-import runpy  # noqa: E402
-from importlib.machinery import PathFinder  # noqa: E402
-from os.path import dirname  # noqa: E402
-
-PIP_SOURCES_ROOT = dirname(dirname(__file__))
-
-
-class PipImportRedirectingFinder:
-    @classmethod
-    def find_spec(self, fullname, path=None, target=None):  # type: ignore
-        if fullname != "pip":
-            return None
-
-        spec = PathFinder.find_spec(fullname, [PIP_SOURCES_ROOT], target)
-        assert spec, (PIP_SOURCES_ROOT, fullname)
-        return spec
-
-
-sys.meta_path.insert(0, PipImportRedirectingFinder())
-
-assert __name__ == "__main__", "Cannot run __pip-runner__.py as a non-main module"
-runpy.run_module("pip", run_name="__main__", alter_sys=True)

alpha_dc_client-0.3.0/build-env-p4x8ot24/Lib/site-packages/pip/_internal/__init__.py

@@ -1,18 +0,0 @@
-from typing import List, Optional
-
-from pip._internal.utils import _log
-
-# init_logging() must be called before any call to logging.getLogger()
-# which happens at import of most modules.
-_log.init_logging()
-
-
-def main(args: (Optional[List[str]]) = None) -> int:
-    """This is preserved for old console scripts that may still be referencing
-    it.
-
-    For additional details, see https://github.com/pypa/pip/issues/7498.
-    """
-    from pip._internal.utils.entrypoints import _wrapper
-
-    return _wrapper(args)