vikron-nautilus 0.1.0__tar.gz

vikron_nautilus-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+/target/
+/work/
+/*-report.json
+/.vikron/
+/dist/
+/.venv*/
+**/__pycache__/
+*.egg-info/
+.env
+.env.*
+!.env.example
+.DS_Store
+**/target/

vikron_nautilus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vikron-data
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

vikron_nautilus-0.1.0/PKG-INFO

@@ -0,0 +1,212 @@
+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 及依赖的许可证，也不授予行情数据的访问或再分发权利。

vikron_nautilus-0.1.0/README.md

@@ -0,0 +1,196 @@
+# 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 及依赖的许可证，也不授予行情数据的访问或再分发权利。

vikron_nautilus-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "vikron-nautilus"
+version = "0.1.0"
+description = "Read Vikron Catalog data with NautilusTrader Python"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["pyarrow>=21,<27", "packaging>=24"]
+
+[project.urls]
+Repository = "https://gitee.com/vikron-data/vikron-nautilus"
+
+[project.optional-dependencies]
+v1 = ["nautilus-trader>=1.226.0,<2.0.0"]
+v2 = ["nautilus-trader>=2.0.0rc6,<2.1.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["python/vikron_nautilus"]
+
+[tool.hatch.build.targets.sdist]
+include = ["python", "tests/test_catalog.py", "tests/test_compat.py", "pyproject.toml", "README.md", "LICENSE"]

vikron_nautilus-0.1.0/python/vikron_nautilus/__init__.py

@@ -0,0 +1,12 @@
+"""Consumer-side registration and reading; importing does not mutate catalogs."""
+from .data import (
+    Liquidation, OpenInterestUpdate, LastPriceUpdate,
+    PredictedFundingRateUpdate, register_custom_types,
+)
+from .catalog import Catalog
+
+__all__ = [
+    "Catalog", "register_custom_types", "Liquidation",
+    "OpenInterestUpdate", "LastPriceUpdate",
+    "PredictedFundingRateUpdate",
+]

vikron_nautilus-0.1.0/python/vikron_nautilus/_compat.py

@@ -0,0 +1,17 @@
+"""Supported Nautilus Python version families."""
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
+
+SUPPORTED_VERSIONS = {
+    1: SpecifierSet(">=1.226.0,<2.0.0"),
+    2: SpecifierSet(">=2.0.0rc6,<2.1.0"),
+}
+
+
+def catalog_version(nautilus_version):
+    version = Version(nautilus_version)
+    for catalog, supported in SUPPORTED_VERSIONS.items():
+        if supported.contains(version, prereleases=True):
+            return catalog
+    ranges = "; ".join(f"v{catalog}: {spec}" for catalog, spec in SUPPORTED_VERSIONS.items())
+    raise ImportError(f"Unsupported Nautilus version {version}; supported ranges: {ranges}")

vikron_nautilus-0.1.0/python/vikron_nautilus/catalog.py

@@ -0,0 +1,86 @@
+from pathlib import Path
+from decimal import Decimal, localcontext
+
+import pyarrow.parquet as pq
+
+from .data import CUSTOM_TYPES, V2, InstrumentId, register_custom_types
+
+_DIRECTORIES = {
+    "QuoteTick": "quotes", "TradeTick": "trades",
+    "OrderBookDelta": "order_book_deltas", "MarkPriceUpdate": "mark_prices",
+    "IndexPriceUpdate": "index_prices", "FundingRateUpdate": "funding_rate_update",
+}
+
+
+class Catalog:
+    """Read-only adapter for the supported Nautilus Python 1.x and 2.0.x ranges.
+
+    query() returns native events/custom observations, sorted by ts_init.
+    start/end are inclusive UNIX nanoseconds; identifiers are InstrumentId strings.
+    No directory aliases or instrument downloads are performed.
+    """
+
+    def __init__(self, path, *, version=None):
+        expected = 2 if V2 else 1
+        if version is not None and version != expected:
+            raise ValueError(f"This Nautilus installation requires Catalog v{expected}")
+        self.path = Path(path).resolve()
+        if not self.path.is_dir():
+            raise FileNotFoundError(self.path)
+        register_custom_types()
+        if V2:
+            from nautilus_trader.persistence import ParquetDataCatalog
+        else:
+            from nautilus_trader.persistence.catalog import ParquetDataCatalog
+        self.native = ParquetDataCatalog(str(self.path))
+
+    def query(self, data_cls, *, identifiers=None, start=None, end=None):
+        if start is not None and end is not None and start > end:
+            raise ValueError("start must not exceed end")
+        name = data_cls.__name__
+        custom = data_cls in CUSTOM_TYPES
+        if custom:
+            name = data_cls.type_name_static()
+        if not custom and name not in _DIRECTORIES:
+            raise ValueError(f"Unsupported type {name}")
+        if V2:
+            from nautilus_trader.model import NautilusDataType
+            kind = NautilusDataType.Custom(name) if custom else getattr(NautilusDataType, name)
+            method = self.native.query_custom_data if custom else self.native.query
+            rows = method(kind, identifiers=identifiers, start=start, end=end)
+            # Nautilus versions can wrap observations in CustomData.
+            return [getattr(row, "data", row) if custom else row for row in rows]
+
+        directory = self.path / "data" / ("custom/" + name if custom else _DIRECTORIES[name])
+        files = sorted(str(f) for f in directory.rglob("*.parquet"))
+        if not files:
+            return []
+        if custom or name in ("MarkPriceUpdate", "IndexPriceUpdate"):
+            rows = []
+            for file in files:
+                parquet = pq.ParquetFile(file)
+                metadata = parquet.schema_arrow.metadata or {}
+                for batch in parquet.iter_batches():
+                    if custom:
+                        rows.extend(data_cls.decode_record_batch_py(metadata, batch))
+                    else:
+                        from nautilus_trader.model.objects import Price
+                        for row in batch.to_pylist():
+                            # Rust high-precision fixed point: signed little endian / 10^16.
+                            with localcontext() as context:
+                                context.prec = 50
+                                value = Decimal(int.from_bytes(row["value"], "little", signed=True)).scaleb(-16)
+                            rows.append(data_cls(
+                                InstrumentId.from_str(metadata[b"instrument_id"].decode()),
+                                Price.from_str(format(value, ".16f")),
+                                row["ts_event"], row["ts_init"],
+                            ))
+        else:
+            rows = self.native.query(data_cls, files=files)
+        return sorted(
+            (row for row in rows
+             if (identifiers is None or str(row.instrument_id) in identifiers)
+             and (start is None or row.ts_init >= start)
+             and (end is None or row.ts_init <= end)),
+            key=lambda row: row.ts_init,
+        )

vikron_nautilus-0.1.0/python/vikron_nautilus/data.py

@@ -0,0 +1,142 @@
+import json
+from decimal import Decimal
+from importlib.metadata import version
+
+import pyarrow as pa
+
+from ._compat import catalog_version
+
+NAUTILUS_VERSION = version("nautilus_trader")
+V2 = catalog_version(NAUTILUS_VERSION) == 2
+if V2:
+    from nautilus_trader.model import InstrumentId
+    BaseData = object
+else:
+    from nautilus_trader.core.data import Data as BaseData
+    from nautilus_trader.model.identifiers import InstrumentId
+
+
+class _Observation(BaseData):
+    fields = ()
+    decimals = ()
+
+    def __init__(self, instrument_id, ts_event, ts_init, **values):
+        if set(values) != set(self.fields):
+            raise ValueError(f"{type(self).__name__} requires fields {self.fields}")
+        self.instrument_id = InstrumentId.from_str(str(instrument_id))
+        self._ts_event = int(ts_event)
+        self._ts_init = int(ts_init)
+        if not (0 <= self._ts_event < 2**64 and 0 <= self._ts_init < 2**64):
+            raise ValueError("invalid event/init timestamps")
+        for name, value in values.items():
+            setattr(self, name, Decimal(str(value)) if name in self.decimals else value)
+
+    @property
+    def ts_event(self):
+        return self._ts_event
+
+    @property
+    def ts_init(self):
+        return self._ts_init
+
+    @classmethod
+    def type_name_static(cls):
+        return f"Vikron{cls.__name__}"
+
+    def to_dict(self):
+        return dict(
+            type=self.type_name_static(), instrument_id=str(self.instrument_id),
+            ts_event=self.ts_event, ts_init=self.ts_init,
+            **{name: str(getattr(self, name)) if name in self.decimals else getattr(self, name)
+               for name in self.fields},
+        )
+
+    @classmethod
+    def from_dict(cls, values):
+        values = dict(values)
+        if values.pop("type", cls.type_name_static()) != cls.type_name_static():
+            raise ValueError("unexpected custom data type")
+        return cls(**values)
+
+    def to_json(self):
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, value):
+        return cls.from_dict(value if isinstance(value, dict) else json.loads(value))
+
+    @classmethod
+    def arrow_schema_py(cls):
+        timestamp = pa.timestamp("ns", tz="UTC") if V2 else pa.uint64()
+        return pa.schema([
+            pa.field("payload", pa.string(), nullable=False),
+            pa.field("ts_event", timestamp, nullable=False),
+            pa.field("ts_init", timestamp, nullable=False),
+        ])
+
+    def encode_record_batch_py(self, items):
+        return pa.RecordBatch.from_arrays([
+            pa.array([item.to_json() for item in items]),
+            pa.array([item.ts_event for item in items], type=pa.int64() if V2 else pa.uint64()).cast(self.arrow_schema_py().field("ts_event").type),
+            pa.array([item.ts_init for item in items], type=pa.int64() if V2 else pa.uint64()).cast(self.arrow_schema_py().field("ts_init").type),
+        ], schema=self.arrow_schema_py())
+
+    @classmethod
+    def decode_record_batch_py(cls, metadata, batch):
+        times = batch.column("ts_init").cast(pa.int64() if V2 else pa.uint64()).to_pylist()
+        events = batch.column("ts_event").cast(pa.int64() if V2 else pa.uint64()).to_pylist()
+        rows = []
+        for payload, event, init in zip(batch.column("payload").to_pylist(), events, times):
+            values = json.loads(payload)
+            values.update(ts_event=event, ts_init=init)
+            rows.append(cls.from_dict(values))
+        return rows
+
+
+class Liquidation(_Observation):
+    fields = ("source_id", "side", "price", "size")
+    decimals = ("price", "size")
+
+
+class OpenInterestUpdate(_Observation):
+    fields = ("open_interest",)
+    decimals = fields
+
+
+class LastPriceUpdate(_Observation):
+    fields = ("price",)
+    decimals = fields
+
+
+class PredictedFundingRateUpdate(_Observation):
+    fields = ("rate", "funding_timestamp")
+    decimals = ("rate",)
+
+
+CUSTOM_TYPES = (
+    Liquidation, OpenInterestUpdate,
+    LastPriceUpdate, PredictedFundingRateUpdate,
+)
+_registered = False
+
+
+def register_custom_types():
+    """Register once per interpreter, before querying/subscribing to custom data."""
+    global _registered
+    if _registered:
+        return
+    if V2:
+        from nautilus_trader.model import register_custom_data_class
+        for cls in CUSTOM_TYPES:
+            register_custom_data_class(cls)
+    else:
+        from nautilus_trader.serialization import register_serializable_type
+        from nautilus_trader.serialization.arrow.serializer import register_arrow
+        for cls in CUSTOM_TYPES:
+            register_serializable_type(cls, cls.to_dict, cls.from_dict)
+            register_arrow(
+                cls, cls.arrow_schema_py(),
+                encoder=lambda obj: obj.encode_record_batch_py([obj]),
+                decoder=lambda batch, cls=cls: cls.decode_record_batch_py({}, batch),
+            )
+    _registered = True

