Metadata-Version: 2.4
Name: fxxking-data-client
Version: 0.1.1
Summary: Source-independent Python client for fxxking-data.
License-Expression: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: httpx<1.0,>=0.27
Requires-Dist: pydantic<3.0,>=2.10
Requires-Dist: pyarrow<22.0,>=18.0
Requires-Dist: websockets<16.0,>=15.0
Provides-Extra: pandas
Requires-Dist: pandas<3.0,>=2.2; extra == "pandas"
Provides-Extra: polars
Requires-Dist: polars<2.0,>=1.0; extra == "polars"
Provides-Extra: dev
Requires-Dist: build<2.0,>=1.2; extra == "dev"
Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.0,>=0.24; extra == "dev"
Requires-Dist: ruff==0.16.1; extra == "dev"
Dynamic: license-file

# fxxking-data-client

`fxxking-data-client` 是 `fxxking-data` 服务的来源无关 Python Client。
候选版本为 `0.1.1`，Python import package 保持为 `market_data_client`。

本包提供同步 HTTP Client、异步 HTTP Client、WebSocket Client，以及搜索、标的详情、
K 线、报价、日历和市场状态的强类型请求与响应模型。它不包含服务端实现、存储实现或
Longbridge、Bitget、OpenFIGI 等金融上游 SDK。

## 安装

正式发布门禁关闭后，从 PyPI 安装精确版本：

```bash
python -m pip install fxxking-data-client==0.1.1
```

当前仓只生成并验证本地 wheel/sdist 发布候选，尚未执行 PyPI 发布。`client/dist/`
不是正式 registry，不得据此声明该版本已经发布。

## 兼容范围

Client `0.1.x` 只接受 API contract `1`。同步和异步 Client 在首次搜索、详情或 K 线
请求前读取服务的公开只读 `GET /v1/capabilities`；成功后在当前实例内缓存。capabilities
缺失、Schema 错误、contract 为 `0`/`2` 或缺少 M1 必需能力时抛出
`CompatibilityError`，不会继续访问旧接口或使用 fallback。

## M1 最小使用

```python
from market_data_client import MarketDataClient

with MarketDataClient(
    "https://data.example.invalid",
    "service-token",
) as client:
    search = client.search_instruments("AAPL", market="US")
    instrument_id = search.items[0].instrument_id
    details = client.get_instrument(instrument_id)
    bars = client.get_bars_by_instrument(
        instrument_ids=[instrument_id],
        market="US",
        interval="1d",
        start="2025-07-29T00:00:00Z",
        end="2026-07-30T00:00:00Z",
        adjustment="none",
    )

assert details.instrument_id == instrument_id
assert bars.items[0].instrument_id == instrument_id
```

同步与异步 Client 使用相同公共模型、稳定错误层级和兼容握手。搜索与详情成功响应
保留服务 request ID；K 线结果保留 request/result ID、row count、data version、
generated time 和 canonical hash。Client 只解释数据与协议事实，不决定业务是否运行。
Client `0.1.1` 会在同步查询、异步查询和 `get_result()` 下载后，使用唯一基础
`BARS_SCHEMA` 对每个成功 item 重算 row count 和 canonical hash；任何内容、
result identity 或 Schema metadata 不一致都会明确失败，不会静默降级。
