cshogi.usi package

Module contents

class cshogi.usi.Engine(cmd, connect=True, debug=False)[source]

Bases: object

A class to interface with a USI (Universal Shogi Interface) engine.

Parameters:

cmd (str) – The command to launch the engine.
connect (bool) – Whether to connect to the engine upon initialization, default is True.
debug (bool) – Whether to enable debug mode, default is False.

connect(listener=None)[source]

Connects to the USI engine.

Parameters:: listener (Callable | None) – Optional callback to handle engine responses.

gameover(result=None, listener=None)[source]

Sends the ‘gameover’ command with the result to notify the engine that the game is over.

Parameters:

result (str | None) – Result of the game.
listener (Callable | None) – Optional callback to handle engine responses.

go(ponder=False, btime=None, wtime=None, byoyomi=None, binc=None, winc=None, nodes=None, listener=None)[source]

Sends the ‘go’ command to initiate a search for the best move.

Parameters:

ponder (bool) – Whether to enable pondering, default is False.
btime (int | None) – Black’s remaining time in milliseconds.
wtime (int | None) – White’s remaining time in milliseconds.
byoyomi (int | None) – Time control setting in milliseconds.
binc (int | None) – Black’s time increment per move in milliseconds.
winc (int | None) – White’s time increment per move in milliseconds.
nodes (int | None) – Limit of the number of nodes to search.
listener (Callable | None) – Optional callback to handle engine responses.

Returns:

The best move found and optional ponder move.

Return type:

Tuple[str, str | None]

go_mate(byoyomi=None, listener=None)[source]

Sends the ‘go mate’ command to initiate a search for checkmate.

Parameters:

byoyomi (int | None) – Time control setting in milliseconds, if None, defaults to ‘infinite’.
listener (Callable | None) – Optional callback to handle engine responses.

Returns:

Result of the checkmate search.

isready(listener=None)[source]

Checks if the engine is ready.

Parameters:: listener (Callable | None) – Optional callback to handle engine responses.

ponderhit(listener=None)[source]

Sends the ‘ponderhit’ command to notify the engine that its pondered move was played.

Parameters:: listener (Callable | None) – Optional callback to handle engine responses.

position(moves=None, sfen='startpos', listener=None)[source]

Sets the position on the engine.

Parameters:

moves (List[str]) – List of moves to make from the starting position.
sfen (str) – The SFEN string representing the starting position, default is “startpos”.
listener (Callable | None) – Optional callback to handle engine responses.

quit(listener=None)[source]

Sends the ‘quit’ command to the engine and waits for it to exit.

Parameters:: listener (Callable | None) – Optional callback to handle engine responses.

setoption(name, value, listener=None)[source]

Sets an option on the engine.

Parameters:

name (str) – The name of the option to set.
value (str | int) – The value to set the option to.
listener (Callable | None) – Optional callback to handle engine responses.

stop(listener=None)[source]

Sends the ‘stop’ command to stop the current search or pondering.

Parameters:: listener (Callable | None) – Optional callback to handle engine responses.

usi(listener=None)[source]

Sends the ‘usi’ command to the engine.

Parameters:: listener (Callable | None) – Optional callback to handle engine responses.
Returns:: Lines returned by the engine after sending ‘usi’.

usinewgame(listener=None)[source]

Sends the ‘usinewgame’ command to the engine.

Parameters:: listener (Callable | None) – Optional callback to handle engine responses.

class cshogi.usi.InfoListener(mate_score=100000, listner=None)[source]

Bases: object

Listener class to obtain the content of the info command returned by the USI engine.

Parameters:

mate_score (int) – The score representing a mate condition, default is 100000.
listener – A callable that may be provided to interact with the listener, default is None.
listner (Callable | None) –

Example:

info_listener = InfoListener()
engine.go(byoyomi=1000, listener=info_listener.listen())
print(info_listener.score)
print(info_listener.pv)
print(info_listener.info)

property bestmove: str

Gets the best move from the USI engine information.

Returns:: The best move.

property info: Dict

Gets detailed information regarding the best move from the USI engine.

Returns:: A dictionary containing detailed information of the best move.

listen()[source]

Resets the listener’s state and returns itself.

Returns:: The listener itself.
Return type:: InfoListener

property mate_score: int

Gets the mate score.

Returns:: The mate score.

property pv: List[str]

Gets the Principal Variation (PV) for the best move.

Returns:: A list containing the Principal Variation.

re_bestmove = re.compile('bestmove ([^ ]+).*$')

re_info = re.compile('^info (.* |)score (cp|mate) ([+\\-0-9]+) (.* |)pv ([^ ]+)(.*)$')

property score: int

Gets the score for the best move.

Returns:: The score for the best move.

class cshogi.usi.MultiPVListener(listner=None)[source]

Bases: object

Listener class to obtain the content of the MultiPV info command returned by the USI engine.

Parameters:

listener – A callable to interact with the listener, default is None.
listner (Callable | None) –

Example:

multipv_listener = MultiPVListener()
engine.go(byoyomi=1000, listener=multipv_listener.listen())
print(info_listener.info)

property info: List[Dict]

Gets detailed information regarding all captured MultiPVs from the USI engine.

Returns:: A list of dictionaries containing detailed information of the MultiPVs.

listen()[source]

Resets the listener’s state related to MultiPV and returns itself.

Returns:: The listener itself.
Return type:: MultiPVListener

re_multipv = re.compile('^info.* multipv ([0-9]+).* pv .*$')