vikron_nautilus-0.1.0/tests/test_catalog.py

@@ -0,0 +1,72 @@
+"""Integration checks against fixtures exported by downloader's versions test."""
+import sys
+from pathlib import Path
+from decimal import Decimal
+
+from vikron_nautilus import (
+    Catalog, register_custom_types, Liquidation, OpenInterestUpdate,
+    LastPriceUpdate, PredictedFundingRateUpdate,
+)
+from vikron_nautilus.data import V2, CUSTOM_TYPES
+
+if V2:
+    from nautilus_trader import model
+else:
+    from nautilus_trader.model import data as model
+
+base = Path(sys.argv[1])
+if not V2:
+    base = base / "v1"
+register_custom_types()
+register_custom_types()
+assert CUSTOM_TYPES == (Liquidation, OpenInterestUpdate, LastPriceUpdate, PredictedFundingRateUpdate)
+for cls in CUSTOM_TYPES:
+    assert not cls.__name__.startswith("Vikron")
+    assert cls.type_name_static() == f"Vikron{cls.__name__}"
+count = 0
+for kind, types in [
+    ("BookTicker", [model.QuoteTick]),
+    ("Trades", [model.TradeTick]),
+    ("BookDeltas", [model.OrderBookDelta]),
+    ("Liquidations", [CUSTOM_TYPES[0]]),
+    ("DerivativeTicker", [
+        model.MarkPriceUpdate, model.IndexPriceUpdate, model.FundingRateUpdate,
+        *CUSTOM_TYPES[1:],
+    ]),
+]:
+    for empty in (False, True):
+        catalog = Catalog(base / f"{kind}-{str(empty).lower()}", version=2 if V2 else 1)
+        for cls in types:
+            rows = catalog.query(cls)
+            assert len(rows) == (0 if empty else (2 if kind == "BookDeltas" else 1)), (kind, cls, rows)
+            for row in rows:
+                assert row.ts_event == 1788220800000000000
+                assert row.ts_init == 1788220800000001000
+                assert str(row.instrument_id) == "ETHUSDT-PERP.BINANCE"
+            if rows and kind == "BookTicker":
+                assert str(rows[0].bid_price) == "1.0000000000000001"
+            if rows and kind == "Liquidations":
+                assert rows[0].price == Decimal("1.0000000000000001")
+                assert rows[0].size == Decimal("3")
+                assert rows[0].side == "BUY"
+                assert rows[0].source_id == "001"
+            if rows and cls in CUSTOM_TYPES:
+                event = rows[0]
+                assert type(event) is cls
+                assert event.to_dict()["type"] == cls.type_name_static()
+                assert cls.from_json(event.to_json()).to_dict() == event.to_dict()
+                if V2:
+                    from nautilus_trader.model import CustomData, DataType
+                    wrapper = CustomData(DataType(cls.type_name_static(), {"instrument_id": str(event.instrument_id)}, str(event.instrument_id)), event)
+                    restored = CustomData.from_json_bytes(bytes(wrapper.to_json_bytes()))
+                    assert restored.data.to_dict() == event.to_dict()
+                else:
+                    from nautilus_trader.model.data import CustomData, DataType
+                    wrapper = CustomData(DataType(cls, {"instrument_id": str(event.instrument_id)}), event)
+                    assert wrapper.ts_init == event.ts_init
+            assert catalog.query(cls, start=1788220800000001001) == []
+            assert catalog.query(cls, identifiers=["OTHER.BINANCE"]) == []
+            assert len(catalog.query(cls, start=1788220800000001000, end=1788220800000001000)) == len(rows)
+            count += 1
+            print("PASS", kind, cls.__name__, "empty=", empty)
+print(f"Passed {count} cases; Nautilus Python {'2' if V2 else '1'}")

