Metadata-Version: 2.4
Name: fxxking-data-client
Version: 0.3.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

`0.3.1` 在 API contract `2` 上新增历史 close 序列，同时保留 `0.3.0` 的 bars v2：bars Arrow Schema 的
`currency` 允许来源事实缺失时保持 `null`，同步/异步 HTTP 请求默认携带
`X-API-Contract-Version: 2`，实时连接默认携带
`api_contract_version=2`。两条 A 股 ashare-lake 独立订阅能力继续保留：

```python
async with MarketDataStreamClient(base_url, token) as client:
    latest = await client.open_latest_price_subscription(
        market="CN",
        symbol="600519.SH",
        poll_interval="5m",
    )
    closed = await client.open_closed_bar_subscription(
        market="CN",
        symbol="600519.SH",
        interval="5m",
    )
```

两个句柄均提供 `initial_status()`、`current_status()`、
`status_updates()`、`events()` 和 `aclose()`。
`CLIENT_VERSION_SERIES="0.3.x"` 表示只接受 API contract `2` 的兼容系列。

`fxxking-data-client` 是 `fxxking-data` 服务的来源无关 Python Client。
候选版本为 `0.3.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.3.1
```

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

## 兼容范围

Client `0.3.x` 只接受 API contract `2`。同步和异步 Client 在首次搜索、详情、K 线
或 backfill 创建前读取服务的公开只读 `GET /v1/capabilities`；实时 Client 在建立 bars
WebSocket 前执行同一握手。成功后在当前实例内缓存。capabilities 缺失、Schema 错误、
contract 不是 `2` 或缺少必需能力时抛出
`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
```

只需要历史收盘事实时，使用独立 close 序列接口；该接口不会把尚未通过完整
OHLC 门禁的行声明为 Canonical bars：

```python
from datetime import UTC, datetime

with MarketDataClient("https://data.example.invalid", "service-token") as client:
    closes = client.get_close_series(
        symbols=(".NDX.US", ".SPX.US"),
        market="US",
        start=datetime(2021, 1, 1, tzinfo=UTC),
        end=datetime(2026, 1, 1, tzinfo=UTC),
        source="longbridge",
    )
```

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