Metadata-Version: 2.5
Name: vikron-nautilus
Version: 0.1.0
Summary: Read Vikron Catalog data with NautilusTrader Python
Project-URL: Repository, https://gitee.com/vikron-data/vikron-nautilus
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: packaging>=24
Requires-Dist: pyarrow<27,>=21
Provides-Extra: v1
Requires-Dist: nautilus-trader<2.0.0,>=1.226.0; extra == 'v1'
Provides-Extra: v2
Requires-Dist: nautilus-trader<2.1.0,>=2.0.0rc6; extra == 'v2'
Description-Content-Type: text/markdown

# vikron-nautilus

在 Python 或 Rust 中读取 Vikron Downloader 生成的 Nautilus Catalog 数据，用于行情分析及 NautilusTrader 策略开发。

本项目提供 Python 包和 Rust crate，按使用语言安装其中一个即可。

## 使用范围

先在 Vikron Downloader 中选择对应的 Catalog 输出格式，再使用本库读取下载后的目录。

| 输出格式 | 数据目录 | Python：NautilusTrader 预计兼容范围 | Rust：Nautilus 预计兼容范围 |
| --- | --- | --- | --- |
| Catalog v1 | `vikron/catalog-v1` | `>=1.226.0, <2.0.0` | `>=0.64.0, <0.65.0`（`0.64.x`） |
| Catalog v2 | `vikron/catalog-v2` | `>=2.0.0rc6, <2.1.0` | `>=0.65.0, <0.66.0`（`0.65.x`） |