vikron_nautilus-0.1.0/tests/test_compat.py

@@ -0,0 +1,40 @@
+"""Version selection and dependency-range consistency checks."""
+import tomllib
+import unittest
+from pathlib import Path
+
+from packaging.requirements import Requirement
+
+from vikron_nautilus._compat import SUPPORTED_VERSIONS, catalog_version
+
+
+class VersionTests(unittest.TestCase):
+    def test_supported_version_selection(self):
+        for version, expected in [
+            ("1.226.0", 1), ("1.227.0", 1), ("1.228.0", 1), ("1.229.0", 1),
+            ("1.230.0", 1), ("1.231.0", 1), ("1.231.1", 1),
+            ("2.0.0rc6", 2), ("2.0.0", 2), ("2.0.1", 2),
+        ]:
+            with self.subTest(version=version):
+                self.assertEqual(catalog_version(version), expected)
+
+    def test_unsupported_version_selection(self):
+        for version in [
+            "1.225.0", "1.226.0rc1", "2.0.0a1", "2.0.0rc4", "2.0.0rc5",
+            "2.1.0rc1", "2.1.0", "3.0.0",
+        ]:
+            with self.subTest(version=version):
+                with self.assertRaises(ImportError):
+                    catalog_version(version)
+
+    def test_install_ranges_match_runtime(self):
+        metadata = tomllib.loads((Path(__file__).parents[1] / "pyproject.toml").read_text())
+        extras = metadata["project"]["optional-dependencies"]
+        for catalog, supported in SUPPORTED_VERSIONS.items():
+            requirement = Requirement(extras[f"v{catalog}"][0])
+            self.assertEqual(requirement.name, "nautilus-trader")
+            self.assertEqual(requirement.specifier, supported)
+
+
+if __name__ == "__main__":
+    unittest.main()