mahjong

library2.0.0pypypiunverified

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

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · MAHJONG

mahjong

pythonv2.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HandCalculator

✓ from mahjong.hand_calculating import HandCalculator

✗ from mahjong.hand_calculating import HandCalculator

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'])

Debug

Known issues

breakingIn 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().

affects: >=2.0.0

breakingIn 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.

affects: >=2.0.0

deprecatedShanten.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.

affects: >=1.4.0

gotchaTilesConverter.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'.

affects: all

gotchaWhen 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.

affects: >=1.2.0

Upgrade

Version history

2.0.0latest on PyPI · released Apr 2, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/MahjongRepository/mahjong ↗

packagehttps://pypi.org/project/mahjong/ ↗

docshttps://mahjongrepository.github.io/mahjong ↗