{"id":27938,"library":"mahjong","title":"Mahjong","description":"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.","status":"active","version":"2.0.0","language":"python","source_language":"en","source_url":"https://github.com/MahjongRepository/mahjong","tags":["mahjong","japanese-mahjong","hand-calculation","shanten"],"install":[{"cmd":"pip install mahjong","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"note":"Module name is 'hand_calculating' not 'hand_calculator'","wrong":"from mahjong.hand_calculator import HandCalculator","symbol":"HandCalculator","correct":"from mahjong.hand_calculating import HandCalculator"},{"note":"TilesConverter is in the tiles_converter module","wrong":"from mahjong.tiles import TilesConverter","symbol":"TilesConverter","correct":"from mahjong.tiles_converter import TilesConverter"},{"note":"Shanten class is in the shanten module directly","wrong":"from mahjong.shanten_calculator import Shanten","symbol":"Shanten","correct":"from mahjong.shanten import Shanten"}],"quickstart":{"code":"from mahjong.hand_calculating import HandCalculator\nfrom mahjong.tiles_converter import TilesConverter\nfrom mahjong.meld import Meld\n\n# Example hand: 123m 456p 789s EE (waiting for E)\ntiles = TilesConverter.one_line_string_to_136_array('123m456p789s11z')\nmelds = []\nwin_tile = TilesConverter.one_line_string_to_136_array('1z')[0]\n\ncalculator = HandCalculator()\nresult = calculator.estimate_hand_value(shanten, tiles, melds, win_tile)\nprint(result.han, result.fu, result.yaku, result.cost['main'])","lang":"python","description":"Basic hand calculation for Japanese mahjong"},"warnings":[{"fix":"Pass a Shanten instance (or the hand's shanten number) as the first argument to estimate_hand_value().","message":"In v2.0.0, HandCalculator.estimate_hand_value() changed signature: now requires 'shanten' argument as the first parameter. Old code will raise TypeError.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Review the new API for hand division results; refer to the updated documentation.","message":"In v2.0.0, the function that returns a list of possible hands now returns a new data structure. Check the changelog for details.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Use Shanten.calculate() which returns an object with the shanten number and other info.","message":"Shanten.number_characters and Shanten.number_isolated_tiles are deprecated since v1.4.0 and may be removed.","severity":"deprecated","affected_versions":">=1.4.0"},{"fix":"Use a continuous string like '123m456p789s'.","message":"TilesConverter.one_line_string_to_136_array() expects tiles in the format '1m2m3m...' without spaces. Passing a string with spaces will cause incorrect parsing.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure the hand tiles array includes all four tiles (including the fourth tile) for kan melds.","message":"When using kan melds, all four tiles must be present in the hand tiles array passed to the calculator. Missing tiles will break calculation.","severity":"gotcha","affected_versions":">=1.2.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use 'from mahjong.hand_calculating import HandCalculator' instead of 'import mahjong.hand_calculating'.","cause":"The import path is incomplete; mahjong is a package, not a module.","error":"AttributeError: module 'mahjong' has no attribute 'hand_calculating'"},{"fix":"Call estimate_hand_value with a Shanten object as the first argument, e.g., calculator.estimate_hand_value(Shanten(), tiles, melds, win_tile).","cause":"In v2.0.0, the method signature changed and now requires a shanten argument.","error":"TypeError: estimate_hand_value() missing 1 required positional argument: 'shanten'"},{"fix":"Ensure the tile string uses correct format: e.g., '123m456p789s' for simple tiles, and '1z' for honors. No spaces.","cause":"TilesConverter returned None because the input string was malformed (e.g., spaces or invalid tile codes).","error":"TypeError: 'NoneType' object is not iterable when calling calculate()"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}