ardata-sdk 1.0.0__tar.gz

ardata_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.4
+Name: ardata-sdk
+Version: 1.0.0
+Summary: ARData Python SDK - A-share market data client
+Author-email: ARQuant <otreewen2020@users.noreply.github.com>
+License-Expression: MIT
+Keywords: a-share,stock,quant,china-market
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: pandas>=1.5
+Dynamic: requires-python
+
+# ARData SDK
+
+Python SDK for ARQuant market data platform.
+
+## Install
+
+```bash
+pip install ardata-sdk
+```
+
+## Quick Start
+
+```python
+import ardata_sdk as ardata
+
+# Initialize with your API key and server URL
+ardata.init(token="your-api-key", base_url="https://ardata.example.com")
+
+# Get daily price data
+df = ardata.get_price(["000001.XSHE", "600519.XSHG"],
+                       start_date="2024-01-01",
+                       end_date="2024-12-31",
+                       frequency="daily",
+                       fields=["open", "close", "high", "low", "volume"],
+                       fq="pre")
+
+# Get all A-share securities
+securities = ardata.get_all_securities()
+
+# Get trade days
+trade_days = ardata.get_trade_days(start_date="2024-01-01", end_date="2024-12-31")
+
+# Get industry info
+industries = ardata.get_industry(["000001.XSHE"])
+```
+
+## API Reference
+
+| Function | Description |
+|----------|-------------|
+| `get_price()` | Historical OHLCV data |
+| `get_all_securities()` | List all securities |
+| `get_security_info()` | Security details |
+| `get_trade_days()` | Trading calendar |
+| `get_industry()` | Industry classification |
+| `get_index_stocks()` | Index constituents |
+| `get_fundamentals()` | Financial data (valuation, balance sheet, etc.) |
+| `get_money_flow()` | Capital flow data |
+| `get_billboard_list()` | Dragon-tiger board data |
+| `get_factor_values()` | Alpha factors |
+| `history()` / `attribute_history()` | JQData-compatible history APIs |
+| `get_ticks()` | Tick-level data |
+| `finance.run_query()` | Financial table query DSL |

ardata_sdk-1.0.0/README.md

@@ -0,0 +1,53 @@
+# ARData SDK
+
+Python SDK for ARQuant market data platform.
+
+## Install
+
+```bash
+pip install ardata-sdk
+```
+
+## Quick Start
+
+```python
+import ardata_sdk as ardata
+
+# Initialize with your API key and server URL
+ardata.init(token="your-api-key", base_url="https://ardata.example.com")
+
+# Get daily price data
+df = ardata.get_price(["000001.XSHE", "600519.XSHG"],
+                       start_date="2024-01-01",
+                       end_date="2024-12-31",
+                       frequency="daily",
+                       fields=["open", "close", "high", "low", "volume"],
+                       fq="pre")
+
+# Get all A-share securities
+securities = ardata.get_all_securities()
+
+# Get trade days
+trade_days = ardata.get_trade_days(start_date="2024-01-01", end_date="2024-12-31")
+
+# Get industry info
+industries = ardata.get_industry(["000001.XSHE"])
+```
+
+## API Reference
+
+| Function | Description |
+|----------|-------------|
+| `get_price()` | Historical OHLCV data |
+| `get_all_securities()` | List all securities |
+| `get_security_info()` | Security details |
+| `get_trade_days()` | Trading calendar |
+| `get_industry()` | Industry classification |
+| `get_index_stocks()` | Index constituents |
+| `get_fundamentals()` | Financial data (valuation, balance sheet, etc.) |
+| `get_money_flow()` | Capital flow data |
+| `get_billboard_list()` | Dragon-tiger board data |
+| `get_factor_values()` | Alpha factors |
+| `history()` / `attribute_history()` | JQData-compatible history APIs |
+| `get_ticks()` | Tick-level data |
+| `finance.run_query()` | Financial table query DSL |

ardata_sdk-1.0.0/ardata_sdk/__init__.py

