棋譜管理（Record / GameResult / 棋譜入出力）

rsshogi.record は棋譜の読み込み、書き出し、手順ツリーの走査と編集、対局メタデータやエンジン解析情報の管理、およびバイナリ棋譜フォーマット（pack / sbinpack / PackedSfenValue）の変換を提供するモジュールである。

from rsshogi.record import (
    EngineInfo,
    GameResult,
    GameResultInfo,
    MoveEntry,
    Record,
    RecordBuilder,
    RecordEditor,
    RecordEntry,
    RecordMetadata,
    RecordMetadataBuilder,
    RecordMetadataKey,
    SpecialMoveEntry,
    TimeControl,
    decode_pack,
    decode_pack_file,
    decode_sbinpack,
    decode_sbinpack_file,
    write_pack,
    write_pack_file,
    write_sbinpack,
    write_sbinpack_file,
)

Record

Record(
    init_position_sfen: str,
    moves: Sequence[MoveEntry | Move32 | Move | int | str] | None = None,
    metadata: RecordMetadata | Mapping[str, Any] | None = None,
    terminal: SpecialMoveEntry | GameResult | int | str | None = None,
    initial_comment: str | None = None,
) -> Record

1 局分の棋譜全体（初期局面、開始局面コメント、本手順と変化手順のツリー、対局ヘッダ情報、終局結果）を保持するクラスである。 直接コンストラクタで生成できるほか、KIF、KI2、CSA、JKF、USI position、辞書、各種バイナリ形式から生成できる。

プロパティ

基本操作と編集メソッド

読み込み（クラスメソッド）

ファイル読み込みメソッドの encoding 引数は位置引数とキーワード引数のどちらでも指定できる。

Record.from_usi_main_line のシグネチャ

Record.from_usi_main_line(
    init_position_sfen: str,
    usi_moves: Sequence[str],
    result: SpecialMoveEntry | GameResult | int | str | None = None,
    move_times_ms: Sequence[int | None] | None = None,
    evals: Sequence[int | None] | None = None,
    nodes: Sequence[int | None] | None = None,
    depths: Sequence[int | None] | None = None,
    seldepths: Sequence[int | None] | None = None,
    wall_times_ms: Sequence[int | None] | None = None,
    latency_deltas_ms: Sequence[int | None] | None = None,
    metadata: RecordMetadata | Mapping[str, Any] | None = None,
    initial_comment: str | None = None,
) -> Record

init_position_sfen には SFEN 文字列または "startpos" を指定できる。 evals[i] は usi_moves[i] を指す前の局面における手番側視点のセンチポーン評価値である。 各テレメトリ配列を指定する場合は usi_moves と同じ長さで渡す。

書き出し（インスタンスメソッド）

棋譜フォーマット入出力の仕様と互換性

• KIF / KI2 の変化手順とコメント：
  • 変化手順と終局要約行が両方存在する場合、to_kif() および to_ki2() は変化ブロックを先に出力し、本手順の まで... 要約行を最後に出力する。
  • 連続する * コメント行は \n で連結され、直前の指し手の MoveEntry.comment（初手より前の場合は Record.initial_comment）に格納される。
• CSA 2.2 / 3.0 の仕様：
  • from_csa_str() / from_csa_file() は CSA 仕様に従い '* で始まる行を指し手コメントとして読み込み、単一の ' で始まる行は注釈として読み飛ばす。
  • '** <評価値> <読み筋> #<ノード数> 形式のエンジン評価行は、MoveEntry.engine_info の eval、nodes、および extras["csa_pv"] に格納され、to_csa() で再出力される。
  • to_csa(version="3.0") は先頭に 'CSA encoding=UTF-8 宣言を出力し、ミリ秒単位の端数がある消費時間を小数表記（例：T15.123）で出力する。write_csa(..., version="3.0") では指定した encoding（UTF-8 または Shift_JIS）に合わせてエンコーディング宣言を出力し、CSA が宣言できない文字コードが指定された場合は ValueError を送出する。

from rsshogi.core import Board
from rsshogi.record import Record

record = Record.from_usi_main_line(
    "startpos",
    ["7g7f", "3c3d", "2g2f"],
    evals=[30, -25, 40],
    move_times_ms=[1000, 1200, 800],
    result="WHITE_WIN",
)

print(record.move_count)  # => 3
print(record.result.name)  # => "WHITE_WIN"

# 盤面上で本手順を再生する
board = Board(record.init_position_sfen)
for entry in record.moves:
    board.apply_move(entry.move)

分岐（変化手順）の走査と RecordEditor

KIF、KI2、JKF、および sbinpack の変化手順を含む棋譜は、内部で木構造として保持される。 各ノードは整数型のノード ID（RecordNodeId = int）で識別される。

Record の木構造参照メソッド

RecordEntry

Record.node_entry(node_id) が返すノード要素のラッパークラスである。

RecordEditor

