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

# ys_base

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

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

使用 uv 添加依赖：

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

本仓库开发与全量测试需要安装全部 extras：

```bash
uv python install 3.13
uv sync --all-extras --frozen
uv run pytest
```

## 快速发布到 PyPI

先在 `ys_base/__init__.py` 中更新 `__version__`。PyPI 不允许覆盖已经发布的同版本文件，因此每次发布必须使用新版本号。
使用 project-scoped PyPI token，并将其保存在 macOS 钥匙串，不在项目目录、环境文件或 Shell 配置中保存明文 Token。

必须使用经典的“钥匙串访问”应用手动添加:文件 -> 新建密码项，不要使用新版“密码”App。新版“密码”App 管理的是网站密码，会强制要求填写网站，凭据类型不适合 PyPI 发布 Token。

在“钥匙串访问”中选择“登录”钥匙串，手动添加密码项目并填写：

- 钥匙串项目名称：`pypi:__token__`
- 账户名称：当前 macOS 用户名
- 密码：完整的 PyPI project-scoped Token

保存后不要使用会直接输出密码内容的命令检查 Token。发布脚本会从钥匙串读取该通用密码，并只注入单次 `uv publish` 进程，不会打印、写入项目文件或长期导出为环境变量。

在 `ys_platform` 仓库根目录执行：

```bash
cd ys_base
./publish-pypi.sh
```

脚本会自动运行测试、构建、审计 wheel/sdist、上传，并校验 PyPI 文件哈希。发布成功后可重新安装当前版本复核：

```bash
uv cache clean ys-base
version=$(sed -n 's/__version__ = "\([^"]*\)"/\1/p' ys_base/ys_base/__init__.py)
uv pip install "ys_base==$version" --default-index https://pypi.org/simple --refresh
```

`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(
		quote_data_base_url="http://quote.example.com",
		symbol_data_base_url="http://symbol.example.com",
		symbol_data_username="symbol-user",
		symbol_data_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
```

当前四仓边界、公共包依赖和配置规则见仓库根 `docs/架构方案.md`。