@@ -0,0 +1,28 @@
+from .config import init, get_client
+from .api.price import get_price, get_bars
+from .api.securities import get_security_info, get_all_securities
+from .api.index_concept import get_index_stocks, get_industry_stocks, get_concept_stocks, get_index_weights
+from .api.industry import get_industry, get_industries, get_concepts
+from .api.fundamentals import get_valuation, get_fundamentals, get_fundamentals_continuously, get_history_fundamentals
+from .api.money_flow import get_money_flow
+from .api.mtss import get_mtss
+from .api.billboard import get_billboard_list
+from .api.margin import get_margincash_stocks, get_marginsec_stocks
+from .api.extras import get_extras
+from .api.history import history, attribute_history
+from .api.trade_days import get_trade_days
+from .api.factors import get_all_factors, get_factor_values
+from .api.ticks import get_ticks, get_call_auction
+from . import finance
+from .finance import query
+
+__all__ = [
+    'init', 'get_price', 'get_bars', 'get_security_info', 'get_all_securities',
+    'get_index_stocks', 'get_industry_stocks', 'get_concept_stocks',
+    'get_industry', 'get_industries', 'get_concepts', 'get_index_weights', 'get_valuation', 'get_fundamentals', 'get_fundamentals_continuously', 'get_history_fundamentals',
+    'get_money_flow', 'get_mtss', 'get_billboard_list',
+    'get_margincash_stocks', 'get_marginsec_stocks', 'get_extras',
+    'history', 'attribute_history',
+    'get_trade_days', 'get_all_factors', 'get_factor_values', 'get_ticks', 'get_call_auction',
+    'finance', 'query',
+]

ardata_sdk-1.0.0/ardata_sdk/api/__init__.py

@@ -0,0 +1,15 @@
+from .price import get_price, get_bars
+from .securities import get_security_info, get_all_securities
+from .index_concept import get_index_stocks, get_industry_stocks, get_concept_stocks, get_index_weights
+from .industry import get_industry, get_industries, get_concepts
+from .fundamentals import get_valuation, get_fundamentals, get_fundamentals_continuously, get_history_fundamentals
+from .money_flow import get_money_flow
+from .mtss import get_mtss
+from .billboard import get_billboard_list
+from .margin import get_margincash_stocks, get_marginsec_stocks
+from .extras import get_extras
+from .trade_days import get_trade_days
+from .factors import get_all_factors, get_factor_values
+from .ticks import get_ticks, get_call_auction
+from .history import history, attribute_history
+from ..finance.run_query import run_query

ardata_sdk-1.0.0/ardata_sdk/api/billboard.py

@@ -0,0 +1,16 @@
+from ..config import get_client
+
+
+def get_billboard_list(stock_list=None, start_date=None, end_date=None, count=None):
+    client = get_client()
+    params = {}
+    if stock_list:
+        params['stock_list'] = ','.join(stock_list) if isinstance(stock_list, list) else stock_list
+    if start_date:
+        params['start_date'] = start_date
+    if end_date:
+        params['end_date'] = end_date
+    if count:
+        params['count'] = count
+    data = client.get('/get_billboard_list', params=params)
+    return client.to_dataframe(data)

ardata_sdk-1.0.0/ardata_sdk/api/client.py