record.into_editor() で生成するカーソル付きの棋譜エディタである。 カーソル位置の盤面状態を内部で管理するため、追加する指し手の合法性を検証しながら分岐を構築できる。 編集完了後は into_record() で Record を取り出す（into_record() 呼び出し後のエディタに対する操作は ValueError を送出する）。

from rsshogi.record import Record

record = Record.from_usi_position("position startpos moves 7g7f 3c3d")
editor = record.into_editor()

# 1 手目（7g7f）の直後に戻って変化手順（8c8d）を追加する
editor.go_to_main_end()
editor.go_back()
variation_node_id = editor.append_move("8c8d", comment="飛車先を突く変化")
editor.append_move("2g2f")

edited_record = editor.into_record()
print(len(edited_record.children(edited_record.main_line_ids()[0])))  # => 2

辞書変換（from_dict / to_dict）と TypedDict 型

Record.from_dict(data, *, strict=False) と record.to_dict() は、JSON シリアライズや外部スキーマとの変換に適した辞書構造を扱う。 型ヒント用に RecordDict、RecordMetadataDict、MoveEntryDict、EngineInfoDict、TimeControlDict、GameResultInfoDict の 6 つの TypedDict が rsshogi.record から提供されている。

from_dict の入力スキーマ

• init_position_sfen（str、必須）：初期局面の SFEN 文字列。
• initial_comment（str | None、任意）：開始局面コメント。
• moves（Sequence[Mapping[str, Any]]、任意）：本手順の指し手リスト。各要素は以下のキーを持つ。
  • move（必須）：MoveEntry、Move32、Move、int（0..=65535 の 16 ビット Move 値、範囲外は ValueError）、または USI 文字列。各手は盤面上で合法性を検証する。
  • time_ms（int | None、任意）：消費時間（ミリ秒）。
  • comment（str | None、任意）：指し手コメント。
  • engine_info（Mapping[str, Any] | None、任意）：eval、depth、nodes、seldepth、extras（dict[str, str | int | float | bool]）を保持する辞書。
• result（Mapping[str, Any] | GameResult | int | str | None、任意）：終局情報。辞書を渡す場合は result キー（GameResult、数値コード、または名前文字列）が必須であり、任意で ply_count、reason、end_time_ms、end_comment を指定できる。
• metadata（Mapping[str, Any] | None、任意）：後述する RecordMetadata の各フィールドに対応する辞書。

strict モードと permissive モードの違い

• strict=False（既定）：metadata 内の未知キー（値が str または None のもの）を自動的に metadata.attributes に格納する。
• strict=True：トップレベル、moves[*]、result、metadata のいずれかに未知のキーが含まれている場合に ValueError を送出する。

RecordMetadata / RecordMetadataKey / TimeControl

RecordMetadata

RecordMetadata(
    event: str | None = None,
    site: str | None = None,
    black_player: str | None = None,
    white_player: str | None = None,
    game_name: str | None = None,
    game_type: str | None = None,
    time_control: TimeControl | str | None = None,
    black_time_control: TimeControl | str | None = None,
    white_time_control: TimeControl | str | None = None,
    max_moves: int | None = None,
    impasse_rule: str | None = None,
    start_date: str | None = None,
    end_date: str | None = None,
    updated_date: str | None = None,
    comment: str | None = None,
    attributes: Mapping[str, str] | None = None,
) -> RecordMetadata

KIF、KI2、CSA、JKF の対局ヘッダ情報を保持するクラスである。すべてのプロパティは読み書き可能であり、未設定時は None（attributes は空辞書 {}）となる。

attributes を個別に操作するメソッドとして set_attribute(key, value)、remove_attribute(key)、clear_attributes() を備える。

RecordMetadataKey

メタデータの正規キー文字列を定数としてまとめたクラスである。

TimeControl

TimeControl(base_seconds: int, byoyomi_seconds: int, increment_seconds: int) -> TimeControl

持ち時間、秒読み、1 手ごとの加算時間（フィッシャールール）を秒単位で保持するイミュータブルなクラスである。

MoveEntry / EngineInfo / SpecialMoveEntry

MoveEntry

MoveEntry(
    move: Move | Move32 | int | str,
    *,
    time_ms: int | None = None,
    comment: str | None = None,
    engine_info: EngineInfo | None = None,
) -> MoveEntry

棋譜内の 1 手分の情報（指し手、消費時間、コメント、エンジン解析情報）を保持するクラスである。 move には Move、Move32、int（0..=65535）、または USI 文字列を指定でき、内部では 16 ビットの Move として保持される。

EngineInfo

EngineInfo(
    eval: int | None = None,
    depth: int | None = None,
    nodes: int | None = None,
    seldepth: int | None = None,
    wall_time_ms: int | None = None,
    latency_delta_ms: int | None = None,
    extras: Mapping[str, str | int | float | bool] | None = None,
) -> EngineInfo

各指し手に紐づく将棋エンジンの探索情報を保持するクラスである。

SpecialMoveEntry

