メインコンテンツへスキップ
見出し画像

【競馬AI開発 #02】JV-Link(64bit)の取得層:PCが2回固まってから作り直した設計

    JRA-VAN からデータを取る部分の話です。この記事のコードは、記事の最後に全文を置きます。
    ここは勝ち負けに直結しない層ですし、64bit の JV-Link を Python から叩く実装例って本当に少ないので、
    私が踏んだ地雷ごと置いていきます。同じところで泣く人が減りますように。

    前提:JRA-VAN Data Lab. の契約、64bit 版 JV-Link、Python 3.10(64bit)、pywin32。
    仕様書(JV-Data 仕様書)は SDK に付いてきます。仕様書そのものと、そこから作った定義ファイルは本記事に含めません。


    1. 取得の口は2つある

    ◆ JVOpen(蓄積系)
    ・過去のレース・馬・調教・血統など。まとめて落ちてくる
    ・使いどころ:学習用のデータをそろえる

    ◆ JVRTOpen(速報系)
    ・1レース分を1回で取る。時系列オッズもこちら
    ・使いどころ:過去の途中経過オッズ、開催日の当日運用

    最初にここを間違えると「欲しいデータが取れない」になります。私は過去の時系列オッズを `JVOpen` で探して時間を溶かしました。

    `JVOpen` には option があり、1 = 差分(前回の続きから)、**4 = セットアップ(全期間)**です。
    戻り値は4つ組で返ってきます。

    code, read_count, download_count, last_file_timestamp = jv.JVOpen(dataspec, fromtime, option, 0, 0, "")

    この `last_file_timestamp` が後で効きます(→ 5章)。

    2. 生成は「遅延バインド」で

    def _default_factory():
        import pythoncom  # COM の初期化を確実にする
        import win32com.client.dynamic
        # 早期バインドの gen_py キャッシュで引数の受け渡しが変わった事例があるため、遅延バインドにする
        return win32com.client.dynamic.Dispatch("JVDTLab.JVLink")

    `win32com.client.gencache` を使うと、環境によって多値の戻り値の受け取り方が変わることがあります。
    `dynamic.Dispatch` に固定してしまうのが安全でした。

    `JVInit` に渡す sid は、仕様書で開発中の既定値とされている `"UNKNOWN"` を使っています。

    3. 地雷その1:`JVGets` に確保済みバッファを渡してはいけない

    ここが一番の落とし穴でした。 素直に書くと、こうしたくなりますよね。

    buf = bytearray(200000)          # ← これをやると死ぬ
    rc, data, fname = jv.JVGets(buf, 200000, bytearray())

    これで数百万回まわすと、確保と解放が積み重なって、PCごと固まります。
    私は2回やりました。1回目は原因がまったく分からず、ただ「競馬AIを作ろうとしてPCを殺した人」になりました。

    正解は、第1引数に空の `bytearray()` を渡すことです。サイズは第2引数だけで伝わります。

    GETS_SIZE = 200000   # 最大のレコード(H6 票数6)は 102,890 バイト
    
    def _gets(self) -> tuple[int, bytes, str]:
        ret = self._jv.JVGets(bytearray(), GETS_SIZE, bytearray())
        rc = int(ret[0])
        payload = ret[1] if len(ret) > 1 else None
        fname = str(ret[2]) if len(ret) > 2 and ret[2] else ""
        data = b""
        if rc > 0:
            raw = payload.tobytes() if hasattr(payload, "tobytes") else bytes(payload)
            data = strip_terminator(raw)     # 行末の \r\n\x00 を3つまとめて落とす
            if not data:
                raise JvError(f"JVGets が {rc} を返しましたがデータが空です", rc, fname)
        return rc, data, fname

    行末は `\r\n\x00` の3バイトです。`rstrip()` で雑に落とすと、データ側の空白まで削れることがあるので、
    終端記号として3つまとめて落とします。

    4. 地雷その2:`-1` は2つの意味を持つ

    ◆ JVOpen / JVRTOpen の戻り値の場合
    ・-1 =「該当データ無し」(エラーではない)

    ◆ JVGets / JVRead の戻り値の場合
    ・-1 =「ファイルの切り替わり」(エラーではない。読み続ける)

    さらに紛らわしいのが `-111`(dataspec が不正)です。`-1` と `-111` を取り違えて
    「0件のまま正常終了」と記録してしまい、空っぽのデータで平然と学習を始めたことがあります。
    何も入っていないのに、プログラムは元気に動くんですよね。

    対策は単純で、コードの分類表を1枚作って、そこを通さない値は「完了」にしないことです。

    class Outcome(Enum):
        OK = "ok"; NO_DATA = "no_data"; RETRYABLE = "retryable"; FATAL = "fatal"; UNKNOWN = "unknown"
    
    OPEN_CODES: dict[int, tuple[Outcome, str]] = {
        0:    (Outcome.OK,        "正常終了"),
        -1:   (Outcome.NO_DATA,   "該当データ無し"),
        -111: (Outcome.FATAL,     "dataspec パラメータが不正"),
        -116: (Outcome.FATAL,     "dataspec と option の組み合わせが不正"),
        -202: (Outcome.FATAL,     "前回の Open に対して JVClose が呼ばれていない"),
        -301: (Outcome.FATAL,     "認証エラー(利用キーが正しくない、または複数マシンで同一キーを使用)"),
        -411: (Outcome.RETRYABLE, "サーバーエラー(HTTP 404)"),
        -502: (Outcome.RETRYABLE, "ダウンロード失敗(通信エラーやディスクエラーなど)"),
        -504: (Outcome.RETRYABLE, "サーバーメンテナンス中"),
        # ……仕様書のコード表を全部並べる
    }
    
    def classify(code: int, table=OPEN_CODES) -> tuple[Outcome, str]:
        return table.get(code, (Outcome.UNKNOWN, f"未分類のコード {code}"))

    表に無いコードは `UNKNOWN`。呼び出し側は UNKNOWN を絶対に「完了」にしない。
    これだけで「黙って0件」は起きなくなりました。読み出し側の表(`-3` ダウンロード中、`-402` ファイル異常など)も別に持っています。

    def iter_records(self):
        while True:
            rc, data, fname = self._gets()
            if rc > 0:
                yield data;  continue
            if rc == 0:      return          # 全部読み終わり
            if rc == -1:     continue        # ファイルの切り替わり。読み続ける
            if rc == -3:                     # ダウンロード中。待つ(待ちすぎたら例外)
                ...
            raise JvError(...)               # それ以外はエラーにして止める

    `JVOpen` の結果が何であれ、最後は必ず `JVClose`。 閉じ忘れると、次の `JVOpen` が `-202` で返ってきます。

    5. 地雷その3:ファイルを何十本も同時に開かない

    蓄積系のレコードは、種別ごとに分けて保存したくなります。私は最初、約40本のファイルを開きっぱなしで追記しました。
    「開いておけば速いでしょ」と思って。

    結果、PCが2回フリーズしました。(この記事、フリーズの話が多いですね……。)

    今はこうしています。

    ① 取ったレコードは、いったんメモリの辞書に溜める(宛先ごとのリスト)
    ② 64MB 溜まったら、ファイルを1本ずつ開いて、まとめて書いて、閉じる

    さらに「途中で止まったとき」に備えて、ユニット方式にしました。

    ユニット = 1回の `JVOpen` で取った分。書いている間は `<名前>.part`、
    最後に `_unit.json`(件数・`lastfiletimestamp`・ファイルごとの行数)を置いてから `<名前>` に改名する。

    def commit(self, meta: UnitMeta) -> None:
        self.flush()
        meta.files = {f"{k}.txt": v for k, v in sorted(self.counts.items())}
        (self.part_dir / "_unit.json").write_text(json.dumps(asdict(meta), ensure_ascii=False, indent=1),
                                                  encoding="utf-8")
        for attempt in range(5):
            try:
                self.part_dir.rename(self.final_dir)   # 改名できた ⇔ 完了
                return
            except PermissionError:                    # ウイルス対策ソフトが一瞬掴むことがある
                if attempt == 4: raise
                time.sleep(1.0)

    利点は、**「改名されたディレクトリがある ⇔ そのユニットは完了」**が成り立つことです。
    状態ファイルと実物が食い違いません。途中で止まったら `.part` が残るだけなので、次回の開始時に消してやり直します。
    「状態JSONに進捗を書いて、途中まで書いたファイルをサイズで巻き戻す」方式(前に自分が書いたもの)より、考えることがずっと減りました。

    6. 大きい種別は「1年ずつ」取る

    レース情報のような大きい種別を全期間まとめて取ると、いつまでも終わらない状態になります。
    提供時期を1年ずつに区切って `JVOpen` を呼び、取れた行は開催年ごとのファイルに振り分けて保存します。
    区切りは `[前年12/31 23:59:59, 当年12/31 23:59:59]`、最新の年だけ終了日を付けません。

    種別ごとのクセもあります(仕様書と実測より)。

    ・差分(option=1)で取れない種別がある(コース情報・データマイニング予想。`-116` が返る)
    ・終了時刻を指定できない種別がある(指定すると `-1`)
    ・特別登録は、セットアップでは当週・翌週しか取れないので、過去分を option=1 で別に取る

    7. 差分の開始時刻は「時計」ではなく `lastfiletimestamp`

    毎週の差分で「前回いつまで取ったか」を実行時刻で持つと、取りこぼします。
    正解は、`JVOpen` が返した `lastfiletimestamp` を覚えておいて、次回の `fromtime` にすることです。

    私は「その種別の完了ユニットの `lastfiletimestamp` の最大値」を使っています。
    セットアップのユニットが1つも無い種別は、差分を取らずにエラーにします。 黙って1986年から取り直し始めると、
    気づかないまま何時間も走るからです。

    8. 取ったら必ず数え直す

    取得が終わったら、その場で検算します。

    ・`_unit.json` に書いた行数と、実ファイルの行数が一致するか
    ・全行のレコード長が、仕様書の長さと一致するか(1行でも違えば止める)
    ・前回取得した分と、過去の件数が一致するか

    実際、生ファイル約4,000万行を数えて、仕様と長さが違う行は0件でした。

    **「たぶん大丈夫」ではなく「数えたら0件だった」**まで持っていくと、後の工程で疑う場所が1つ減ります。
    このあと私は「疑う場所を減らす」ことに、ものすごく時間を使うことになります(第2部)。

    実績(2026-09-14、私の環境)

    ◆ 蓄積系セットアップ(12種別・1986年〜)
    ・全種別完了・約20分・27.6GB・ユニット93
    ・全行が仕様の長さ
    ・うち「データ無しで確定」18ユニット(提供のない年)

    ◆ 時系列オッズ(2003-10-04〜)
    ・79,713 レース・5時間53分・28.5GB
    ・失敗0件

    ※ 約20分で終わったのは JV-Link のキャッシュが効いていたためで、初回はもっとかかります。
    ※ 時系列オッズの「該当データ無し」296件は、すべてレース中止でした(確認済み)。

    今回で手元にできるもの

    ・JV-Link を安全に叩く薄いラッパ(分類表つき)
    ・途中で止めても続きから再開できる取得の仕組み
    ・生ファイル(cp932 のまま、1レコード1行)

    この層のソースは、記事の一番下にフォルダ構成つきで全文を置いてあります
    (ランチャの PS1、取得する種別の一覧、取得の本体、JV-Link の包み、ユニット方式、ロック)。
    そのまま動かせる形なので、使えそうなら持っていってください。

    次回:#03「数千項目の仕様書から、テーブル定義を1か所で作る」。
    Excel の仕様書を読んで PostgreSQL の CREATE TABLE を自動生成し、同じ定義で切り出しと検証までやる話です。


    付録:取得層のソース全文(64bit 版)

    本文で抜粋したところを含めて、JV-Link を叩いてデータを落とすところを丸ごと置いておきます。
    すべて私が書いたものです。JV-Link SDK 同梱のサンプルコードや仕様書は含みません。

    フォルダの構成

    (プロジェクトのルート)
    ├─ pipeline\                     ダブルクリックで動かすランチャ(PowerShell)
    │   ├─ 000_データダウンロード.ps1     ← 今回の主役。蓄積系の取得
    │   ├─ 001_DB定義作成.ps1            仕様書 → テーブル定義(#03)
    │   ├─ 002_データインポート.ps1       生ファイル → PostgreSQL(#04)
    │   ├─ 010_時系列オッズダウンロード.ps1  (#05)
    │   └─ 011_時系列オッズインポート.ps1
    ├─ src\keiba\                    本体
    │   ├─ common\                   パス・ログ・設定の読み込み
    │   ├─ jvdata\                   JV-Data の仕様:レイアウト定義、レコードの切り出し
    │   ├─ jvlink\                   JV-Link(COM)の包みと、戻り値の分類
    │   ├─ acquire\                  取得(蓄積系 stored.py / 時系列オッズ ts_odds.py)
    │   └─ dbload\                   DB 定義の作成と、取り込み
    ├─ specs\                        仕様書から生成した定義(公開しません)
    ├─ tests\                        単体テスト
    └─ data\                         取得したファイル・状態・ログ(Git 管理外)
        ├─ jv_raw\setup\{種別}\        セットアップで取った生ファイル
        ├─ jv_raw\diff\{実行日時}\     差分で取った生ファイル(消さない)
        └─ state\log\                ログ

    ランチャを pipeline フォルダ に、中身を src\keiba フォルダ に分けているのは、
    「ダブルクリックするもの」と「コードを直すもの」を混ぜないためです。
    PS1 は UTF-8 BOM + CRLF で保存しないと、Windows PowerShell 5.1 で日本語が化けます(ここでハマりました)。

    動かし方

    pipeline\000_データダウンロード.ps1 をダブルクリック
      → モード 1 = セットアップ(全期間。初回だけ。長時間かかる)
      → モード 2 = 差分(普段使い)

    途中で止めても、もう一度実行すれば続きから始まります(完了したユニットはやり直しません)。

    前提と、ここに載せていないもの

    ・必要なライブラリは pywin32 だけです。
    ・`keiba.common` の中身は載せていません。使っているのは次の小さな関数だけなので、読み替えてください。
     ・`ensure_dir(path)` … 無ければ作る
     ・`ensure_writable(path)` … 書き込み先がプロジェクトの外なら例外で止める(事故防止)
     ・`SETUP_DIR` / `DIFF_DIR` / `STATE_DIR` … 上のフォルダ構成のパス
     ・`setup_logger(...)` … 画面とファイルの両方に出すログ
     ・`hms(秒)` / `human_bytes(n)` … 「1時間18分29秒」「27.6 GB」の整形
     ・`prevent_sleep()` … 長時間の取得中に PC を寝かせない
    ・`jvdata/layout.py`(仕様書から作った定義を読む部分)も載せていません。
     `stored.py` からは `record_year()`(1行から開催年を読む)だけ使っています。

    そのまま動かす前に:JRA-VAN Data Lab. の契約と、64bit 版 JV-Link の利用キー設定が要ります。
    取得したデータは再配布できません。ご自身の責任でお使いください(無保証です)。

    `000_データダウンロード.ps1` — ダブルクリックで動かすランチャ

    # JRA-VAN 蓄積系データのダウンロード(JVOpen)
    #   モード 1: セットアップ(全期間。初回のみ。長時間かかる)
    #   モード 2: 差分(普段使い)
    # 引数でモードを渡すこともできる:  .\000_データダウンロード.ps1 2
    #
    # 保存先は data\jv_raw\setup / data\jv_raw\diff\{実行日時}。
    # 差分のファイルは消さない(どこまで DB に入れたかは取込台帳で管理するので、二重取込にはならない)。
    
    Write-Host "=========================================" -ForegroundColor Cyan
    Write-Host " JRA-VAN 蓄積系データのダウンロード" -ForegroundColor Yellow
    Write-Host "=========================================" -ForegroundColor Cyan
    
    # プロジェクトの場所は、このスクリプト自身の位置から求める。
    $Root = Split-Path -Parent $PSScriptRoot
    Set-Location -Path $Root
    $env:PYTHONPATH = Join-Path $Root "src"
    
    py -3.10 -m keiba.acquire.stored @args
    $code = $LASTEXITCODE
    
    Write-Host "=========================================" -ForegroundColor Cyan
    if ($code -eq 0) {
        Write-Host " 正常に終了しました。" -ForegroundColor Green
    } else {
        Write-Host " エラーまたは未完了で終了しました(終了コード $code)。ログ: data\state\log" -ForegroundColor Red
    }
    Write-Host "=========================================" -ForegroundColor Cyan
    Read-Host "Enterキーを押して終了してください..."
    exit $code

    `acquire/catalog.py` — 取得する種別と、その性質(差分で取れるか・終了時刻を付けられるか・1年ずつ区切るか)

    """取得する蓄積系データ種別(dataspec)とその性質。
    
    出典: JV-Link インターフェース仕様書 4.9.0.1「option パラメータと dataspec の組み合わせ」、
          JRA-VAN Data Lab. 開発ガイド 4.2.3。
    
    旧レイアウトの4種別(DIFF・BLOD・SNAP・HOSE)は、2023年8月に新種別(DIFN・BLDN・SNPN・HOSN)へ
    置き換わって提供が終わっている。桁数が違うので新しい位置では切れず、内容は新種別に含まれるため取得しない。
    """
    from __future__ import annotations
    
    from dataclasses import dataclass
    
    # セットアップの開始時刻。
    START_FROMTIME = "19860101000000"
    START_YEAR = 1986
    
    OPTION_NORMAL = 1   # 通常データ(差分)
    OPTION_SETUP = 4    # セットアップ(ダイアログは初回のみ)
    
    
    @dataclass(frozen=True)
    class Spec:
        name: str
        diff: bool       # option=1(差分)で取れるか。COMM・MING は取れない(-116)
        end_time: bool   # fromtime に終了時刻を付けられるか。付けられない種別に付けると -1 が返り、欠損に気づけない
        yearly: bool     # 提供時期で区切って取得するか(大きい種別)
    
    
    SPECS: tuple[Spec, ...] = (
        Spec("TOKU", diff=True, end_time=False, yearly=False),
        Spec("RACE", diff=True, end_time=True, yearly=True),
        Spec("SLOP", diff=True, end_time=True, yearly=False),
        Spec("WOOD", diff=True, end_time=True, yearly=False),
        Spec("YSCH", diff=True, end_time=True, yearly=False),
        Spec("HOYU", diff=True, end_time=False, yearly=False),
        Spec("COMM", diff=False, end_time=False, yearly=False),
        Spec("MING", diff=False, end_time=True, yearly=False),
        Spec("DIFN", diff=True, end_time=False, yearly=False),
        Spec("BLDN", diff=True, end_time=True, yearly=False),
        Spec("SNPN", diff=True, end_time=True, yearly=True),
        Spec("HOSN", diff=True, end_time=False, yearly=False),
    )
    
    # TOKU はセットアップ(option=4)では当週・翌週の分しか取れない。過去分は option=1 で別に取る。
    TOKU_PAST_UNIT = "TOKU_normal"
    
    
    def year_fromtime(year: int, end_year: int) -> str:
        """提供時期の区切り(1年分)の fromtime。
    
        区切り同士を隙間なくつなぐため [前年12/31 23:59:59, 当年12/31 23:59:59] とし、
        最新の年だけは終了時刻を付けない(開発ガイド:セットアップの最後は必ず終了日なしで取得する)。
        """
        begin = START_FROMTIME if year == START_YEAR else f"{year - 1}1231235959"
        if year >= end_year:
            return begin
        return f"{begin}-{year}1231235959"
    
    
    def is_closed(fromtime: str) -> bool:
        return "-" in fromtime

    `acquire/stored.py` — 蓄積系の取得の本体。ここが入口(`-m keiba.acquire.stored`)

    """蓄積系データの取得(1: セットアップ / 2: 差分)。
    
        py -3.10 -m keiba.acquire.stored [1|2]      引数を省くとメニューを出す
    
    保存先(すべて data\\jv_raw\\ の下):
        setup\\{種別}\\{種別}.txt                   一括で取る種別
        setup\\{種別}\\p{提供年}\\{種別}_{開催年}.txt   提供時期で区切る種別(RACE・SNPN)
        setup\\TOKU_normal\\TOKU_normal.txt          TOKU の過去分(option=1)
        diff\\{実行日時}\\{種別}\\{種別}.txt           差分
    
    各ディレクトリの `_unit.json` に件数と lastfiletimestamp を残す。
    差分の開始時刻は、前回までに JVOpen が返した lastfiletimestamp の最大値(実行した時刻ではない)。
    """
    from __future__ import annotations
    
    import logging
    import sys
    from collections.abc import Callable
    from datetime import datetime
    from pathlib import Path
    
    from keiba.acquire.catalog import (
        OPTION_NORMAL,
        OPTION_SETUP,
        SPECS,
        START_FROMTIME,
        START_YEAR,
        TOKU_PAST_UNIT,
        Spec,
        is_closed,
        year_fromtime,
    )
    from keiba.acquire.lock import LockError, run_lock
    from keiba.acquire.units import UnitMeta, UnitWriter, iter_units, remove_tree
    from keiba.common.log import hms, prevent_sleep, setup_logger
    from keiba.common.paths import DIFF_DIR, SETUP_DIR, ensure_dir
    from keiba.jvdata.record import record_year
    from keiba.jvlink.client import JvBrokenFile, JvError, JVLinkClient
    from keiba.jvlink.codes import Outcome
    
    # 「該当データ無し」のときの扱い
    ON_EMPTY_DONE = "done_empty"      # 閉じた期間:データ無しで確定させる
    ON_EMPTY_RETRY = "retry"          # 次回また問い合わせる(何も残さない)
    ON_EMPTY_IF_TS = "record_if_ts"   # 差分:lastfiletimestamp が返っていれば記録する
    
    PROGRESS_INTERVAL = 20.0
    
    
    class StoredRunner:
        def __init__(self, jv: JVLinkClient, log: logging.Logger,
                     setup_dir: Path = SETUP_DIR, diff_dir: Path = DIFF_DIR,
                     now: Callable[[], datetime] = datetime.now):
            self.jv = jv
            self.log = log
            self.setup_dir = setup_dir
            self.diff_dir = diff_dir
            self.now = now
    
        # ------------------------------------------------------------ 1ユニット
        def fetch_unit(self, spec: str, fromtime: str, option: int, final_dir: Path,
                       file_stem: Callable[[bytes], str], on_empty: str) -> UnitMeta | None:
            """1回の JVOpen で取れる分を1ユニットとして書く。完了しなければ None。"""
            label = f"[{final_dir.parent.name}/{final_dir.name}]"
            ensure_dir(final_dir.parent)
            writer = UnitWriter(final_dir, self.log)
            writer.begin()
            try:
                self.log.info("%s JVOpen(%s, %s, option=%d) 問い合わせ中…(数十秒応答しないことがあります)",
                              label, spec, fromtime, option)
                r = self.jv.open(spec, fromtime, option)
                if r.outcome not in (Outcome.OK, Outcome.NO_DATA):
                    raise JvError(f"{label} JVOpen が失敗しました({r.code}: {r.message})", r.code)
    
                meta = UnitMeta(spec=spec, option=option, fromtime=fromtime, status="", records=0,
                                code=r.code, last_file_timestamp=r.last_file_timestamp)
    
                if r.outcome is Outcome.NO_DATA or r.read_count == 0:
                    self.jv.close()
                    return self._finish_empty(writer, meta, on_empty, label)
    
                self.log.info("%s 対象 %d ファイル / 要ダウンロード %d / last=%s",
                              label, r.read_count, r.download_count, r.last_file_timestamp)
                self.jv.wait_download(r.download_count)
                t0 = last = self.now().timestamp()
                for data in self.jv.iter_records():
                    writer.write(file_stem(data), data)
                    now = self.now().timestamp()
                    if now - last >= PROGRESS_INTERVAL:
                        self.log.info("%s 読み出し中 %s件(%s)", label, f"{writer.records:,}", hms(now - t0))
                        last = now
                self.jv.close()
    
                if writer.records == 0:
                    # ファイルはあるのにレコードが0件。原因が分からないので完了にしない。
                    self.log.warning("%s 0件でした。完了にせず、次回また取得します。", label)
                    writer.abort()
                    return None
    
                meta.status, meta.records = "done", writer.records
                writer.commit(meta)
                self.log.info("%s 完了 %s件  %s", label, f"{meta.records:,}",
                              ", ".join(f"{k}:{v:,}" for k, v in list(meta.files.items())[:6])
                              + (" …" if len(meta.files) > 6 else ""))
                return meta
            except JvBrokenFile as e:
                # 仕様書の対処:壊れたファイルを JVFiledelete で消し、JVOpen からやり直す(次回の実行で)。
                writer.abort()
                self.jv.close()
                if e.filename:
                    self.jv.delete_file(e.filename)
                raise
            except BaseException:
                writer.abort()
                self.jv.close()
                raise
    
        def _finish_empty(self, writer: UnitWriter, meta: UnitMeta, on_empty: str, label: str) -> UnitMeta | None:
            if on_empty == ON_EMPTY_DONE:
                meta.status = "done_empty"
                writer.commit(meta)
                self.log.info("%s 該当データ無し(閉じた期間なので、データ無しで確定)", label)
                return meta
            if on_empty == ON_EMPTY_IF_TS and meta.last_file_timestamp:
                meta.status = "empty"
                writer.commit(meta)
                self.log.info("%s 新しいデータ無し(last=%s を記録)", label, meta.last_file_timestamp)
                return meta
            writer.abort()
            self.log.warning("%s 該当データ無し。完了にせず、次回また問い合わせます。", label)
            return None
    
        # ------------------------------------------------------------ セットアップ
        def run_setup(self) -> bool:
            end_year = self.now().year
            incomplete: list[str] = []
            for spec in SPECS:
                self.log.info("")
                self.log.info("==================== %s ====================", spec.name)
                if spec.yearly:
                    ok = self._setup_yearly(spec, end_year)
                else:
                    ok = self._setup_single(spec.name, self.setup_dir / spec.name, OPTION_SETUP)
                    if spec.name == "TOKU":
                        # セットアップでは当週・翌週の分しか取れないので、過去分を通常データで取る。
                        ok = self._setup_single("TOKU", self.setup_dir / TOKU_PAST_UNIT, OPTION_NORMAL) and ok
                if not ok:
                    incomplete.append(spec.name)
    
            self.log.info("")
            if incomplete:
                self.log.warning("セットアップ未完了の種別: %s(再実行すると続きから取得します)", incomplete)
                return False
            self.log.info("セットアップ完了(全 %d 種別)", len(SPECS))
            return True
    
        def _setup_single(self, spec: str, final_dir: Path, option: int) -> bool:
            if final_dir.exists():
                self.log.info("[%s] 完了済みのためスキップ", final_dir.name)
                return True
            meta = self.fetch_unit(spec, START_FROMTIME, option, final_dir,
                                   lambda _d: final_dir.name, ON_EMPTY_RETRY)
            return meta is not None
    
        def _setup_yearly(self, spec: Spec, end_year: int) -> bool:
            base = self.setup_dir / spec.name
            years = list(range(end_year, START_YEAR - 1, -1))   # 新しい提供年から
            done = [y for y in years if (base / f"p{y}").exists()]
            if done:
                self.log.info("[%s] 完了済みの提供年: %d 年分をスキップ", spec.name, len(done))
            ok = True
    
            def stem(data: bytes) -> str:
                y = record_year(data)
                return f"{spec.name}_{y if y is not None else 'unknown'}"
    
            for year in years:
                final_dir = base / f"p{year}"
                if final_dir.exists():
                    continue
                fromtime = year_fromtime(year, end_year)
                on_empty = ON_EMPTY_DONE if is_closed(fromtime) else ON_EMPTY_RETRY
                if self.fetch_unit(spec.name, fromtime, OPTION_SETUP, final_dir, stem, on_empty) is None:
                    ok = False
            return ok
    
        # ------------------------------------------------------------ 差分
        def baseline(self, spec: str) -> str | None:
            """差分の開始時刻。これまでに JVOpen が返した lastfiletimestamp の最大値。
    
            セットアップが1ユニットも無い種別は None(全期間の取り直しを黙って始めないため)。
            TOKU は option=4 のユニットを使わない(当週・翌週しか含まず、通常データの続きではないため)。
            """
            setup_units = [m for _, m in iter_units(self.setup_dir) if m.spec == spec]
            if not setup_units:
                return None
            diff_units = [m for _, m in iter_units(self.diff_dir) if m.spec == spec]
            stamps = [
                m.last_file_timestamp for m in setup_units + diff_units
                if m.last_file_timestamp.isdigit() and len(m.last_file_timestamp) == 14
                and not (spec == "TOKU" and m.option == OPTION_SETUP)
            ]
            return max(stamps) if stamps else None
    
        def run_diff(self) -> bool:
            run_dir = self.diff_dir / self.now().strftime("%Y%m%d_%H%M%S")
            ok = True
            for spec in SPECS:
                if not spec.diff:
                    self.log.info("[%s] 差分(option=1)では取れない種別のためスキップ(セットアップでのみ取得)", spec.name)
                    continue
                fromtime = self.baseline(spec.name)
                if fromtime is None:
                    self.log.error("[%s] セットアップの記録が無いため差分を取れません。先にセットアップを実行してください。",
                                   spec.name)
                    ok = False
                    continue
                final_dir = run_dir / spec.name
                self.fetch_unit(spec.name, fromtime, OPTION_NORMAL, final_dir, lambda _d, s=spec.name: s, ON_EMPTY_IF_TS)
            if run_dir.exists() and not any(run_dir.iterdir()):
                remove_tree(run_dir)
            self.log.info("差分の保存先: %s", run_dir)
            return ok
    
    
    def main(argv: list[str] | None = None) -> int:
        argv = sys.argv[1:] if argv is None else argv
        mode = argv[0] if argv and argv[0] in ("1", "2") else ""
        while mode not in ("1", "2"):
            mode = input(
                "\n--- モード選択 ---\n"
                "  1: セットアップ取得(全期間 / option=4)※初回のみ。長時間かかります\n"
                "  2: 差分取得        (option=1)※普段使い\n"
                "番号: "
            ).strip()
    
        log = setup_logger("acquire_setup" if mode == "1" else "acquire_diff")
        try:
            with run_lock():
                jv = JVLinkClient(log)
                jv.connect()
                log.info("JV-Link 接続成功")
                runner = StoredRunner(jv, log)
                try:
                    with prevent_sleep(log):
                        ok = runner.run_setup() if mode == "1" else runner.run_diff()
                finally:
                    jv.release()
        except (JvError, LockError) as e:
            log.error("%s", e)
            log.error("中断しました。完了していない分は、再実行すると取得し直します。")
            return 1
        except KeyboardInterrupt:
            log.warning("ユーザー操作で中断しました。完了していない分は、再実行すると取得し直します。")
            return 1
        return 0 if ok else 1
    
    
    if __name__ == "__main__":
        sys.exit(main())

    `acquire/units.py` — ユニット方式の書き出し(`.part` → 改名で確定)

    """取得の単位(ユニット)を、ディレクトリ1つとして書き出す。
    
    ユニット=「1回の JVOpen で取った分」。書き終わるまでは `<名前>.part` に書き、
    最後に `_unit.json`(件数や lastfiletimestamp)を置いてから `<名前>` へ改名する。
    
    - 改名されたディレクトリがある ⇔ そのユニットは完了している(状態ファイルと実物が食い違わない)
    - 途中で止まったら `.part` が残るだけで、次回の開始時に消してやり直す
    - 取込は完了したユニットの *.txt だけを読む
    
    書き込みはメモリに溜めてから、ファイルを1本ずつ開いてまとめて書く。
    振り分け先のファイルを何十本も同時に開いたまま追記すると、PC 全体が固まった実例があるため。
    """
    from __future__ import annotations
    
    import json
    import logging
    import shutil
    import time
    from collections.abc import Iterator
    from dataclasses import asdict, dataclass, field
    from datetime import datetime
    from pathlib import Path
    
    from keiba.common.log import human_bytes
    from keiba.common.paths import ensure_dir, ensure_writable
    
    UNIT_META = "_unit.json"
    PART_SUFFIX = ".part"
    FLUSH_BYTES = 64 * 1024 * 1024
    
    
    class UnitError(Exception):
        pass
    
    
    @dataclass
    class UnitMeta:
        spec: str
        option: int
        fromtime: str
        status: str                 # "done"(1件以上)/ "done_empty"(閉じた期間で該当なし)/ "empty"(差分で新規なし)
        records: int
        code: int
        last_file_timestamp: str
        files: dict[str, int] = field(default_factory=dict)   # ファイル名 → 行数
        at: str = field(default_factory=lambda: datetime.now().strftime("%Y%m%d%H%M%S"))
    
    
    def read_meta(unit_dir: Path) -> UnitMeta:
        return UnitMeta(**json.loads((unit_dir / UNIT_META).read_text(encoding="utf-8")))
    
    
    def iter_units(root: Path) -> Iterator[tuple[Path, UnitMeta]]:
        """root 以下の完了済みユニットを返す(書きかけの .part の中は見ない)。"""
        if not root.exists():
            return
        for meta_path in sorted(root.rglob(UNIT_META)):
            unit_dir = meta_path.parent
            if any(p.name.endswith(PART_SUFFIX) for p in [unit_dir, *unit_dir.parents]):
                continue
            yield unit_dir, read_meta(unit_dir)
    
    
    def remove_tree(path: Path) -> None:
        ensure_writable(path)
        shutil.rmtree(path)
    
    
    class UnitWriter:
        def __init__(self, final_dir: Path, log: logging.Logger):
            self.final_dir = final_dir
            self.part_dir = final_dir.with_name(final_dir.name + PART_SUFFIX)
            self.log = log
            self._buf: dict[str, list[bytes]] = {}
            self._buf_bytes = 0
            self.counts: dict[str, int] = {}
    
        def begin(self) -> None:
            if self.final_dir.exists():
                raise UnitError(f"既に完了済みのユニットがあります: {self.final_dir}")
            if self.part_dir.exists():
                self.log.warning("前回の書きかけを削除します: %s", self.part_dir.name)
                remove_tree(self.part_dir)
            ensure_dir(self.part_dir)
    
        def write(self, file_stem: str, data: bytes) -> None:
            buf = self._buf.setdefault(file_stem, [])
            buf.append(data)
            buf.append(b"\n")
            self._buf_bytes += len(data) + 1
            self.counts[file_stem] = self.counts.get(file_stem, 0) + 1
            if self._buf_bytes >= FLUSH_BYTES:
                self.flush()
    
        def flush(self) -> None:
            if not self._buf_bytes:
                return
            total = self._buf_bytes
            for stem in sorted(self._buf):
                parts = self._buf[stem]
                if not parts:
                    continue
                path = ensure_writable(self.part_dir / f"{stem}.txt")
                with open(path, "ab") as f:
                    f.write(b"".join(parts))
                parts.clear()
            self._buf_bytes = 0
            self.log.debug("  書き出し %s", human_bytes(total))
    
        @property
        def records(self) -> int:
            return sum(self.counts.values())
    
        def commit(self, meta: UnitMeta) -> None:
            self.flush()
            meta.files = {f"{k}.txt": v for k, v in sorted(self.counts.items())}
            (self.part_dir / UNIT_META).write_text(
                json.dumps(asdict(meta), ensure_ascii=False, indent=1), encoding="utf-8"
            )
            # ウイルス対策ソフトなどが一瞬ファイルを掴んでいると改名に失敗することがあるので、少し待って再試行する。
            for attempt in range(5):
                try:
                    self.part_dir.rename(self.final_dir)
                    return
                except PermissionError:
                    if attempt == 4:
                        raise
                    time.sleep(1.0)
    
        def abort(self) -> None:
            self._buf.clear()
            self._buf_bytes = 0
            if self.part_dir.exists():
                remove_tree(self.part_dir)

    `acquire/lock.py` — JV-Link を同時に2つ動かさないためのロック

    """JV-Link を使う取得を、同時に1つしか動かさないためのロック。"""
    from __future__ import annotations
    
    import os
    from collections.abc import Iterator
    from contextlib import contextmanager
    from datetime import datetime
    from pathlib import Path
    
    from keiba.common.paths import STATE_DIR, ensure_dir
    
    
    class LockError(Exception):
        pass
    
    
    @contextmanager
    def run_lock(name: str = "jvlink", state_dir: Path = STATE_DIR) -> Iterator[None]:
        ensure_dir(state_dir)
        path = state_dir / f"{name}.lock"
        try:
            fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
        except FileExistsError as e:
            info = path.read_text(encoding="utf-8", errors="replace").strip()
            raise LockError(
                f"別の取得が実行中です({path}: {info})。\n"
                f"  実行中でないのに残っている場合は、このファイルを削除してから再実行してください。"
            ) from e
        os.write(fd, f"pid={os.getpid()} started={datetime.now():%Y-%m-%d %H:%M:%S}".encode())
        os.close(fd)
        try:
            yield
        finally:
            path.unlink(missing_ok=True)

    `jvlink/client.py` — JV-Link(COM)の薄い包み

    """JV-Link(COM)の薄い包み。
    
    何を取るか・どこへ書くかはここでは決めない(keiba.acquire の責務)。
    COM オブジェクトは外から差し替えられるようにしてあり、テストでは偽物を渡す。
    
    呼び出しの形(64bit JV-Link Ver.5.0.0 + pywin32 で確認されている形):
        JVInit(sid)                                   -> int
        JVOpen(dataspec, fromtime, option, 0, 0, "")  -> (code, readcount, downloadcount, lastfiletimestamp)
        JVStatus()                                    -> int(ダウンロード済みファイル数、負ならエラー)
        JVGets(bytearray(), 200000, bytearray())      -> (rc, data, filename)
        JVRTOpen(dataspec, key)                       -> int
        JVClose() / JVFiledelete(filename)
    """
    from __future__ import annotations
    
    import logging
    import sys
    import time
    from collections.abc import Callable, Iterator
    from dataclasses import dataclass
    from typing import Any
    
    from keiba.jvdata.record import strip_terminator
    from keiba.jvlink.codes import (
        BROKEN_FILE_CODES,
        READ_CODES,
        READ_DOWNLOADING,
        READ_EOF,
        READ_FILE_SWITCH,
        STATUS_CODES,
        Outcome,
        classify,
    )
    
    PROG_ID = "JVDTLab.JVLink"
    # 仕様書で開発中の既定値とされている sid。
    DEFAULT_SID = "UNKNOWN"
    
    # JVGets に渡すサイズ。最大のレコード(H6 票数6)は 102,890 バイト。
    # 第1引数には空の bytearray を渡す。サイズ分を確保した bytearray を毎回渡すと、
    # 数百万回の呼び出しで確保と解放が積み重なり、PC のフリーズや異常終了が起きた実例がある。
    GETS_SIZE = 200000
    
    
    class JvError(Exception):
        def __init__(self, message: str, code: int | None = None, filename: str = ""):
            super().__init__(message)
            self.code = code
            self.filename = filename
    
    
    class JvStalled(JvError):
        """ダウンロードが一定時間まったく進まなかった。"""
    
    
    class JvBrokenFile(JvError):
        """ダウンロード済みファイルが壊れている(-402/-403)。filename に対象ファイル名が入る。"""
    
    
    @dataclass(frozen=True)
    class OpenResult:
        outcome: Outcome
        code: int
        read_count: int
        download_count: int
        last_file_timestamp: str
        message: str
    
    
    def _default_factory() -> Any:
        import pythoncom  # noqa: F401  (COM の初期化を確実にする)
        import win32com.client.dynamic
    
        # 遅延バインド。早期バインドの gen_py キャッシュで引数の受け渡しが変わった事例があるため。
        return win32com.client.dynamic.Dispatch(PROG_ID)
    
    
    class JVLinkClient:
        def __init__(
            self,
            log: logging.Logger,
            factory: Callable[[], Any] = _default_factory,
            sid: str = DEFAULT_SID,
            sleep: Callable[[float], None] = time.sleep,
        ):
            self.log = log
            self._factory = factory
            self._sid = sid
            self._sleep = sleep
            self._jv: Any = None
            self._opened = False
    
        # ------------------------------------------------------------ 接続
        def connect(self) -> None:
            if sys.maxsize <= 2**32:
                self.log.warning("32bit の Python で動いています。64bit の JV-Link を前提にしています。")
            try:
                self._jv = self._factory()
            except Exception as e:
                raise JvError(f"JV-Link({PROG_ID})を生成できません: {e}") from e
            code = int(self._jv.JVInit(self._sid))
            if code != 0:
                raise JvError(f"JVInit が失敗しました({code}: {classify(code)[1]})", code)
    
        def reconnect(self, wait: float = 1.0) -> None:
            """COM を作り直す。長時間の連続呼び出しで JV-Link が不安定になるのを避けるため。"""
            self.close()
            self._jv = None
            self._sleep(wait)
            self.connect()
    
        def release(self) -> None:
            self.close()
            self._jv = None
    
        def close(self) -> None:
            if self._jv is not None and self._opened:
                try:
                    self._jv.JVClose()
                except Exception as e:  # 閉じる失敗は後続の Open で -202 として現れる
                    self.log.debug("JVClose で例外: %s", e)
            self._opened = False
    
        # ------------------------------------------------------------ 蓄積系
        def _open_once(self, dataspec: str, fromtime: str, option: int) -> OpenResult:
            res = self._jv.JVOpen(dataspec, fromtime, option, 0, 0, "")
            self._opened = True
            if isinstance(res, (list, tuple)):
                code = int(res[0])
                read_count = int(res[1] or 0) if len(res) > 1 else 0
                download_count = int(res[2] or 0) if len(res) > 2 else 0
                last_ts = str(res[3] or "").strip() if len(res) > 3 else ""
            else:
                code, read_count, download_count, last_ts = int(res), 0, 0, ""
            outcome, message = classify(code)
            return OpenResult(outcome, code, read_count, download_count, last_ts, message)
    
        def open(self, dataspec: str, fromtime: str, option: int,
                 max_retry: int = 5, base_wait: float = 10.0) -> OpenResult:
            """JVOpen を呼ぶ。再試行できるエラーは待ち時間を倍にしながら繰り返す。
    
            戻り値が OK / NO_DATA 以外なら、呼び出し側は完了にせず止めること。
            """
            attempt = 0
            while True:
                attempt += 1
                try:
                    r = self._open_once(dataspec, fromtime, option)
                except Exception as e:
                    r = OpenResult(Outcome.UNKNOWN, -9999, 0, 0, "", f"JVOpen で例外: {e}")
                self.log.debug("JVOpen(%s, %s, %d) -> %d %s read=%d dl=%d last=%s", dataspec, fromtime, option,
                               r.code, r.message, r.read_count, r.download_count, r.last_file_timestamp)
                if r.outcome in (Outcome.OK, Outcome.NO_DATA) or r.outcome is Outcome.FATAL or attempt > max_retry:
                    return r
                wait = base_wait * (2 ** (attempt - 1))
                self.log.warning("JVOpen(%s) %d(%s)→ %.0f秒待って再試行(%d/%d)",
                                 dataspec, r.code, r.message, wait, attempt, max_retry)
                self.close()
                self._sleep(wait)
    
        def wait_download(self, need: int, stall_timeout: float = 600.0, report_interval: float = 30.0,
                          poll: float = 0.5, clock: Callable[[], float] = time.time) -> None:
            """JVStatus がダウンロード対象数に届くまで待つ。進まない時間が続いたら JvStalled。"""
            if need <= 0:
                return
            last_value, last_change, last_report = -1, clock(), 0.0
            while True:
                cur = int(self._jv.JVStatus())
                if cur < 0:
                    raise JvError(f"JVStatus エラー({cur}: {classify(cur, STATUS_CODES)[1]})", cur)
                if cur >= need:
                    self.log.info("  ダウンロード完了 %d/%d", cur, need)
                    return
                now = clock()
                if cur != last_value:
                    last_value, last_change = cur, now
                if now - last_change > stall_timeout:
                    raise JvStalled(f"ダウンロードが {stall_timeout:.0f} 秒間進みませんでした({cur}/{need})", cur)
                if now - last_report >= report_interval:
                    self.log.info("  ダウンロード中 %d/%d", cur, need)
                    last_report = now
                self._sleep(poll)
    
        def _gets(self) -> tuple[int, bytes, str]:
            ret = self._jv.JVGets(bytearray(), GETS_SIZE, bytearray())
            if isinstance(ret, (list, tuple)):
                rc = int(ret[0])
                payload = ret[1] if len(ret) > 1 else None
                fname = str(ret[2]) if len(ret) > 2 and ret[2] else ""
            else:
                rc, payload, fname = int(ret), None, ""
            data = b""
            if rc > 0:
                if payload is None:
                    raise JvError(f"JVGets が {rc} を返しましたがデータがありません", rc, fname)
                raw = payload.tobytes() if hasattr(payload, "tobytes") else bytes(payload)
                data = strip_terminator(raw)
                if not data:
                    raise JvError(f"JVGets が {rc} を返しましたがデータが空です", rc, fname)
            return rc, data, fname
    
        def iter_records(self, max_wait: float = 300.0, wait_step: float = 0.5,
                         report_interval: float = 15.0) -> Iterator[bytes]:
            """開いているデータを1レコードずつ返す(終端記号は除去済み)。"""
            waited = 0.0
            last_report = 0.0
            filename = ""
            while True:
                rc, data, fname = self._gets()
                if fname:
                    filename = fname
                if rc > 0:
                    waited = 0.0
                    yield data
                    continue
                if rc == READ_EOF:
                    return
                if rc == READ_FILE_SWITCH:
                    waited = 0.0
                    continue
                if rc == READ_DOWNLOADING:
                    waited += wait_step
                    if waited > max_wait:
                        raise JvStalled(f"ファイルのダウンロードが {max_wait:.0f} 秒待っても終わりません", rc, filename)
                    if waited - last_report >= report_interval:
                        self.log.info("  ファイルのダウンロード待ち %.0f秒", waited)
                        last_report = waited
                    self._sleep(wait_step)
                    continue
                message = classify(rc, READ_CODES)[1]
                if rc in BROKEN_FILE_CODES:
                    raise JvBrokenFile(f"ダウンロード済みファイルが異常です({rc}: {message}){filename}", rc, filename)
                raise JvError(f"レコードの読み出しでエラー({rc}: {message})", rc, filename)
    
        def delete_file(self, filename: str) -> None:
            """壊れたファイルを JV-Link のキャッシュから消す(仕様書の対処手順)。通常のキャッシュは消さない。"""
            try:
                code = int(self._jv.JVFiledelete(filename))
                self.log.info("JVFiledelete(%s) -> %d", filename, code)
            except Exception as e:
                self.log.warning("JVFiledelete(%s) で例外: %s", filename, e)
    
        # ------------------------------------------------------------ 速報系
        def rt_fetch(self, dataspec: str, key: str) -> tuple[Outcome, int, list[bytes]]:
            """JVRTOpen で1件(1レース)分を読み切って閉じる。"""
            try:
                ret = self._jv.JVRTOpen(dataspec, key)
            except Exception as e:
                self.log.debug("JVRTOpen(%s, %s) で例外: %s", dataspec, key, e)
                return Outcome.UNKNOWN, -9999, []
            self._opened = True
            code = int(ret[0]) if isinstance(ret, (list, tuple)) else int(ret)
            outcome, _ = classify(code)
            if outcome is not Outcome.OK:
                self.close()
                return outcome, code, []
            try:
                rows = list(self.iter_records(max_wait=60.0, wait_step=0.1))
            except JvError as e:
                self.close()
                out = Outcome.FATAL if e.code in (-201, -202, -203) else Outcome.RETRYABLE
                return out, e.code if e.code is not None else -9999, []
            except Exception as e:
                self.log.debug("JVRTOpen(%s, %s) の読み出しで例外: %s", dataspec, key, e)
                self.close()
                return Outcome.UNKNOWN, -9999, []
            self.close()
            return Outcome.OK, 0, rows

    `jvlink/codes.py` — 戻り値の分類表

    """JV-Link の戻り値の分類。
    
    出典: JV-Link インターフェース仕様書 4.9.0.1(Win)「コード表」。
    表に無いコードは UNKNOWN とし、呼び出し側は「完了」にしないこと。
    
    特に取り違えやすいもの:
        -1   JVOpen / JVRTOpen では「該当データ無し」(エラーではない)
        -111 dataspec パラメータが不正(エラー)
        -1   JVGets / JVRead では「ファイルの切り替わり」(エラーではない。読み続ける)
    """
    from __future__ import annotations
    
    from enum import Enum
    
    
    class Outcome(Enum):
        OK = "ok"
        NO_DATA = "no_data"
        RETRYABLE = "retryable"
        FATAL = "fatal"
        UNKNOWN = "unknown"
    
    
    OPEN_CODES: dict[int, tuple[Outcome, str]] = {
        0: (Outcome.OK, "正常終了"),
        -1: (Outcome.NO_DATA, "該当データ無し"),
        -2: (Outcome.FATAL, "セットアップダイアログでキャンセルが押された"),
        -111: (Outcome.FATAL, "dataspec パラメータが不正"),
        -112: (Outcome.FATAL, "fromtime パラメータが不正(開始ポイント)"),
        -113: (Outcome.FATAL, "fromtime パラメータが不正(終了ポイント)"),
        -114: (Outcome.FATAL, "key パラメータが不正"),
        -115: (Outcome.FATAL, "option パラメータが不正"),
        -116: (Outcome.FATAL, "dataspec と option の組み合わせが不正"),
        -201: (Outcome.FATAL, "JVInit が行われていない"),
        -202: (Outcome.FATAL, "前回の Open に対して JVClose が呼ばれていない"),
        -211: (Outcome.FATAL, "レジストリ内容が不正"),
        -301: (Outcome.FATAL, "認証エラー(利用キーが正しくない、または複数マシンで同一キーを使用)"),
        -302: (Outcome.FATAL, "利用キーの有効期限切れ"),
        -303: (Outcome.FATAL, "利用キーが設定されていない"),
        -305: (Outcome.FATAL, "利用規約に同意していない"),
        -401: (Outcome.FATAL, "JV-Link 内部エラー"),
        -411: (Outcome.RETRYABLE, "サーバーエラー(HTTP 404)"),
        -412: (Outcome.RETRYABLE, "サーバーエラー(HTTP 403)"),
        -413: (Outcome.RETRYABLE, "サーバーエラー(HTTP 200/403/404 以外)"),
        -421: (Outcome.RETRYABLE, "サーバーエラー(応答が不正)"),
        -431: (Outcome.RETRYABLE, "サーバーエラー(サーバーアプリケーション内部エラー)"),
        -501: (Outcome.FATAL, "セットアップ処理においてスタートキットが無効"),
        -502: (Outcome.RETRYABLE, "ダウンロード失敗(通信エラーやディスクエラーなど)"),
        -504: (Outcome.RETRYABLE, "サーバーメンテナンス中"),
    }
    
    STATUS_CODES: dict[int, tuple[Outcome, str]] = {
        -201: (Outcome.FATAL, "JVInit が行われていない"),
        -203: (Outcome.FATAL, "JVOpen が行われていない"),
        -502: (Outcome.RETRYABLE, "ダウンロード失敗(通信エラーやディスクエラーなど)"),
    }
    
    READ_CODES: dict[int, tuple[Outcome, str]] = {
        -3: (Outcome.RETRYABLE, "ファイルダウンロード中"),
        -201: (Outcome.FATAL, "JVInit が行われていない"),
        -202: (Outcome.FATAL, "前回の Open に対して JVClose が呼ばれていない"),
        -203: (Outcome.FATAL, "JVOpen が行われていない"),
        -402: (Outcome.RETRYABLE, "ダウンロードしたファイルが異常(ファイルサイズ=0)"),
        -403: (Outcome.RETRYABLE, "ダウンロードしたファイルが異常(データ内容)"),
        -502: (Outcome.RETRYABLE, "ダウンロード失敗(通信エラーやディスクエラーなど)"),
        -503: (Outcome.RETRYABLE, "ファイルが見つからない"),
    }
    
    READ_EOF = 0
    READ_FILE_SWITCH = -1
    READ_DOWNLOADING = -3
    BROKEN_FILE_CODES = (-402, -403)
    
    
    def classify(code: int, table: dict[int, tuple[Outcome, str]] = OPEN_CODES) -> tuple[Outcome, str]:
        return table.get(code, (Outcome.UNKNOWN, f"未分類のコード {code}"))

    `jvdata/record.py` — 固定長レコードの終端処理・長さ検査

    """固定長レコード(cp932 のバイト列)の切り出し。"""
    from __future__ import annotations
    
    from keiba.jvdata.layout import RecordLayout
    
    # JV-Data には NEC/IBM 拡張文字が実在し、shift_jis では化けるため cp932 で読む。
    ENCODING = "cp932"
    REPLACEMENT_CHAR = chr(0xFFFD)
    
    
    class RecordError(Exception):
        """レコードが仕様と合わない。"""
    
    
    def strip_terminator(data: bytes) -> bytes:
        """行末の CR・LF・NUL を落とす。
    
        JVGets の戻りは「本体 + CR/LF + NUL」の形になっている。CR/LF だけ落とすと NUL が残り、
        NUL だけの行が混ざる。本体は空白で埋められていて NUL では埋められないので、本体は欠けない。
        """
        return data.rstrip(b"\x00\r\n")
    
    
    def record_type(data: bytes) -> str:
        return data[:2].decode("ascii", "replace")
    
    
    def record_year(data: bytes) -> int | None:
        """レース系レコードの開催年(11〜15バイト目)を返す。読めなければ None。
    
        [0:2] レコード種別 / [2:3] データ区分 / [3:11] データ作成年月日 / [11:15] 開催年。
        この並びはレースキーを持つレコード(RACE・SNPN の各種別)でだけ成り立つ。
        """
        text = data[11:15].decode("ascii", "replace")
        if not text.isdigit():
            return None
        year = int(text)
        return year if 1900 <= year <= 2100 else None
    
    
    def check_length(data: bytes, layout: RecordLayout) -> None:
        if len(data) != layout.data_length:
            raise RecordError(
                f"{layout.record_type} のレコード長が {len(data)} バイトです(仕様は {layout.data_length} バイト)"
            )
    
    
    def parse_record(data: bytes, layout: RecordLayout) -> tuple[list[object], int]:
        """1レコードを (値のリスト, 文字化けの数) に切り分ける。
    
        値のリストの先頭は行全体(raw_text)、以降は layout.fields の順。
        各値は前後の空白(全角空白を含む)を落とす。固定長のパディングのため。
        """
        raw = data.decode(ENCODING, "replace")
        values: list[object] = [raw]
        for f in layout.fields:
            if f.repeat > 1:
                values.append([
                    data[f.start + i * f.size: f.start + (i + 1) * f.size].decode(ENCODING, "replace").strip()
                    for i in range(f.repeat)
                ])
            else:
                values.append(data[f.start: f.start + f.size].decode(ENCODING, "replace").strip())
        return values, raw.count(REPLACEMENT_CHAR)

    ※ 本記事は個人の開発記録です。馬券の的中や利益を保証するものではありません。
    ※ JRA-VAN Data Lab. の契約が必要です。取得したデータの再配布はできません。
    ※ 掲載しているコードは筆者が書いたものです。JV-Link SDK 同梱のサンプルコードや仕様書は含みません。
    ※ 各サービスの利用規約はご自身でご確認ください。

     
     
    競馬予想AIを、ひとりで作っているITエンジニアです。 JRA-VAN からのデータ取得、特徴量、モデル、開催日の自動予想、Discord通知、即PATでの購入まで、 その作り方の記録を置いています。 かわいいものとボンレス犬が好きです。 ※ 予想や買い目は販売していません。

    あなたへのおすすめ