@@ -0,0 +1,195 @@
+"""ARData Proxy HTTP Client"""
+
+import os
+import requests
+import pandas as pd
+from datetime import datetime, date
+from typing import Optional, List, Union
+
+
+class APIClient:
+    """ARData Proxy HTTP Client (计划中名为 ARDataClient)"""
+    def __init__(self, host: str = "http://localhost:8000", token: str = ""):
+        self.host = host.rstrip("/")
+        self.token = token
+        self.session = requests.Session()
+        self.session.headers.update({"Authorization": f"Bearer {token}"})
+
+    def _prefix(self, path: str) -> str:
+        """server 路由都挂在 /api/v1 下, client 自动补前缀 (已有则不重复)."""
+        if not path.startswith("/api/v1"):
+            return "/api/v1" + path
+        return path
+
+    def _get(self, path: str, params: dict = None) -> dict:
+        resp = self.session.get(f"{self.host}{self._prefix(path)}", params=params, timeout=120)
+        resp.raise_for_status()
+        return resp.json()
+
+    def get(self, path: str, params: dict = None) -> dict:
+        return self._get(path, params)
+
+    def to_dataframe(self, data):
+        import pandas as pd
+        if not data:
+            return pd.DataFrame()
+        return pd.DataFrame(data)
+
+    def _post(self, path: str, json: dict) -> dict:
+        resp = self.session.post(f"{self.host}{self._prefix(path)}", json=json, timeout=30)
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_token(self, api_key: str, expire_days: int = 30) -> dict:
+        """用 api_key 登录拿 JWT (server /auth/login 端点)."""
+        return self._post("/api/v1/auth/login", {
+            "api_key": api_key, "expire_days": expire_days,
+        })
+
+    def get_price(self, security, start_date=None, end_date=None, frequency="daily",
+                  fields=None, skip_paused=False, fq="pre", count=None, panel=True):
+        codes = ",".join(security) if isinstance(security, list) else security
+        params = {"security": codes, "frequency": frequency, "fq": fq if fq is not None else '', "skip_paused": str(skip_paused).lower()}
+        if start_date:
+            params["start_date"] = str(start_date)
+        if end_date:
+            params["end_date"] = str(end_date)
+        if fields:
+            params["fields"] = ",".join(fields) if isinstance(fields, list) else fields
+
+        data = self._get("/get_price", params)
+        if not data:
+            return pd.DataFrame()
+
+        df = pd.DataFrame(data)
+        if "code" in df.columns:
+            df.set_index(["code", "time" if frequency == "1m" else "date"], inplace=True)
+
+        if fields:
+            df = df[[c for c in fields if c in df.columns]]
+        return df
+
+    def get_trade_days(self, start_date=None, end_date=None):
+        params = {}
+        if start_date:
+            params["start_date"] = str(start_date)
+        if end_date:
+            params["end_date"] = str(end_date)
+        return self._get("/get_trade_days", params)
+
+    def get_all_securities(self, types=None, date=None):
+        params = {}
+        if types:
+            params["types"] = ",".join(types) if isinstance(types, list) else types
+        if date:
+            params["date"] = str(date)
+        data = self._get("/get_all_securities", params)
+        df = pd.DataFrame(data)
+        if "code" in df.columns:
+            df.set_index("code", inplace=True)
+        return df
+
+    def get_security_info(self, code, date=None):
+        data = self._get("/get_security_info", {"code": code})
+        return data
+
+    def get_industry(self, security, date=None):
+        codes = ",".join(security) if isinstance(security, list) else security
+        params = {"security": codes}
+        if date:
+            params["date"] = str(date)
+        return self._get("/get_industry", params)
+
+    def get_concept(self):
+        return self._get("/get_concepts")
+
+    def get_index_constituents(self, index_code, date=None):
+        params = {"index_code": index_code}
+        if date:
+            params["date"] = str(date)
+        return self._get("/get_index_stocks", params)
+
+    def get_industry_constituents(self, industry_code, date=None):
+        params = {"industry_code": industry_code}
+        if date:
+            params["date"] = str(date)
+        return self._get("/get_industry_stocks", params)
+
+    def get_index_weights(self, index_code, date=None):
+        params = {"index_code": index_code}
+        if date:
+            params["date"] = str(date)
+        return self._get("/get_index_weights", params)
+
+    def get_margin_stocks(self, date=None):
+        params = {"date": str(date)} if date else {}
+        return self._get("/get_margincash_stocks", params)
+
+    def get_ST_stocks(self):
+        return self._get("/get_extras", {"info": "is_st", "security_list": "*", "df": "false"})
+
+    def get_billboard_list(self, stock_list=None, start_date=None, end_date=None, count=None):
+        params = {}
+        if stock_list:
+            params["stock_list"] = ",".join(stock_list) if isinstance(stock_list, list) else stock_list
+        if start_date:
+            params["start_date"] = str(start_date)
+        if end_date:
+            params["end_date"] = str(end_date)
+        if count is not None:
+            params["count"] = count
+        return self._get("/get_billboard_list", params)
+
+    def get_fundamentals(self, query_object, date=None, statDate=None):
+        from ardata_sdk.finance.query import Query
+        if not isinstance(query_object, Query):
+            q = Query(query_object)
+        else:
+            q = query_object
+        if date is not None:
+            q._filters.append({'col': 'day' if q._table == 'valuation' else 'pubDate', 'op': 'lte', 'val': str(date)})
+        if statDate is not None:
+            s = str(statDate)
+            if 'q' in s:
+                year, qtr = s.split('q', 1)
+                quarter_end = {'1': '03-31', '2': '06-30', '3': '09-30', '4': '12-31'}.get(qtr)
+                if quarter_end:
+                    q._filters.append({'col': 'statDate', 'op': 'eq', 'val': f'{year}-{quarter_end}'})
+            else:
+                q._filters.append({'col': 'statDate', 'op': 'lte', 'val': f'{s}-12-31'})
+        return self._query_finance(q._table, self._q_to_params(q))
+
+    def _q_to_params(self, q):
+        params = {}
+        for f in q._filters:
+            key = f['col'] if f['op'] == 'eq' else f"{f['col']}__{f['op']}"
+            params[key] = f['val']
+        if q._limit_val:
+            params['_limit'] = q._limit_val
+        if q._offset_val:
+            params['_offset'] = q._offset_val
+        if q._order_by_cols:
+            params['_order_by'] = ','.join(q._order_by_cols)
+        return params
+
+    def _query_finance(self, table_name: str, params: dict = None) -> pd.DataFrame:
+        data = self._get(f"/table/{table_name}", params)
+        if not data:
+            return pd.DataFrame()
+        df = pd.DataFrame(data)
+        if "id" in df.columns:
+            df.drop(columns=["id"], inplace=True)
+        return df
+
+    def get_factor_data(self, codes, start_date, end_date, fields=None):
+        params = {"securities": ",".join(codes) if isinstance(codes, list) else codes}
+        if start_date:
+            params["start_date"] = str(start_date)
+        if end_date:
+            params["end_date"] = str(end_date)
+        if fields:
+            params["factors"] = ",".join(fields)
+        return self._get("/get_factor_values", params)
+
+
+ARDataClient = APIClient