SpecialMoveEntry(
    kind: str,
    result: GameResult | int | str,
    unknown_name: str | None = None,
    comment: str | None = None,
    time_ms: int | None = None,
    raw: str | None = None,
) -> SpecialMoveEntry

SpecialMoveEntry.from_result(
    result: GameResult | int | str,
    time_ms: int | None = None,
    comment: str | None = None,
    raw: str | None = None,
) -> SpecialMoveEntry

投了、千日手、持将棋、入玉宣言勝ちなどの終局特殊手ノードを表すクラスである。 SpecialMoveEntry.from_result(...) を使うと、GameResult から対応する kind を自動導出して生成できる（GameResult.INVALID は終局状態ではないため ValueError を送出する）。

SpecialMoveEntry.kind の値一覧

GameResult と GameResultInfo

GameResult

GameResult(value: int) -> GameResult
GameResult.from_str(name: str) -> GameResult

対局の勝敗結果と決着理由を表す列挙ライクなイミュータブルクラスである。

Note

数値コードは 14 の次が 16、17 の次が 20 と飛び番になっている。全定数の辞書は GameResult.__members__ から参照できる。

裁定引き分けの保存

GameResult.DRAW_BY_ADJUDICATION は数値 14 の裁定引き分けである。 SpecialMoveEntry.from_result(...) はこれを kind == "DRAW" の終局特殊手に変換する。 保存形式によって、読み戻した結果が次のように変わる。

裁定理由の保持には SAZ2 v4、SBINPACK、または rsshogi の KIF / KI2 拡張表記を使う。 KIF / KI2 は終局特殊手の 裁定引分 と終局サマリーの まで○手で裁定引分 を DRAW_BY_ADJUDICATION として読み込む。 裁定引分 は KIF 形式の公式仕様に定義された終局表記ではない。 ShogiHome が使用する tsshogi 2.3.4 の実装は未知の終局理由を文字列として読み書きするが、裁定引分を引き分けとして分類する対応はない。 他ソフトとの受け渡しでは、拡張表記の読み込みと結果の分類を確認する必要がある。

CSA %HIKIWAKE と JKF HIKIWAKE の読み込み結果は、kind == "DRAW"、result == DRAW_BY_IMPASSE である。 これを KIF / KI2 に変換する場合は、結果に従って 持将棋 を出力し、読み戻しても DRAW_BY_IMPASSE を保持する。 SpecialMoveEntry("DRAW", GameResult.DRAW_BY_IMPASSE) を直接指定した場合も同じである。

旧版が出力した 引き分け は裁定と持将棋を区別する情報を持たないため、裁定引分としては読み込まない。 KIF の終局行は未知の特殊手（kind == "UNKNOWN"、結果は PAUSED）、終局サマリーだけの場合は結果未設定（INVALID）となる。 KI2 の終局サマリーだけの場合は中断（kind == "INTERRUPT"、結果は PAUSED）となる。 旧表記の結果を復元するには、生成元の対局情報で理由を確認する必要がある。

GameResultInfo

record.result_info が返す終局情報のイミュータブルなスナップショットである。

ビルダークラス（RecordBuilder / RecordMetadataBuilder）

メソッドチェーンまたは段階的な設定で Record や RecordMetadata を組み立てるビルダークラスである。

RecordBuilder

RecordBuilder(init_position_sfen: str | None = None) -> RecordBuilder

init_position_sfen=None の場合は平手初期局面で初期化される。 build() を呼ぶと内部状態から Record を生成し、ビルダー自身は空の初期状態にリセットされる。

RecordMetadataBuilder

RecordMetadataBuilder() -> RecordMetadataBuilder

set_event(v)、set_site(v)、set_black_player(v)、set_white_player(v)、set_game_name(v)、set_game_type(v)、set_time_control(v)、set_black_time_control(v)、set_white_time_control(v)、set_max_moves(v)、set_impasse_rule(v)、set_start_date(v)、set_end_date(v)、set_updated_date(v)、set_comment(v)、set_attribute(key, value)、remove_attribute(key)、clear_attributes() を提供し、build() -> RecordMetadata で RecordMetadata を生成する。

複数棋譜のバイナリ一括入出力（pack / sbinpack）

複数局の棋譜をまとめて 1 つのバイナリ列またはファイルに読み書きするモジュール関数を提供する。 バイナリ構造の仕様は 棋譜フォーマット一覧 を参照。

sbinpack 形式の一括読み書き

pack 形式の一括読み書き

from rsshogi.record import Record, decode_sbinpack, write_sbinpack

record = Record.from_usi_main_line(
    "startpos",
    ["7g7f", "3c3d"],
    evals=[20, -15],
    result="BLACK_WIN",
)

blob = write_sbinpack([record], metadatas=[b"game-001"])
restored_list = decode_sbinpack(blob)
restored_record, meta_bytes = restored_list[0]
assert meta_bytes == b"game-001"
assert restored_record.move_count == 2

関連項目

• 盤面管理（Board）
• 指し手クラス（Move / Move32）
• NumPy 連携
• USI プロトコル
• 棋譜フォーマット一覧