Metadata-Version: 2.4
Name: finosdk_fiona_data
Version: 1.0.1
Summary: Python SDK for accessing Finoview financial data services
Author: 上海东证期货有限公司
License-Expression: MIT
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.1
Requires-Dist: pandas<3,>=1.5
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Dynamic: license-file

# finosdk_fiona_data 使用说明

## 概览

`finosdk_fiona_data` 是 Finoview 数据服务的 Python SDK，用于在 Python 环境中访问 Finoview 的金融数据产品。

SDK 只保留产品化入口：

| 数据产品 | 推荐入口 | 说明 |
| --- | --- | --- |
| 市场数据 | `finosdk.marketdata` | 交易日历、合约信息、行情、持仓、仓单、价差、波动率等标准市场数据 |
| 因子数据 | `finosdk.factor` | 商品因子、国债因子、因子回测与测试数据 |
| 研究数据 | `finosdk.research` | 市场预期研判、机构观点统计等研究数据 |

顶层 `finosdk` 只暴露初始化、版本、异常、产品清单和三大产品模块，不再平铺导出 `get_xxx` 函数。

## 环境要求

| 项目 | 要求 |
| --- | --- |
| Python 版本 | `>=3.9`，推荐 `3.10` 或 `3.11` |
| 操作系统 | Windows / macOS / Linux |
| 主要依赖 | `requests>=2.25.1`，`pandas>=1.5,<3` |

## 安装

```bash
pip install -U finosdk_fiona_data -i https://pypi.org/simple
```

如需安装指定版本：

```bash
pip install finosdk_fiona_data==1.0.1 -i https://pypi.org/simple
```

## 配置 API Key

推荐使用环境变量配置 token。

Windows PowerShell:

```powershell
$env:FINO_API_KEY="your_api_key"
```

Windows CMD:

```cmd
set FINO_API_KEY=your_api_key
```

Linux / macOS:

```bash
export FINO_API_KEY="your_api_key"
```

也可以在代码中显式传入：

```python
import finosdk as fino

fino.init(api_key="your_api_key")
```

## 初始化

```python
import finosdk as fino

fino.init()
```

如需指定服务地址或超时时间：

```python
fino.init(
    api_key="your_api_key",
    base_url="https://track.finoview.com.cn/data_api/",
    timeout=30,
)
```

## 产品清单

```python
import finosdk as fino

print(fino.get_products())
```

## 返回格式

大多数接口默认返回 `pandas.DataFrame`。如需获取服务端原始 `data`，传入 `as_df=False`。

```python
df = fino.marketdata.quotes.get_dominant_quotes(
    start_date="20250102",
    end_date="20250130",
    symbol="RB",
)

rows = fino.marketdata.quotes.get_dominant_quotes(
    start_date="20250102",
    end_date="20250130",
    symbol="RB",
    as_df=False,
)
```

## 市场数据

市场数据按数据类型拆分：

| 模块 | 入口 | 常用函数 |
| --- | --- | --- |
| 基础信息 | `fino.marketdata.basic_info` | `get_trading_calendar`、`get_futures_product_info`、`get_previous_trade_day` |
| 行情数据 | `fino.marketdata.quotes` | `get_dominant_quotes`、`get_intraday_ticks`、`get_latest_minute_bars` |
| 市场统计 | `fino.marketdata.stats` | `get_exchange_daily_bars`、`get_term_structure_yield`、`get_index_dividend_points` |
| 持仓统计 | `fino.marketdata.positions` | `get_member_positions`、`get_fund_flow`、`get_section_statistics` |
| 仓单库存 | `fino.marketdata.warehouse` | `get_warehouse_quantity`、`get_warehouse_distribution` |
| 价差数据 | `fino.marketdata.spread` | `get_basis`、`get_monthly_spread`、`get_realtime_index_basis` |
| 期权数据 | `fino.marketdata.options` | `get_option_contract_selection`、`get_option_risk_metrics`、`get_option_derived_metrics` |
| 波动率数据 | `fino.marketdata.volatility` | `get_historical_volatility`、`get_implied_volatility` |

示例：

```python
import finosdk as fino

fino.init()

df = fino.marketdata.quotes.get_dominant_quotes(
    start_date="20250102",
    end_date="20250130",
    symbol="RB",
)
```

## 因子数据

因子数据按产品拆分：

| 数据产品 | 入口 | 说明 |
| --- | --- | --- |
| 商品因子 | `fino.factor.commodity` | carry、trend、position、futurespot、value、warrant、volatility |
| 国债因子 | `fino.factor.treasury` | basis、intradaytech、l2、position、riskyassets |
| 因子回测/测试 | `fino.factor.csft` | `get_csft_bkt_*`、`get_csft_test_*` |

商品因子示例：

```python
df = fino.factor.commodity.get_trend(
    start_date="20250102",
    end_date="20250130",
    code_list=["JD"],
    factor=["T_overnight_k240"],
    section=["农产品"],
)
```

国债因子示例：

```python
df = fino.factor.treasury.get_basis(
    start_date="20250102",
    end_date="20250130",
    code_list=["T"],
)
```

因子回测示例：

```python
df = fino.factor.csft.get_csft_bkt_perf(
    start_date="20250102",
    end_date="20250130",
    factor=["T_overnight_k240"],
)
```

## 研究数据

当前已提供市场预期研判相关接口：

```python
df = fino.research.rating.get_overview(
    report_type="daily",
    start_date="20250102",
    end_date="20250130",
)
```

## 异常说明

SDK 会把请求错误和服务端错误包装为统一异常：

| 异常 | 说明 |
| --- | --- |
| `FinoHTTPError` | HTTP 请求失败或服务端返回非 200 状态码 |
| `FinoAPIError` | 服务端返回业务错误，例如 `code != 200` |
| `FinoValidationError` | SDK 侧参数校验错误，预留给后续扩展 |

常见问题：

| 问题 | 可能原因 |
| --- | --- |
| `401 Unauthorized` | API Key 无效、过期或未配置 |
| `403 Forbidden` | 当前 token 没有该数据产品权限 |
| `429 Too Many Requests` | 调用频率超限 |
| 请求超时 | 查询区间过大、网络异常或服务端处理时间较长 |
| 返回空表 | 查询条件下没有数据，或过滤条件过窄 |

## 版本查看

```bash
pip show finosdk_fiona_data
```

```python
import finosdk as fino

print(fino.__version__)
```
