Metadata-Version: 2.5
Name: aibeta
Version: 0.3.0
Summary: 板块指标库 API SDK
Author: 伍老师
License-Expression: MIT
License-File: LICENSE
Keywords: aibeta,citics,indicator,research,sdk
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: pandas>=2.2.0
Requires-Dist: pyarrow>=17.0.0
Requires-Dist: requests>=2.32.0
Requires-Dist: tqdm>=4.66.0
Description-Content-Type: text/markdown

# aibeta-sdk

板块指标库 API SDK，提供主题分类与指标库数据的统一查询接口。

## 安装

```bash
pip install aibeta
```

## 配置凭证

SDK 需要 `app_key` / `secret_key` 两个凭证，二选一方式提供：

```python
import aibeta
# 方式一：代码内配置（对当前进程有效）
aibeta.configuration(app_key="XXX", secret_key="XXX")
```

或通过环境变量配置（不调用 `configuration` 时自动读取）：

```bash
# 方式二：通过环境变量配置（长期有效）
export BETA_INDICATOR_API_APP_KEY="XXX"
export BETA_INDICATOR_API_SECRET_KEY="XXX"
```

## 快速使用

```python
from aibeta import theme_classification, beta_indicator

# 指标库：读取所有指标类型
beta_indicator.list_indicator_types()
```

完整接口示例见 `examples/import_script.py`。

## 接口说明

数据类接口统一返回 `pandas.DataFrame`（`get_indicator_value_batch` 除外）。凭证配置见上方「配置凭证」。

### 全局配置

| 接口              | 调用方式                      | 功能简介                     | 参数                                               |
| ----------------- | ----------------------------- | ---------------------------- | -------------------------------------------------- |
| `configuration` | `aibeta.configuration(...)` | 配置当前进程的凭证与超时参数 | `app_key` / `secret_key` / `timeout`，均可选 |

### 主题分类 `theme_classification`

| 接口                                         | 调用方式                                                                     | 功能简介                         | 参数                         |
| -------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------- | ---------------------------- |
| `get_theme_classification_framework_inc`   | `theme_classification.get_theme_classification_framework_inc(view_date)`   | 主题库日度增量数据               | `view_date: str`，查询日期 |
| `get_theme_classification_framework_daily` | `theme_classification.get_theme_classification_framework_daily(view_date)` | 主题库日度截面数据               | `view_date: str`，查询日期 |
| `get_theme_classification_portfolio_inc`   | `theme_classification.get_theme_classification_portfolio_inc(view_date)`   | 主题成分股（标准池）日度增量数据 | `view_date: str`，查询日期 |
| `get_theme_classification_portfolio_daily` | `theme_classification.get_theme_classification_portfolio_daily(view_date)` | 主题成分股（标准池）日度截面数据 | `view_date: str`，查询日期 |
| `get_theme_classification_index_inc`       | `theme_classification.get_theme_classification_index_inc(view_date)`       | 主题指数点位日度增量数据         | `view_date: str`，查询日期 |
| `get_theme_classification_index_by_id`     | `theme_classification.get_theme_classification_index_by_id(theme_id)`      | 查询特定主题的历史指数点位       | `theme_id: str`，主题 ID   |

### 指标库 `beta_indicator`

| 接口                          | 调用方式                                                                   | 功能简介                                        | 参数                                                                                         |
| ----------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `list_indicator_types`      | `beta_indicator.list_indicator_types()`                                  | 读取所有指标类型（如市盈率 PE、市净率 PB 等）   | 无                                                                                           |
| `list_indicators`           | `beta_indicator.list_indicators(indicator_type)`                         | 按指标类型读取指标列表                          | `indicator_type: str`，指标类型名称                                                        |
| `get_indicator_value`       | `beta_indicator.get_indicator_value(indicator_id)`                       | 按指标 ID 读取该指标全部数值记录                | `indicator_id: str`，指标唯一标识                                                          |
| `get_indicator_value_inc`   | `beta_indicator.get_indicator_value_inc(view_date)`                      | 按日期增量读取所有指标值                        | `view_date: str`，查询日期                                                                 |
| `list_sector_types`         | `beta_indicator.list_sector_types()`                                     | 读取所有板块类型（如 ETF 指数、中信证券行业等） | 无                                                                                           |
| `list_sectors`              | `beta_indicator.list_sectors(sector_type=None)`                          | 读取板块列表，可选按板块类型过滤                | `sector_type: str \| None`，传 `None` 返回全部                                            |
| `list_indicators_by_sector` | `beta_indicator.list_indicators_by_sector(sector_code)`                  | 按板块代码读取该板块全部指标列表                | `sector_code: str`，板块代码（如 `000001.SH`）                                           |
| `get_indicator_value_batch` | `beta_indicator.get_indicator_value_batch(indicator_ids, max_workers=3)` | 并发批量读取多个指标的数值记录                  | `indicator_ids: list[str]`，指标 ID 列表（≤30）；`max_workers: int`，最大并发数，默认 3 |

> 返回类型：`get_indicator_value_batch` 返回 `dict[str, DataFrame | None]`（key 为指标 ID，读取失败对应 `None`），其余均返回 `DataFrame`。

## 依赖

- Python >= 3.10
- pandas、pyarrow、requests、tqdm

> 缓存说明：SDK 会在用户缓存目录（`~/.cache/aibeta/`）维护指标库的全量快照缓存，默认每 3 天自动重建一次。
