mahjong.hand_calculating.hand_response

class mahjong.hand_calculating.hand_response.HandResponse(cost=None, han=None, fu=None, yaku=None, error=None, fu_details=None, is_open_hand=False)[source]

Bases: object

Result of a hand value estimation returned by HandCalculator.estimate_hand_value().

On success, the response contains the hand’s han count, fu count, scoring breakdown, yaku list, and fu component details. On failure, only error is set and all other fields are None.

Successful hand — access scoring information:

>>> from mahjong.hand_calculating.hand import HandCalculator
>>> from mahjong.tile import TilesConverter
>>> tiles = TilesConverter.string_to_136_array(man="22444", pin="333567", sou="444")
>>> win_tile = TilesConverter.string_to_136_array(sou="4")[0]
>>> result = HandCalculator.estimate_hand_value(tiles, win_tile)
>>> result.han
1
>>> result.fu
40
>>> result.cost["main"]
1300
>>> result.yaku
[Tanyao]
>>> print(result)
1 han, 40 fu

Invalid hand — error is set:

>>> tiles = TilesConverter.string_to_136_array(man="12345")
>>> win_tile = TilesConverter.string_to_136_array(man="1")[0]
>>> result = HandCalculator.estimate_hand_value(tiles, win_tile)
>>> result.error is not None
True
>>> result.cost is None
True
Variables:

  • cost (ScoresResult | None) – scoring breakdown with main/additional payments, bonuses, and total; None when the hand is invalid

  • han (int | None) – total han count; None when the hand is invalid

  • fu (int | None) – total fu (minipoints) count; None when the hand is invalid

  • fu_details (list[FuDetail] | None) – fu component breakdown sorted by fu value (descending); None when the hand is invalid

  • yaku (list[Yaku] | None) – yaku present in the hand sorted by yaku id; None when the hand is invalid

  • error (str | None) – error message describing why the hand is invalid; None for valid hands

  • is_open_hand (bool) – whether the hand contains open melds

Parameters:

  • cost (ScoresResult | None)

  • han (int | None)

  • fu (int | None)

  • yaku (list[Yaku] | None)

  • error (str | None)

  • fu_details (list[FuDetail] | None)

  • is_open_hand (bool)

__init__(cost=None, han=None, fu=None, yaku=None, error=None, fu_details=None, is_open_hand=False)[source]

Initialize a hand response.

Typically constructed by HandCalculator.estimate_hand_value() rather than directly by user code.

Parameters:

  • cost (ScoresResult | None) – scoring breakdown (payment amounts, bonuses, total)

  • han (int | None) – total han count

  • fu (int | None) – total fu (minipoints) count

  • yaku (Collection[Yaku] | None) – yaku present in the hand; stored sorted by yaku id

  • error (str | None) – error message if the hand is invalid

  • fu_details (list[FuDetail] | None) – fu component breakdown; stored sorted by fu value (descending)

  • is_open_hand (bool) – whether the hand contains open melds

Return type:

None