Mahjong

2.0.0 verified Sat May 09 auth: no python

Library for mahjong hands calculation, including hand division, shanten number, and yaku detection for Japanese mahjong. Current version: 2.0.0. Active development, irregular releases.

pip install mahjong

Common errors

error AttributeError: module 'mahjong' has no attribute 'hand_calculating' ↓

cause The import path is incomplete; mahjong is a package, not a module.

fix

Use 'from mahjong.hand_calculating import HandCalculator' instead of 'import mahjong.hand_calculating'.

error TypeError: estimate_hand_value() missing 1 required positional argument: 'shanten' ↓

cause In v2.0.0, the method signature changed and now requires a shanten argument.

fix

Call estimate_hand_value with a Shanten object as the first argument, e.g., calculator.estimate_hand_value(Shanten(), tiles, melds, win_tile).

error TypeError: 'NoneType' object is not iterable when calling calculate() ↓

cause TilesConverter returned None because the input string was malformed (e.g., spaces or invalid tile codes).

fix

Ensure the tile string uses correct format: e.g., '123m456p789s' for simple tiles, and '1z' for honors. No spaces.

Warnings

breaking In v2.0.0, HandCalculator.estimate_hand_value() changed signature: now requires 'shanten' argument as the first parameter. Old code will raise TypeError. ↓

fix Pass a Shanten instance (or the hand's shanten number) as the first argument to estimate_hand_value().

breaking In v2.0.0, the function that returns a list of possible hands now returns a new data structure. Check the changelog for details. ↓

fix Review the new API for hand division results; refer to the updated documentation.

deprecated Shanten.number_characters and Shanten.number_isolated_tiles are deprecated since v1.4.0 and may be removed. ↓

fix Use Shanten.calculate() which returns an object with the shanten number and other info.

gotcha TilesConverter.one_line_string_to_136_array() expects tiles in the format '1m2m3m...' without spaces. Passing a string with spaces will cause incorrect parsing. ↓

fix Use a continuous string like '123m456p789s'.

gotcha When using kan melds, all four tiles must be present in the hand tiles array passed to the calculator. Missing tiles will break calculation. ↓

fix Ensure the hand tiles array includes all four tiles (including the fourth tile) for kan melds.

Imports

HandCalculator

wrong

from mahjong.hand_calculator import HandCalculator

correct

from mahjong.hand_calculating import HandCalculator

Module name is 'hand_calculating' not 'hand_calculator'

TilesConverter

wrong

from mahjong.tiles import TilesConverter

correct

from mahjong.tiles_converter import TilesConverter

TilesConverter is in the tiles_converter module

Shanten

wrong

from mahjong.shanten_calculator import Shanten

correct

from mahjong.shanten import Shanten

Shanten class is in the shanten module directly

Quickstart

Basic hand calculation for Japanese mahjong

from mahjong.hand_calculating import HandCalculator
from mahjong.tiles_converter import TilesConverter
from mahjong.meld import Meld

# Example hand: 123m 456p 789s EE (waiting for E)
tiles = TilesConverter.one_line_string_to_136_array('123m456p789s11z')
melds = []
win_tile = TilesConverter.one_line_string_to_136_array('1z')[0]

calculator = HandCalculator()
result = calculator.estimate_hand_value(shanten, tiles, melds, win_tile)
print(result.han, result.fu, result.yaku, result.cost['main'])