ardata_sdk-1.0.0/ardata_sdk/api/extras.py

@@ -0,0 +1,31 @@
+from ..config import get_client
+
+
+def get_extras(info='is_st', security_list=None, start_date=None, end_date=None, df=True):
+    """spec: get_extras(info, security_list, start_date, end_date, df=True).
+    df=True  -> pandas.DataFrame, 行=日期(datetime), 列=股票代码.
+    df=False -> dict {code: numpy.ndarray(bool)}.
+    """
+    import pandas as pd
+    import numpy as np
+    if security_list is None:
+        return pd.DataFrame() if df else {}
+    client = get_client()
+    list_str = ','.join(security_list) if isinstance(security_list, list) else security_list
+    params = {'info': info, 'security_list': list_str, 'df': str(df).lower()}
+    if start_date:
+        params['start_date'] = start_date
+    if end_date:
+        params['end_date'] = end_date
+    raw = client.get('/get_extras', params=params)
+    if not raw:
+        return pd.DataFrame() if df else {}
+    if df:
+        # server 返回 {index, columns, data}; data 是 {code: {day: value}}
+        from datetime import date as _date
+        idx = [_date.fromisoformat(d) for d in raw['index']]
+        cols = raw['columns']
+        data = {c: [raw['data'].get(c, {}).get(d) for d in raw['index']] for c in cols}
+        return pd.DataFrame(data, index=pd.DatetimeIndex(idx), columns=cols)
+    else:
+        return {c: np.array(list(raw.get(c, [])), dtype=bool) for c in raw}

ardata_sdk-1.0.0/ardata_sdk/api/factors.py