预计兼容范围用于安装依赖和选择 Catalog 版本，不代表范围内所有版本均已测试。Catalog v1 的 Python 下限 `1.226.0` 根据[官方发布说明](https://github.com/nautechsystems/nautilus_trader/blob/develop/RELEASES.md#nautilustrader-12260-beta)中的数据读取和混合回测修复推断；`1.226.0–1.229.0` 尚未进行实际数据读取测试。范围内未来发布的版本也仍需验证。

这里的 Python 1.x / 2.x 指 NautilusTrader 包版本，不是 Python 解释器版本。Rust `0.x` 的次版本可能不兼容，因此不跨次版本放宽。

已测试版本（macOS ARM64）：

| 输出格式 | Python：NautilusTrader 已通过测试 | Rust：Nautilus 已通过测试 |
| --- | --- | --- |
| Catalog v1 | `1.230.0`、`1.231.0` | `0.64.0` |
| Catalog v2 | `2.0.0rc6` | `0.65.0` |

Python 已验证原生及自定义数据的读取、空数据、数值精度和查询过滤；Rust 已验证四种自定义数据通过官方 Catalog 读取。`2.0.0rc5` 经测试缺少所需查询接口，不支持。当前验证的 Python 2.x 仍为预发布版，建议生产环境固定使用已测试版本。

支持读取的数据：

| 数据 | 类型归属 | Python 类型 | Rust 类型 |
| --- | --- | --- | --- |
| 报价 | Nautilus 原生 | `QuoteTick` | `QuoteTick` |
| 成交 | Nautilus 原生 | `TradeTick` | `TradeTick` |
| 订单簿增量 | Nautilus 原生 | `OrderBookDelta` | `OrderBookDelta` |
| 标记价格 | Nautilus 原生 | `MarkPriceUpdate` | `MarkPriceUpdate` |
| 指数价格 | Nautilus 原生 | `IndexPriceUpdate` | `IndexPriceUpdate` |
| 资金费率 | Nautilus 原生 | `FundingRateUpdate` | `FundingRateUpdate` |
| 强平 | Vikron 自定义 | `Liquidation` | `Liquidation` |
| 持仓量 | Vikron 自定义 | `OpenInterestUpdate` | `OpenInterestUpdate` |
| 最新价格 | Vikron 自定义 | `LastPriceUpdate` | `LastPriceUpdate` |
| 预测资金费率 | Vikron 自定义 | `PredictedFundingRateUpdate` | `PredictedFundingRateUpdate` |

具体可用的数据取决于 Downloader 的输出。本库不下载行情、不转换 CSV，也不创建或补全交易品种的 `Instrument` 信息。

## Python 使用方法

### 安装

需要 Python 3.12 或以上版本，同时满足对应 NautilusTrader 版本的平台要求。建议为两个版本分别创建虚拟环境，不要混装。

使用 Catalog v1：

```sh
python -m pip install "vikron-nautilus[v1]==0.1.0"
```

使用 Catalog v2：

```sh
python -m pip install "vikron-nautilus[v2]==0.1.0"
```

### 读取数据

下面以 Catalog v2 的强平数据为例。路径指向 Catalog 根目录，不是其中的 `data` 子目录；将路径和品种替换成自己的数据。

```python
from vikron_nautilus import Catalog, Liquidation

catalog = Catalog("./data/vikron/catalog-v2", version=2)
events = catalog.query(
    Liquidation,
    identifiers=["ETHUSDT-PERP.BINANCE"],
)
for event in events:
    print(event.instrument_id, event.price, event.size, event.ts_init)
```

使用 v1 时，将路径改成 `./data/vikron/catalog-v1`，并设置 `version=1`。

读取原生行情类型时，替换查询类型即可。例如，v2 的报价数据：

```python
from nautilus_trader.model import QuoteTick

quotes = catalog.query(QuoteTick, identifiers=["ETHUSDT-PERP.BINANCE"])
```

v1 的原生行情类型从 `nautilus_trader.model.data` 导入：

```python
from nautilus_trader.model.data import QuoteTick
```

### 限定查询范围

`identifiers` 使用完整的 Nautilus `InstrumentId`。`start` 和 `end` 是 Unix 纳秒时间戳，按 `ts_init` 筛选，包含起止边界；省略参数表示不限制该条件。

```python
events = catalog.query(
    Liquidation,
    identifiers=["ETHUSDT-PERP.BINANCE"],
    start=1788220800000000000,  # 2026-09-01 00:00:00 UTC
    end=1788307199999999999,    # 2026-09-01 当天结束（UTC）
)
```

查询返回对象列表，空数据返回空列表。较大的历史范围建议按日期和品种分批读取。

### 使用自定义数据

本库的 `Catalog` 会自动注册上表中的四种自定义数据。若直接使用 Nautilus 官方接口或在策略中使用这些类型，请先调用：

```python
from vikron_nautilus import register_custom_types

register_custom_types()
```

Python 1.x 读取 Downloader 的 Catalog v1 时，请使用本库的 `Catalog`。

## Rust 使用方法

### 添加依赖

需要 Rust 1.98.1 或以上版本。在项目的 `Cargo.toml` 中添加以下依赖。

Catalog v2（默认）：

```toml
[dependencies]
anyhow = "1"
vikron-nautilus = "0.1.0"
nautilus-model = { version = "0.65", features = ["high-precision"] }
nautilus-persistence = { version = "0.65", features = ["high-precision"] }
```

Catalog v1：

```toml
[dependencies]
anyhow = "1"
vikron-nautilus = { version = "0.1.0", default-features = false, features = ["catalog-v1"] }
nautilus-model = { version = "0.64", features = ["high-precision"] }
nautilus-persistence = { version = "0.64", features = ["high-precision"] }
```

`catalog-v1` 和 `catalog-v2` 必须二选一，不要同时启用。

### 读取自定义数据

以下为 v2 示例：

```rust
use nautilus_model::data::Data;
use nautilus_persistence::backend::parquet::catalog::ParquetDataCatalog;
use vikron_nautilus::{Liquidation, register_custom_types};

fn main() -> anyhow::Result<()> {
    register_custom_types()?;
    let path = std::path::Path::new("./data/vikron/catalog-v2");
    let mut catalog = ParquetDataCatalog::new(path, None, None, None, None);
    let identifiers = vec!["ETHUSDT-PERP.BINANCE".to_string()];
    let events = catalog.query_custom_data_dynamic(
        "VikronLiquidation", Some(&identifiers), None, None, None, None, false,
    )?;

    for event in events {
        if let Data::Custom(custom) = event {
            if let Some(value) = custom.data.as_any().downcast_ref::<Liquidation>() {
                println!("{} {} {}", value.instrument_id, value.price, value.size);
            }
        }
    }
    Ok(())
}
```

使用 v1 时，将目录改为 `catalog-v1`，并将 `ParquetDataCatalog` 的导入改为：

```rust
use nautilus_persistence::backend::catalog::ParquetDataCatalog;
```

自定义数据的查询名称为类型名前加 `Vikron`，例如 `VikronOpenInterestUpdate`，读取后转换为对应 Rust 类型即可。Python 使用 `Catalog.query(Liquidation)` 等类型查询，无需手动添加前缀。已有 Catalog 文件无需修改。报价、成交等原生数据使用对应版本的 Nautilus 官方查询接口。

## 使用注意事项

- 不要混用 v1 与 v2 数据目录，选择与 Nautilus 版本匹配的输出格式。
- Python 自定义数据中的价格、数量和费率使用 `Decimal`，需要精确保留数值时避免转成 `float`。
- 回测或交易所需的 `Instrument` 信息需要自行提供。本库的自定义数据是行情观察事件，不会自动触发撮合或资金费结算。

## 许可证

本库采用 [MIT 许可证](LICENSE)。该许可不改变 Vikron Downloader 及依赖的许可证，也不授予行情数据的访问或再分发权利。
