Metadata-Version: 2.4
Name: rshogi-py
Version: 0.11.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
License-File: LICENSE
Summary: Python tools for shogi board handling, move legality, records, and training-data formats.
Author: Hiroki Taniai
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Repository, https://github.com/nyoki-mtl/rshogi

# rshogi-py

`rshogi-py` は、Python から将棋の局面・指し手・合法性・棋譜・学習データ形式を扱うための
ライブラリです。

> English: `rshogi-py` provides Python tools for shogi board handling, move
> legality, game records, policy labels, and dataset formats.

Rust 製の `rshogi` core を内部で利用していますが、通常の Python モジュールとして使えるように
構成しています。通常はこの標準ビルドを利用してください。AVX2 対応の x86_64 CPU で
AVX2 最適化版を使いたい場合は
[`rshogi-py-avx2`](https://pypi.org/project/rshogi-py-avx2/) を利用します。

Python API は [cshogi](https://pypi.org/project/cshogi/) から影響を受けています。

## できること

- SFEN / USI から局面を構築し、指し手を適用して更新する
- 指し手の生成・検証を行い、局面を SFEN として出力する
- KIF / KI2 / CSA / JKF / SFEN などの棋譜形式を読み書きする
- policy label や学習データ向けに指し手・局面を変換する
- データセット向けに NumPy と扱いやすい packed position 形式を利用する

## 開発用インストール

```bash
python -m pip install maturin
maturin develop -m crates/rshogi-py/pyproject.toml
```

## AVX2 ビルド

`rshogi-py-avx2` は、AVX2 対応 x86_64 CPU 向けに最適化した同じ Python モジュールです。

```bash
python -m pip install rshogi-py-avx2
```

## 注意

- `rshogi-py` と `rshogi-py-avx2` は同時にインストールせず、どちらか一方だけを利用してください。
- 幅広い環境では `rshogi-py` が安全な標準選択です。
- 学習向けの policy label 変換は `rshogi.policy` から利用できます。

## Policy Label

```python
from rshogi.core import Move
from rshogi.policy import compact_move_label, move_label
from rshogi.types import Color

mv = Move.from_usi("7g7f")

label = move_label(mv, Color.BLACK)
compact = compact_move_label(mv, Color.BLACK)

print(label)    # 2187 クラス
print(compact)  # 1496 クラス or None
```

## クイック例

```python
from rshogi.core import Board

board = Board()
board.apply_usi("7g7f")
print(board.to_sfen())
```

raw-state を Python から直接編集することもできます。

```python
from rshogi.core import Board
from rshogi.types import Color, Piece, PieceType, Square

board = Board()
state = board.to_position_state()
state.set_piece(Square.from_usi("7g"), Piece(0))
state.set_piece(Square.from_usi("7f"), Piece.from_color_type(Color.BLACK, PieceType.PAWN))
state.ply = 42

board.set_position_state(state)
report = board.validate_all()
print(board.to_sfen())
print(report.is_valid())
```

USI の `position` 文字列を直接扱うこともできます。

```python
from rshogi.core import Board, normalize_usi_position, parse_usi_position

board = Board()
board.set_usi_position("position startpos moves 7g7f 3c3d")

board2 = parse_usi_position("startpos moves 7g7f")
print(board2.to_sfen())

print(normalize_usi_position("position startpos"))  # "startpos"
```

## 構造化 import

`rshogi-py` は用途別の submodule から import できます。

```python
# 型と定数
from rshogi.types import Color, PieceType, Square
from rshogi.core import Move, Move32

# 盤面
from rshogi.core import Board, PositionState, ValidationIssue, ValidationReport

# 棋譜
from rshogi.record import Record, RecordMetadata, GameResult

# 棋譜変換
record = Record.from_kif_str(kif_text)
kif_text = record.to_kif()

# 棋譜ファイル I/O
record = Record.from_kif_file("example.kif")
record.write_kif("example_out.kif")

# NumPy dtype
from rshogi.numpy import (
    PackedSfen,
    PackedSfenValue,
    HuffmanCodedPos,
    HuffmanCodedPosAndEval,
)

# Policy label
from rshogi.policy import move_label, compact_move_label
```

基本的には submodule から import してください。

```python
from rshogi.core import Board
from rshogi.core import Move
from rshogi.record import Record
```

## 棋譜 I/O の注意

`Record` の棋譜 I/O は、内部の `rshogi` 実装と同じ互換方針で動作します。

- KIF/KI2 は ShogiHome/tsshogi 系の実務互換と `shogi-validator` 寄りの整形を意識しています。
- 変化手順と終局要約が同居する場合、`to_kif()` / `to_ki2()` は `変化：...` を先に、
  `まで...` を最後に出力します。
- `from_kif_str()` / `from_ki2_str()` で読んだ初手前コメントは
  `Record.initial_comment` に保持され、`to_kif()` / `to_ki2()` で 1 手目の前に戻ります。
- `from_csa_str()` / `from_csa_file()` は CSA 3.0 に合わせて `'*comment` だけを
  プログラムが読むコメントとして受理し、plain な `'comment` は読み飛ばします。
  受理した開始局面コメントは `Record.initial_comment` に保持されます。
- 互換性のため、手番行より前にある `'*comment` も `initial_comment` に正規化して受理します。
- `RecordMetadata.comment` は自由コメントではなく、KIF の `備考` / CSA の `$NOTE` /
  JKF header の `備考` に対応します。
- `to_csa()` は move comment と初期局面コメントを `'*comment` として出力し、
  `write_kif()` / `write_ki2()` / `write_csa()` は末尾改行つきで書き出します。

