Metadata-Version: 2.1
Name: ys_base
Version: 0.1.7
Summary: YS 统一 SDK：契约模型 / auth 客户端与差量同步 / 应用服务骨架 / 交易网关
Author-email: ys <popsars@gmail.com>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: pydantic>=2.7,<3
Requires-Dist: websockets>=13,<16
Requires-Dist: loguru>=0.7,<1
Requires-Dist: aiosqlite>=0.20,<1
Requires-Dist: motor>=3.5,<4 ; extra == "mongo"
Requires-Dist: fastapi>=0.115,<1 ; extra == "server"
Requires-Dist: uvicorn[standard]>=0.30,<1 ; extra == "server"
Requires-Dist: pyjwt[crypto]>=2.9,<3 ; extra == "server"
Requires-Dist: aiohttp>=3.10,<4 ; extra == "trade"
Requires-Dist: certifi ; extra == "trade"
Requires-Dist: exchange-calendars>=4.5 ; extra == "trade"
Requires-Dist: pandas>=2.2 ; extra == "trade"
Provides-Extra: mongo
Provides-Extra: server
Provides-Extra: trade

# ys_base

YS 统一 SDK：契约模型（contracts）、auth 客户端与差量同步（auth）、WebSocket RPC 基类（ws）、
本地存储（store，默认 SQLite）、子系统服务骨架（server，extra）、交易网关（trade，extra，P4 收编）。

```bash
pip install ys_base            # 契约 + auth 客户端 + SQLite 存储
pip install ys_base[server]    # + FastAPI 子系统骨架
pip install ys_base[trade]     # + 交易网关（纯策略系统只装这个）
```

使用 uv 添加依赖：

```bash
uv add ys_base             # 契约 + auth 客户端 + SQLite 存储
uv add "ys_base[server]"   # + FastAPI 子系统骨架
uv add "ys_base[trade]"    # + 交易网关（纯策略系统只装这个）
```

`trade` extra 由 `TradeManager` 统一装配交易客户端、行情、静态信息和收益数据服务。
每个 Manager 独占一个 `TradeRuntime`，同一 Manager 下的账号共享 Runtime；`ys_base` 不保存任何
YsQuote、YsSymbol 或 YsTrade 默认地址和凭据。

```python
from ys_base.trade import (
	Account,
	TradeManager,
	TradeRuntimeConfig,
)

manager = TradeManager(
	accounts=[
		Account(
			account="A001",
			password="...",
			trade_source="xt",
			trade_uri="ws://trade.example.com",
			profit_enabled=True,
		)
	],
	runtime_config=TradeRuntimeConfig(
		snapshot_base_url="http://quote.example.com",
		static_info_base_url="http://symbol.example.com",
		static_info_username="symbol-user",
		static_info_password="symbol-password",
		trade_data_base_url="http://trade-data.example.com",
		trade_data_username="trade-user",
		trade_data_password="trade-password",
	),
)

quotes = await manager.query_snapshots({"600000.SH", "300750.SZ"})
refreshed = await manager.query_snapshots_with_refresh({"600000.SH"}, {"f43", "f58", "f60"})
statics = await manager.query_static_infos({"600000.SH"}, {"name", "pre_close"})
alive = await manager.check_snapshot_service_alive()
```

`DefaultSnapshotFields == "f43,f58,f60"`，返回原始 `f*` 字段，并固定映射
`f43 -> close`、`f60 -> pre_close`、`f58 -> name`。不提供 `last_price` 或 `pre_price` 兼容字段；
可通过字符串或字段集合指定其他 `fields`。

- `query_snapshots()` 是无缓存单次查询，不登记后台刷新标的。
- `query_snapshots_with_refresh()` 登记当日标的和字段，并在 `09:00:00-15:30:00` 每 2 秒持续刷新；
  当日标的和字段只增不减。
- Snapshot 和 StaticInfo 缓存在上海自然日变化时会同时清空日期、标的、字段和记录。
- 只有账号明确配置 `profit_enabled=True` 时，才要求 Snapshot、StaticInfo 和 TradeData 三类服务地址齐全。

刚发布的新版本若已在 PyPI 页面可见，但 uv 仍提示该版本不存在，通常是本地缓存的 PyPI Simple Index 元数据尚未更新。先清理单包缓存并从官方源重试：
uv cache clean ys-base：优先清理单包缓存。
uv cache clean：单包清理无效时清理完整缓存。
使用 --default-index https://pypi.org/simple 从官方 PyPI 重新安装。
使用 --refresh 强制刷新解析。
```bash
uv cache clean ys-base
uv add "ys_base[trade]" --default-index https://pypi.org/simple --refresh
```

如果仍无法解析，再清理完整缓存：
```bash
uv cache clean
uv add "ys_base[trade]" --default-index https://pypi.org/simple --refresh
```

设计文档：ys_auth/docs/架构方案.md（v6 终版）、契约初稿.md。