@@ -0,0 +1,45 @@
+from ..config import get_client
+
+
+def get_all_factors():
+    """获取所有可用因子名. 返回 list[str] (spec)."""
+    client = get_client()
+    data = client.get('/get_all_factors')
+    if isinstance(data, list):
+        # server 返回 [{factor: name}, ...] 或 [name, ...], 统一为 list[str]
+        if data and isinstance(data[0], dict):
+            return [d.get('factor') for d in data if d.get('factor')]
+        return list(data)
+    return []
+
+
+def get_factor_values(securities, factors, *, start_date=None, end_date=None, count=1):
+    """spec: get_factor_values(securities, factors, start_date, end_date, count)
+    后两个参数 keyword-only 避免与历史 positional 调用混淆.
+    返回: dict[factor_name -> DataFrame(date x code)]"""
+    client = get_client()
+    params = {
+        'securities': ','.join(securities) if isinstance(securities, list) else securities,
+        'factors': ','.join(factors) if isinstance(factors, list) else factors,
+        'count': count,
+    }
+    if start_date:
+        params['start_date'] = start_date
+    if end_date:
+        params['end_date'] = end_date
+    data = client.get('/get_factor_values', params=params)
+
+    import pandas as pd
+    result = {}
+    for date_str, stocks in data.items():
+        for code, values in stocks.items():
+            for fname, fval in values.items():
+                if fname not in result:
+                    result[fname] = {}
+                if date_str not in result[fname]:
+                    result[fname][date_str] = {}
+                result[fname][date_str][code] = fval
+
+    for fname in result:
+        result[fname] = pd.DataFrame(result[fname]).T
+    return result

ardata_sdk-1.0.0/ardata_sdk/api/fundamentals.py

