ohlcvault 0.1.0__py3-none-any.whl

ohlcvault/__init__.py

@@ -0,0 +1,282 @@
+"""OHLCVault —— 可复现、带校验和的公开行情数据集客户端。
+
+    OHLCV = Open/High/Low/Close/Volume, the universal bar format.
+    Vault = immutable, checksummed snapshots.
+
+设计立场（决定了这个库为什么长这样）：
+
+- **数据是事实，复权是视图。** 盘上只存不复权原始价 + 官方复权因子，
+  前/后复权由客户端算（`adjust()`）。所以历史文件永远不会因分红送转而改变，
+  `immutable` 缓存才成立，用户才有可能「一生下载一次」。
+- **没有可信校验的数据不算数据。** 每个文件都对快照清单里的 sha256 校验，
+  不匹配即丢弃并降级到下一个镜像 —— 绝不把脏数据交给调用方。
+- **可复现是一等公民。** 每次读取都锚定在一个快照 id 上（`snapshot()`），
+  把它记下来就能在任何机器、任何时间重建同一份输入。
+
+快速开始：
+
+    import ohlcvault as ov
+
+    ov.connect()                                  # 默认镜像链
+    ov.daily("600519.SH", start=20260701, end=20260918)
+    ov.cross_section("cn", 20260918, limit=50)    # 按成交额排序的日截面
+    ov.symbols("cn", type="stock", status="delisted")   # 退市股也在池内
+    ov.calendar("cn", start=20260101)
+
+离线 / 自建镜像：
+
+    ov.connect(mirrors=["/path/to/data"])         # 本地目录也是合法镜像
+    ov.connect(mirrors=[...], snapshot="be592f7a7fb5e4e3")   # 冻结复现
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .adjust import ADJUSTMENTS, apply_adjust
+from .client import MarketClient, sha256_bytes, sha256_file
+from .codes import market_of as market_of
+from .codes import normalize as normalize_symbol
+from .codes import split as split_symbol
+from .codes import to_api, to_storage
+from .config import DEFAULT_CACHE, DEFAULT_MIRRORS, MARKETS, TIMEOUT, mirrors_from_env
+from .errors import (
+    ConfigError,
+    ContractError,
+    DateError,
+    HashMismatch,
+    NotSupported,
+    OhlcvaultError,
+    SnapshotUnavailable,
+    SymbolError,
+    UnknownMarket,
+)
+from .store import Bars, Store, period_of, periods_between
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Bars", "Store", "MarketClient", "connect", "use", "reset",
+    "symbols", "symbol", "calendar", "daily", "index_daily", "daily_many",
+    "cross_section", "adjust", "snapshot", "coverage", "coverage_note",
+    "period_of", "periods_between", "sha256_bytes", "sha256_file",
+    "normalize_symbol", "to_api", "to_storage", "market_of", "split_symbol",
+    "__version__",
+    # errors
+    "OhlcvaultError", "ConfigError", "ContractError", "DateError", "HashMismatch",
+    "NotSupported", "SnapshotUnavailable", "SymbolError", "UnknownMarket",
+]
+
+_default: Store | None = None
+
+
+# ── 连接 ────────────────────────────────────────────────────────────────
+
+def connect(
+    mirrors: list[str] | None = None,
+    cache_dir: str | Path | None = None,
+    snapshot: str | None = None,
+    timeout: int = TIMEOUT,
+    validate: bool = True,
+    shard_cache: int = 4,
+    quiet: bool = False,
+) -> Store:
+    """建立（并记住）默认 Store。
+
+    `mirrors` 缺省时依次读环境变量 `OHLCVAULT_MIRRORS` 与内置默认链。
+    镜像既可以是 http(s) URL，也可以是**本地目录** —— 后者让离线复现和
+    自建镜像站都不需要额外代码。
+    """
+    global _default
+    ms = mirrors or mirrors_from_env()
+    if not ms:
+        raise ConfigError("没有可用镜像：显式传入 mirrors 或设置 OHLCVAULT_MIRRORS")
+    cli = MarketClient(ms, cache_dir or DEFAULT_CACHE, snapshot=snapshot, timeout=timeout)
+    st = Store(cli, validate=validate, shard_cache=shard_cache)
+    _default = st
+    if not quiet:
+        _announce(st)
+    return st
+
+
+def _announce(st: Store) -> None:
+    """首次连接时把「你拿到的是哪一份数据、它缺什么」说出来。
+
+    静默地返回一份有已知缺口的数据，是这个项目最不想犯的错误。
+    """
+    sid = st.snapshot
+    print(f"[ohlcvault] 快照 {sid}  镜像 {len(st.client.mirrors)} 个")
+    for mkt in MARKETS:
+        try:
+            note = st.coverage_note(mkt)
+        except OhlcvaultError:
+            continue
+        if note:
+            print(f"[ohlcvault] {mkt} 覆盖说明：{note}")
+
+
+def use(store: Store) -> Store:
+    """指定默认 Store（例如已 pinned 的实例）。"""
+    global _default
+    _default = store
+    return store
+
+
+def reset() -> None:
+    """清掉默认 Store（测试用）。"""
+    global _default
+    _default = None
+
+
+def _store() -> Store:
+    global _default
+    if _default is None:
+        _default = connect()
+    return _default
+
+
+# ── 五项需求的模块级入口（委托给默认 Store）────────────────────────────
+
+def symbols(market: str, type: str | None = None,   # noqa: A002
+            status: str | None = None, board: str | None = None,
+            include_indices: bool = True) -> list[dict]:
+    """标的清单：代码 / 名称 / 上市日 / 退市状态 / 类型 / 板块。
+
+    **含退市股**（`status="delisted"`）。回测池若只含今天还活着的股票，
+    历史收益会被系统性高估 —— 这是本数据集相对爬虫类源的结构性优势。
+    """
+    return _store().symbols(market, type=type, status=status, board=board,
+                            include_indices=include_indices)
+
+
+def symbol(code: str, market: str | None = None) -> dict:
+    """查单个标的的清单条目。"""
+    return _store().symbol(code, market=market)
+
+
+def calendar(market: str, start: int | str | None = None,
+             end: int | str | None = None) -> list[int]:
+    """交易日历（升序 `YYYYMMDD`）。权威区间只到今天，不承诺未来。
+
+    `start` / `end` 接受 `20260918` 或 `"2026-09-18"`。
+    """
+    return _store().calendar(market, start=start, end=end)
+
+
+def daily(code: str, start: int | str | None = None, end: int | str | None = None,
+          market: str | None = None, refresh: bool = False) -> Bars:
+    """股票日线（跨月自动拼接）。
+
+    `start` / `end` 接受 `20260918` 或 `"2026-09-18"`；非法形态抛 `DateError`。
+    """
+    return _store().daily(code, start=start, end=end, market=market, refresh=refresh)
+
+
+def index_daily(code: str, start: int | str | None = None, end: int | str | None = None,
+                market: str | None = None, refresh: bool = False) -> Bars:
+    """指数日线（独立命名空间，不与个股混装）。"""
+    return _store().index_daily(code, start=start, end=end, market=market,
+                                refresh=refresh)
+
+
+def daily_many(codes, start: int | str | None = None, end: int | str | None = None,
+               market: str | None = None, namespace: str = "stock",
+               refresh: bool = False) -> dict[str, Bars]:
+    """批量取多个标的时间序列。**回测请优先用这个** —— 每个分片只装载一次。"""
+    return _store().daily_many(codes, start=start, end=end, market=market,
+                               namespace=namespace, refresh=refresh)
+
+
+def cross_section(market: str, date: int | str, sort_by: str = "amount",
+                  limit: int | None = None, ascending: bool = False,
+                  namespace: str = "stock") -> list[dict]:
+    """某一交易日的全市场截面，默认按成交额降序。
+
+    `date` 接受 `20260918` 或 `"2026-09-18"`。
+    """
+    return _store().cross_section(market, date, sort_by=sort_by, limit=limit,
+                                  ascending=ascending, namespace=namespace)
+
+
+def snapshot() -> str:
+    """当前快照 id。记下它 = 记下这次读取的确切输入，随时可复现。"""
+    return _store().snapshot
+
+
+def coverage(market: str) -> dict:
+    """该市场的覆盖度声明。`complete=False` 表示这份数据明确知道自己是残缺的。"""
+    return _store().coverage(market)
+
+
+def coverage_note(market: str) -> str:
+    return _store().coverage_note(market)
+
+
+# ── 复权视图 ────────────────────────────────────────────────────────────
+
+def adjust(obj, to: str = "qfq"):
+    """把不复权数据换算成复权**视图**。`to` ∈ {`"none"`, `"hfq"`, `"qfq"`}。
+
+    接受 `Bars` 或 pandas DataFrame（后者需含 `af` 列与 `open/high/low/close`）。
+
+        qfq_i = price_i × af_i / af_latest     （锚点 = 最后一个有数据的交易日）
+        hfq_i = price_i × af_i / af_scale      （锚点 = 上市首日，af=1）
+
+    **`af_latest` 取「该标的最后一个有数据的交易日的因子」，不是「当前日期的因子」**
+    —— 停牌期间不产生新因子。
+
+    港美 V1 没有官方因子源（`af_basis="unavailable"`），此时请求复权**会抛
+    `NotSupported`**，而不是退回未复权数据：宁可报错，不给不可信的数字。
+    """
+    if to not in ADJUSTMENTS:
+        raise ValueError(f"to={to!r} 不支持，合法值 {ADJUSTMENTS}")
+    if isinstance(obj, Bars):
+        return _adjust_bars(obj, to)
+    return _adjust_frame(obj, to)
+
+
+def _adjust_bars(bars: Bars, to: str) -> Bars:
+    if to == "none":
+        return bars
+    if not bars.has_factor or bars.af is None:
+        raise NotSupported(
+            f"{bars.symbol}: af_basis={bars.af_basis!r}，该市场没有官方复权因子，"
+            f"无法给出可信的 {to} 视图（SPEC.md §9.5）")
+    af_latest = next((x for x in reversed(bars.af) if x is not None), None)
+    scale = bars.af_scale or 1
+    out = Bars(
+        symbol=bars.symbol, market=bars.market, namespace=bars.namespace,
+        price_scale=bars.price_scale, currency=bars.currency,
+        volume_unit=bars.volume_unit, af_basis=bars.af_basis,
+        af_scale=bars.af_scale, source=bars.source, adjust=to,
+        d=list(bars.d), v=list(bars.v), a=list(bars.a), af=list(bars.af),
+    )
+    for name in ("o", "h", "l", "c"):
+        setattr(out, name,
+                apply_adjust(getattr(bars, name), bars.af, scale, af_latest, to))
+    return out
+
+
+def _adjust_frame(df, to: str):
+    """DataFrame 版本：直接乘因子比例。
+
+    约定 `af` 列是**已归一的因子**（即 `Bars.to_pandas()` 产出的形态：
+    上市首日为 1.0），而不是盘上的定点整数。于是：
+
+        hfq: ratio = af            （锚点 = 上市首日）
+        qfq: ratio = af / af_last  （锚点 = 最后一个有值的因子）
+    """
+    if to == "none":
+        return df.copy()
+    if "af" not in df.columns:
+        raise NotSupported(
+            "DataFrame 缺少 'af' 列 —— 该市场没有官方复权因子，"
+            "无法给出可信的复权视图（SPEC.md §9.5）")
+    af = df["af"]
+    if af.isna().all():
+        raise NotSupported("'af' 列全为空，无法复权")
+    ratio = af if to == "hfq" else af / af.dropna().iloc[-1]
+    out = df.copy()
+    for col in ("open", "high", "low", "close"):
+        if col in out.columns:
+            out[col] = out[col] * ratio
+    return out

ohlcvault/adjust.py

@@ -0,0 +1,61 @@
+"""复权视图 = 纯函数（SPEC.md §9.2）。
+
+**这是本数据集的第一原则的落地点：只存事实，不存视图。**
+
+复权价不是事实，是「相对于某个锚点重算出来的视图」。前复权的锚点是**最新价**，
+所以每次分红送转都会导致**全历史价格被重算** —— 若把前复权价存进静态文件，
+历史文件就会天天变，`immutable` 缓存全部失效，整套免费分发的收益归零。
+
+因此：盘上只存不复权原始价 + 官方后复权累计因子 `af`，
+前/后复权都在客户端由下面这两个纯函数算出来。
+
+    后复权 hfq_i = c_i × af_i / af_scale      （锚点 = 上市首日，af=1）
+    前复权 qfq_i = c_i × af_i / af_latest     （锚点 = 最后一个有数据的交易日）
+
+**全部用整数运算**（`price_scale` 与 `af_scale` 都是整数标度）。
+引入浮点会让同一份数据在不同实现/架构上产生不同的末位，破坏可复现性 ——
+这与「数据集里不放浮点数」是同一条纪律。
+"""
+from __future__ import annotations
+
+from .errors import NotSupported
+
+ADJUSTMENTS = ("none", "hfq", "qfq")
+
+
+def _div_round(num: int, den: int) -> int:
+    """整数除法，四舍五入（half-up）。只用整数，结果与平台无关。"""
+    return (2 * num + den) // (2 * den)
+
+
+def adjust_factor(af: int, af_scale: int, af_latest: int | None, to: str) -> float:
+    """给定某日的因子，返回该日价格的乘数（浮点，仅供外部参考）。"""
+    if to == "hfq":
+        return af / af_scale
+    if to == "qfq":
+        if not af_latest:
+            raise NotSupported("qfq 需要 af_latest，但序列没有可用因子")
+        return af / af_latest
+    return 1.0
+
+
+def apply_adjust(
+    values: list[int],
+    af: list[int],
+    af_scale: int,
+    af_latest: int | None,
+    to: str,
+) -> list[int]:
+    """把一组定点整数价格按因子换算成复权视图，仍返回同标度的定点整数。
+
+    `to="none"` 原样返回。`af` 与 `values` 必须等长（契约 §4.2 硬性约束 1）。
+    """
+    if to == "none":
+        return list(values)
+    if to == "hfq":
+        return [_div_round(v * f, af_scale) for v, f in zip(values, af)]
+    if to == "qfq":
+        if not af_latest:
+            raise NotSupported("qfq 需要 af_latest，但序列没有可用因子")
+        return [_div_round(v * f, af_latest) for v, f in zip(values, af)]
+    raise ValueError(f"未知复权类型 {to!r}，合法值 {ADJUSTMENTS}")

ohlcvault/client.py

@@ -0,0 +1,203 @@
+"""传输层：多镜像读取 + sha256 校验 + 内容寻址本地缓存。
+
+这是「数据一定能用」的全部实现：
+
+1. 任意一个镜像可达 → 数据拿得到
+2. sha256 与快照清单不符 → 该镜像的这份数据被丢弃并降级到下一个
+   （**绝不把脏数据交给调用方** —— 这是校验存在的唯一理由）
+3. 全部镜像不可达 → 从本地缓存取（已拉过的数据永久可用，可离线复现）
+4. 缓存有效性由清单里的 sha256 决定，**不靠时间戳** —— 内容寻址的威力所在
+
+两种模式：
+
+- floating（默认）读 `latest.json`，跟随最新快照
+- pinned 指定快照 id，冻结历史状态，用于复现研究
+
+镜像可以是 http(s) URL，也可以是本地目录（便于离线测试）。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+import urllib.request
+from pathlib import Path
+
+from .errors import HashMismatch, SnapshotUnavailable  # noqa: F401  （对外保留此名）
+
+CHUNK = 1 << 20
+
+
+def sha256_bytes(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+
+def sha256_file(path: str | Path) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(CHUNK), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+class MarketClient:
+    """读一个内容寻址的快照数据服务。"""
+
+    def __init__(
+        self,
+        mirrors: list[str],
+        cache_dir: str | Path,
+        snapshot: str | None = None,
+        timeout: int = 15,
+    ):
+        if not mirrors:
+            raise ValueError("至少需要一个镜像")
+        self.mirrors = [str(m).rstrip("/") for m in mirrors]
+        self.cache = Path(cache_dir)
+        self.cache.mkdir(parents=True, exist_ok=True)
+        self.pinned = snapshot
+        self.timeout = timeout
+        self.trace: list[str] = []
+        self.stats: dict = {
+            "net": 0, "cache_hit": 0, "hash_reject": 0, "mirror_fail": 0,
+            "served_by": {}, "offline": False,
+        }
+        self._mf: dict | None = None
+        self._sid: str | None = None
+        self._lock = threading.Lock()
+
+    # ---------- 底层 IO ----------
+
+    @staticmethod
+    def _label(m: str) -> str:
+        return m.rsplit("/", 2)[-2] if m.startswith("http") else Path(m).name
+
+    def _fetch_raw(self, m: str, rel: str) -> bytes:
+        if m.startswith("http"):
+            self.stats["net"] += 1
+            with urllib.request.urlopen(f"{m}/{rel}", timeout=self.timeout) as r:
+                return r.read()
+        p = Path(m) / rel
+        if not p.is_file():
+            raise FileNotFoundError(rel)
+        return p.read_bytes()
+
+    def _promote(self, m: str) -> None:
+        """故障转移记忆：成功过的镜像提到首选位，后续请求不再重复探测死镜像。"""
+        if self.mirrors and self.mirrors[0] != m:
+            self.mirrors.remove(m)
+            self.mirrors.insert(0, m)
+            self.trace.append(f"    亲和切换 → {self._label(m)} 提为首选镜像")
+
+    def _read(self, rel: str) -> bytes:
+        """按镜像顺序取一个相对路径，任一成功即返回。"""
+        for m in list(self.mirrors):
+            label = self._label(m)
+            try:
+                body = self._fetch_raw(m, rel)
+            except Exception as e:
+                self.stats["mirror_fail"] += 1
+                self.trace.append(f"    镜像 {label} 不可达（{type(e).__name__}）")
+                continue
+            self.stats["served_by"][label] = self.stats["served_by"].get(label, 0) + 1
+            self.trace.append(f"    镜像 {label} 命中 → {rel}")
+            self._promote(m)
+            return body
+        raise SnapshotUnavailable(f"全部镜像均不可达: {rel}")
+
+    def _manifest_cache_file(self) -> Path:
+        return self.cache / "_manifest.json"
+
+    # ---------- 快照解析 ----------
+
+    def manifest(self, refresh: bool = False) -> dict:
+        with self._lock:
+            if self._mf is not None and not refresh:
+                return self._mf
+
+            want = self.pinned
+            rel = f"snapshots/{want}/manifest.json" if want else "latest.json"
+            try:
+                idx = json.loads(self._read(rel))
+                sid = idx["snapshot"]
+                if rel != f"snapshots/{sid}/manifest.json":
+                    mf = json.loads(self._read(f"snapshots/{sid}/manifest.json"))
+                else:
+                    mf = idx
+                self._mf, self._sid = mf, sid
+                self._manifest_cache_file().write_bytes(json.dumps(mf).encode())
+                return mf
+            except SnapshotUnavailable:
+                cached = self._manifest_cache_file()
+                if cached.is_file():
+                    mf = json.loads(cached.read_bytes())
+                    self._mf, self._sid = mf, mf["snapshot"]
+                    self.stats["offline"] = True
+                    self.trace.append(
+                        f"    全部镜像失败 → 使用本地缓存清单（快照 {self._sid}）")
+                    return mf
+                raise SnapshotUnavailable(
+                    "无镜像可达，且本地无缓存清单 —— 首次使用需联网") from None
+
+    @property
+    def snapshot(self) -> str:
+        if self._mf is None:
+            self.manifest()
+        return self._sid  # type: ignore[return-value]
+
+    def files(self) -> list[str]:
+        """本快照包含的全部相对路径（排序后）。"""
+        return sorted(self.manifest()["files"])
+
+    # ---------- 取数 ----------
+
+    def raw(self, rel: str, refresh: bool = False) -> bytes:
+        """取一个文件的**原始字节**（已通过 sha256 校验）。
+
+        调用方若要自己解压/解析就用这个 —— 校验的对象始终是传输中的字节，
+        不是解压后的明文。这个区别很重要：若分发端错误地设了
+        `Content-Encoding: gzip`，客户端拿到的就是被自动解压过的明文，
+        哈希必然对不上，表现为「数据被篡改」的假警报（SPEC.md §3.3）。
+        """
+        mf = self.manifest(refresh=refresh)
+        meta = mf["files"].get(rel)
+        if meta is None:
+            raise KeyError(f"快照中不存在: {rel}")
+        want_hash = meta["sha256"]
+        cache_file = self.cache / self.snapshot / rel
+
+        # 1) 本地缓存 —— 有效性由 hash 决定，与时间无关
+        if cache_file.is_file() and sha256_file(cache_file) == want_hash:
+            self.stats["cache_hit"] += 1
+            self.trace.append(f"    本地缓存命中（hash 一致）→ {rel}")
+            return cache_file.read_bytes()
+
+        # 2) 逐镜像请求 + 逐镜像校验
+        for m in list(self.mirrors):
+            label = self._label(m)
+            try:
+                body = self._fetch_raw(m, rel)
+            except Exception as e:
+                self.stats["mirror_fail"] += 1
+                self.trace.append(f"    镜像 {label} 不可达（{type(e).__name__}）")
+                continue
+
+            if sha256_bytes(body) != want_hash:
+                self.stats["hash_reject"] += 1
+                self.trace.append(f"    镜像 {label} 内容与清单不符 → 拒绝，继续降级")
+                continue
+
+            self.stats["served_by"][label] = self.stats["served_by"].get(label, 0) + 1
+            self.trace.append(f"    镜像 {label} 取回并通过校验 → {rel}")
+            cache_file.parent.mkdir(parents=True, exist_ok=True)
+            cache_file.write_bytes(body)
+            self._promote(m)
+            return body
+
+        raise SnapshotUnavailable(
+            f"{rel}: 无可信来源（镜像全部不可达或校验失败，"
+            f"已拒绝 {self.stats['hash_reject']} 份脏数据）")
+
+    def get(self, rel: str, refresh: bool = False) -> dict:
+        """取一个明文 JSON 文件。"""
+        return json.loads(self.raw(rel, refresh=refresh))

ohlcvault/codes.py

@@ -0,0 +1,127 @@
+"""证券代码双轨规范（SPEC.md §2）。
+
+| 场合 | 形态 |
+|---|---|
+| 存储层（文件、清单、路径） | 前缀式小写 `sh.600519` / `us.AAPL` |
+| 对外 API（入参、返回值） | 后缀式大写 `600519.SH` / `AAPL.US` |
+
+**模块名叫 `codes` 而不是 `symbols`**：包门面里有一个同名的
+`ohlcvault.symbols(market=...)` 函数（返回标的清单），
+同名模块与同名函数在 `__init__` 里必然互相遮蔽，改掉模块名是最省事的解法。
+顶层已把常用函数直接导出（`ov.to_api` / `ov.to_storage` / `ov.normalize_symbol`），
+所以使用者通常不需要直接导入本模块。
+
+**用户永远不需要记规则。** 本模块接受任意常见写法并归一化；但遇到
+真正有歧义的输入（如裸 `000001`，沪市是上证指数、深市是平安银行）
+**必须报错而非猜测** —— 猜错一个交易所，拿回来的是一份看起来完全正常的
+错误数据，比报错危险得多。
+"""
+from __future__ import annotations
+
+from .errors import SymbolError
+
+# 交易所代码（SPEC.md §2.2）
+EXCHANGES = ("sh", "sz", "bj", "hk", "us")
+
+MARKET_EXCHANGES: dict[str, tuple[str, ...]] = {
+    "cn": ("sh", "sz", "bj"),
+    "hk": ("hk",),
+    "us": ("us",),
+}
+
+# 仅当 market 上下文已知时可推断交易所的市场（SPEC.md §2.4 的例外）
+_CONTEXT_INFERABLE = {"hk": "hk", "us": "us"}
+
+
+def to_api(storage: str) -> str:
+    """存储式 → API 式。`sh.600519` → `600519.SH`，`us.AAPL` → `AAPL.US`。"""
+    ex, code = storage.split(".", 1)
+    return f"{code.upper() if ex == 'us' else code}.{ex.upper()}"
+
+
+def to_storage(api: str) -> str:
+    """API 式 → 存储式。`600519.SH` → `sh.600519`，`AAPL.US` → `us.AAPL`。
+
+    美股代码在存储层是**大写**（SPEC.md §2.1），所以 `aapl.us` 也要归一成 `us.AAPL`。
+    """
+    code, ex = api.rsplit(".", 1)
+    exl = ex.lower()
+    if exl not in EXCHANGES:
+        raise SymbolError(f"无法识别的交易所后缀：{api!r}（合法值 {EXCHANGES}）")
+    return f"{exl}.{code.upper() if exl == 'us' else code}"
+
+
+def normalize(raw: str, market: str | None = None) -> str:
+    """把用户可能写出的任意形态归一化为**存储式**（SPEC.md §2.4）。
+
+    >>> normalize("600519.SH")
+    'sh.600519'
+    >>> normalize("sh600519")
+    'sh.600519'
+    >>> normalize("00700.HK")
+    'hk.00700'
+    >>> normalize("AAPL")
+    Traceback (most recent call last):
+    ...
+    ohlcvault.errors.SymbolError: ...
+
+    `market` 只在 `hk` / `us` 下提供消歧能力（这两个市场各只有一家交易所）；
+    对 `cn` 提供 `market="cn"` 也**不会**让裸 `000001` 通过 —— 它分属沪深两市。
+    """
+    if not isinstance(raw, str):
+        raise SymbolError(f"symbol 必须是字符串，收到 {type(raw).__name__}")
+    s = raw.strip()
+    if not s:
+        raise SymbolError("空的 symbol")
+
+    low = s.lower()
+
+    # ① 前缀式：sh.600519 / sh600519
+    for ex in EXCHANGES:
+        if low.startswith(ex + "."):
+            return _canonical(ex, s[len(ex) + 1:], raw)
+        if low.startswith(ex) and "." not in s and low[len(ex):].isalnum():
+            return _canonical(ex, s[len(ex):], raw)
+
+    # ② 后缀式：600519.SH
+    if "." in s:
+        code, ex = s.rsplit(".", 1)
+        exl = ex.lower()
+        if exl in EXCHANGES:
+            return _canonical(exl, code, raw)
+        raise SymbolError(f"无法识别的交易所后缀：{raw!r}（合法值 {EXCHANGES}）")
+
+    # ③ 裸代码：仅在市场上下文唯一确定交易所时才允许
+    infer = _CONTEXT_INFERABLE.get(market or "")
+    if infer:
+        return _canonical(infer, s, raw)
+
+    raise SymbolError(
+        f"symbol 缺少交易所信息：{raw!r}。请写成 '600519.SH' 或 'sh.600519'。"
+        f"（契约禁止猜测交易所 —— 000001 在沪市是上证指数、深市是平安银行）"
+    )
+
+
+def _canonical(exchange: str, code: str, raw: str) -> str:
+    if not code:
+        raise SymbolError(f"symbol 缺少代码部分：{raw!r}")
+    # 港股代码必须零填充到 5 位（港交所规范，也是 akshare / yfinance 的共同要求）
+    if exchange == "hk":
+        code = code.zfill(5)
+    code = code.upper() if exchange == "us" else code
+    return f"{exchange}.{code}"
+
+
+def split(storage: str) -> tuple[str, str]:
+    """存储式 → (交易所小写, 代码)。"""
+    ex, code = storage.split(".", 1)
+    return ex, code
+
+
+def market_of(storage: str) -> str:
+    """存储式 → 市场代码。"""
+    ex = storage.split(".", 1)[0]
+    for mkt, exs in MARKET_EXCHANGES.items():
+        if ex in exs:
+            return mkt
+    raise SymbolError(f"未知交易所：{storage!r}")