@@ -0,0 +1,156 @@
+from ..config import get_client
+
+
+# spec 字段名 -> 本地 valuation 表列名 (因 ARData 用了 'total_market_cap' 而本地是 'market_cap')
+_VALUATION_FIELD_ALIASES = {
+    "total_market_cap":   "market_cap",
+    "total_cap":          "market_cap",
+    "mkt_cap":            "market_cap",
+    # 其它字段 1-to-1 (pe_ratio, pb_ratio, ps_ratio, pcf_ratio, turnover_ratio 等)
+    "pe_ratio_ttm":       "pe_ratio_lyr",  # 简化映射
+}
+
+
+def _translate_valuation_fields(fields):
+    """spec -> 本地 列名映射; 不识别的字段保持原样 (服务端会 400)."""
+    if fields is None:
+        return None
+    items = fields.split(",") if isinstance(fields, str) else list(fields)
+    out = [_VALUATION_FIELD_ALIASES.get(f.strip(), f.strip()) for f in items]
+    return ",".join(out) if isinstance(fields, str) else out
+
+
+def get_valuation(security, start_date=None, end_date=None, fields=None, count=None):
+    """spec: get_valuation(security, start_date, end_date, fields, count) -> DataFrame (index=day).
+    count: take the most recent N rows (ORDER BY day DESC LIMIT N).
+    spec 字段名 (如 total_market_cap) 自动翻译成本地表列名 (market_cap)."""
+    client = get_client()
+    params = {"security": security}
+    if start_date:
+        params["start_date"] = start_date
+    if end_date:
+        params["end_date"] = end_date
+    if fields is not None:
+        params["fields"] = _translate_valuation_fields(fields)
+    if count is not None:
+        params["count"] = count
+    data = client.get("/get_valuation", params=params)
+    df = client.to_dataframe(data)
+    if not df.empty and "day" in df.columns:
+        df = df.set_index("day")
+    return df
+
+
+def get_fundamentals(query_object, date=None, statDate=None):
+    """spec: get_fundamentals(query_object, date, statDate) -> DataFrame.
+    query_object accepts a Query instance (recommended) or a table name string (back-compat).
+    Routes through /table/{table} via finance.run_query, applying date/statDate as
+    additional filter params on the table.
+
+    date: 查询日期, 传 '2015-10-15' 格式, 过滤 day <= date 或 pubDate <= date
+    statDate: 财报统计季度/年份, 传 '2014q1' 或 '2014', 过滤 statDate = 对应季末
+    """
+    from ..finance import run_query
+    from ..finance.query import Query
+    if isinstance(query_object, Query):
+        q = query_object
+    else:
+        q = Query(query_object)
+
+    if date is not None:
+        from datetime import date as _date
+        from ..finance.columns import Compare
+        try:
+            parsed = str(_date.fromisoformat(str(date).replace('/', '-')))
+        except ValueError:
+            parsed = str(date)
+        if q._table == 'valuation':
+            q._filters.append({'col': 'day', 'op': 'lte', 'val': parsed})
+        else:
+            q._filters.append({'col': 'pubDate', 'op': 'lte', 'val': parsed})
+
+    if statDate is not None:
+        s = str(statDate)
+        if 'q' in s:
+            year, qtr = s.split('q', 1)
+            quarter_end = {'1': '03-31', '2': '06-30', '3': '09-30', '4': '12-31'}.get(qtr)
+            if quarter_end:
+                from ..finance.columns import Compare
+                q._filters.append({'col': 'statDate', 'op': 'eq', 'val': f'{year}-{quarter_end}'})
+        else:
+            from ..finance.columns import Compare
+            q._filters.append({'col': 'statDate', 'op': 'lte', 'val': f'{s}-12-31'})
+
+    return run_query(q)
+
+
+def get_fundamentals_continuously(query_object, end_date=None, count=None, panel=True):
+    """spec: get_fundamentals_continuously(query_object, end_date, count, panel).
+    对估值/财务时间序列表取 end_date 之前 count 条.
+    panel=True (默认) -> dict[code -> DataFrame]  (pandas.Panel 已弃用, 用 dict 替代).
+    panel=False -> 原始 DataFrame."""
+    import pandas as pd
+    from ..finance.query import Query
+
+    def _table_name(obj):
+        if isinstance(obj, Query):
+            return obj._table
+        return obj
+
+    table = _table_name(query_object)
+    code = None
+    if isinstance(query_object, Query):
+        for f in query_object._filters:
+            if f.get('col') == 'code' and f.get('op') == 'eq':
+                code = f.get('val')
+                break
+
+    client = get_client()
+    params = {'table': table}
+    if code:
+        params['code'] = code
+    if end_date:
+        params['end_date'] = end_date
+    if count is not None:
+        params['count'] = count
+    params['panel'] = str(panel).lower()
+
+    rows = client.get('/get_fundamentals_continuously', params=params)
+    df = pd.DataFrame(rows)
+    if not panel or df.empty or 'code' not in df.columns:
+        return df
+    codes = df['code'].unique().tolist()
+    if len(codes) == 1:
+        return df.drop(columns=['code'])
+    return {c: df[df['code'] == c].drop(columns=['code']) for c in codes}
+
+
+def get_history_fundamentals(security, fields, watch_date=None, stat_date=None,
+                              count=1, interval="1q", stat_by_year=False):
+    """spec: get_history_fundamentals(security, fields, watch_date, stat_date, count, interval, stat_by_year).
+    返回 list[dict]: 历史多个报告期数据, 按 statDate 升序.
+
+    - watch_date: 仅返回 pubDate <= watch_date 的报告
+    - stat_date: 'YYYY' (年) 或 'YYYYqN' (季); 只取 <= stat_date 的报告期
+    - interval: '1q' / '1y' (本参数只用于对齐 spec, 本地实现统一按 statDate 排序)
+    - stat_by_year: True 时强制使用 indicator 表
+    """
+    import pandas as pd
+    client = get_client()
+    table = "indicator" if stat_by_year else "valuation"
+    params = {
+        "table": table,
+        "count": count,
+        "interval": interval,
+        "stat_by_year": str(stat_by_year).lower(),
+    }
+    if security:
+        params["security"] = security
+    if fields:
+        params["fields"] = ",".join(fields) if isinstance(fields, list) else fields
+    if watch_date:
+        params["watch_date"] = watch_date
+    if stat_date:
+        params["stat_date"] = stat_date
+    rows = client.get("/get_history_fundamentals", params=params)
+    return pd.DataFrame(rows)