mahjong 2.0.0.dev2__tar.gz → 2.1.0__tar.gz

{mahjong-2.0.0.dev2/mahjong.egg-info → mahjong-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mahjong
-Version: 2.0.0.dev2
+Version: 2.1.0
 Summary: Mahjong hands calculation
 Author-email: Alexey Lisikhin <alexey@nihisil.com>
 Maintainer: Apricot S.
@@ -9,14 +9,19 @@ Project-URL: Homepage, https://github.com/MahjongRepository/mahjong
 Project-URL: Documentation, https://mahjongrepository.github.io/mahjong
 Project-URL: Wiki, https://github.com/MahjongRepository/mahjong/wiki
 Classifier: Development Status :: 5 - Production/Stable
-Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Games/Entertainment :: Board Games
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
@@ -31,11 +36,11 @@ Dynamic: license-file
 [![Linters and tests](https://github.com/MahjongRepository/mahjong/actions/workflows/lint_and_test.yml/badge.svg)](https://github.com/MahjongRepository/mahjong/actions/workflows/lint_and_test.yml)
 [![API Docs](https://img.shields.io/badge/api-master-yellow.svg)](https://mahjongrepository.github.io/mahjong)
 
-This library can calculate hand cost (han, fu with details, yaku, and scores) for riichi mahjong (Japanese version).
+Japanese riichi mahjong hand calculator library.
 
-Also calculating of shanten is supported.
+Compute hand cost (han, fu, yaku, and scores), validate winning hands, and calculate shanten (minimum tiles to tenpai).
 
-The code was validated on tenhou.net phoenix replays in total on **26,148,038 hands**.
+The code was validated on tenhou.net phoenix replays: **26,148,050** four-player and **8,406,421** three-player winning hands.
 
 So, we can say that our hand calculator works the same way that tenhou.net hand calculation.
 

{mahjong-2.0.0.dev2 → mahjong-2.1.0}/README.md

@@ -7,11 +7,11 @@
 [![Linters and tests](https://github.com/MahjongRepository/mahjong/actions/workflows/lint_and_test.yml/badge.svg)](https://github.com/MahjongRepository/mahjong/actions/workflows/lint_and_test.yml)
 [![API Docs](https://img.shields.io/badge/api-master-yellow.svg)](https://mahjongrepository.github.io/mahjong)
 
-This library can calculate hand cost (han, fu with details, yaku, and scores) for riichi mahjong (Japanese version).
+Japanese riichi mahjong hand calculator library.
 
-Also calculating of shanten is supported.
+Compute hand cost (han, fu, yaku, and scores), validate winning hands, and calculate shanten (minimum tiles to tenpai).
 
-The code was validated on tenhou.net phoenix replays in total on **26,148,038 hands**.
+The code was validated on tenhou.net phoenix replays: **26,148,050** four-player and **8,406,421** three-player winning hands.
 
 So, we can say that our hand calculator works the same way that tenhou.net hand calculation.
 

{mahjong-2.0.0.dev2 → mahjong-2.1.0}/mahjong/__init__.py

@@ -1,5 +1,27 @@
 """
-_summary_.
+Japanese riichi mahjong hand calculator library.
+
+Compute hand cost (han, fu, yaku, and scores), validate winning hands, and calculate shanten (minimum tiles to tenpai).
+
+.. rubric:: Main entry points
+
+* :class:`~mahjong.hand_calculating.hand.HandCalculator` — estimate hand value (han, fu, cost,
+  and yaku list) given tiles, win tile, melds, and dora indicators.
+* :class:`~mahjong.agari.Agari` — check whether tiles form a complete (winning) hand structure.
+* :class:`~mahjong.shanten.Shanten` — calculate how many tiles away a hand is from winning.
+
+.. rubric:: Tile and meld utilities
+
+* :class:`~mahjong.tile.TilesConverter` — convert between mpsz-notation strings, 34-format count
+  arrays, and 136-format tile index lists.
+* :class:`~mahjong.meld.Meld` — represent declared melds (chi, pon, kan).
+
+.. rubric:: Configuration and results
+
+* :class:`~mahjong.hand_calculating.hand_config.HandConfig` — configure win conditions (tsumo/ron),
+  wind context, and optional rule variants (open tanyao, aka dora, double yakuman, etc.).
+* :class:`~mahjong.hand_calculating.hand_response.HandResponse` — structured result containing
+  han, fu, fu details, cost breakdown, and yaku list.
 
 Tile representation
 ###################
@@ -30,11 +52,8 @@ Honors (`z`) use ranks to distinguish individual tiles:
 * `6` - Green dragon (發, hatsu)
 * `7` - Red dragon (中, chun)
 
-Multiple tiles may be concatenated without separators to form a string that represents a collection. For example:
-
-``123m406p789s11555z``
-
-is equivalent to ``1m2m3m4p0p6p7s8s9s1z1z5z5z5z``.
+Multiple tiles may be concatenated without separators to form a string that represents a collection
+(e.g., ``123m406p789s11555z`` is equivalent to ``1m2m3m4p0p6p7s8s9s1z1z5z5z5z``).
 
 34-format
 ---------

mahjong-2.1.0/mahjong/hand_calculating/__init__.py

@@ -0,0 +1,23 @@
+"""
+Hand value calculation pipeline.
+
+This subpackage evaluates a winning hand and produces its han, fu, yaku list,
+and payment amounts. The calculation flows through several stages:
+
+1. :class:`~mahjong.hand_calculating.divider.HandDivider` decomposes the hand into all
+   valid block combinations (4 melds + 1 pair, or 7 pairs for chiitoitsu).
+2. :class:`~mahjong.hand_calculating.yaku.Yaku` subclasses test each decomposition for
+   matching yaku patterns (e.g., tanyao, pinfu, honitsu).
+3. :class:`~mahjong.hand_calculating.fu.FuCalculator` computes minipoints from the meld
+   structure, wait type, pair, and winning method.
+4. :class:`~mahjong.hand_calculating.scores.ScoresCalculator` converts han and fu into
+   payment amounts, accounting for honba and kyoutaku bonuses.
+
+:class:`~mahjong.hand_calculating.hand.HandCalculator` orchestrates the full pipeline and
+returns a :class:`~mahjong.hand_calculating.hand_response.HandResponse` with the
+highest-scoring result.
+
+Behavior is controlled by :class:`~mahjong.hand_calculating.hand_config.HandConfig`, which
+specifies win conditions (tsumo/ron), wind context, and optional rule variants such as
+open tanyao, aka dora, and double yakuman.
+"""

{mahjong-2.0.0.dev2 → mahjong-2.1.0}/mahjong/hand_calculating/fu.py

@@ -169,7 +169,7 @@ class FuCalculator:
             as tile indices in 34-format
         :param config: hand configuration with win method and optional rule settings
         :param valued_tiles: tile indices in 34-format for tiles that grant pair fu
-            (dragons, player wind, round wind); pass the same index twice for double-valued
+            (dragons, seat wind, round wind); pass the same index twice for double-valued
         :param melds: declared melds (chi, pon, kan)
         :return: tuple of (fu component list, total fu rounded up to nearest 10)
         """

{mahjong-2.0.0.dev2 → mahjong-2.1.0}/mahjong/hand_calculating/hand.py

@@ -1,7 +1,7 @@
 from collections.abc import Collection
 from typing import TypedDict
 
-from mahjong.constants import AKA_DORAS, CHUN, HAKU, HATSU
+from mahjong.constants import AKA_DORAS, CHUN, HAKU, HATSU, NORTH
 from mahjong.hand_calculating.divider import HandDivider
 from mahjong.hand_calculating.fu import FuCalculator, FuDetail
 from mahjong.hand_calculating.hand_config import HandConfig
@@ -22,36 +22,85 @@ class _CalculatedHand(TypedDict):
     fu_details: list[FuDetail]
 
 
+def _hand_priority(hand: _CalculatedHand) -> tuple[int, bool, int, int]:
+    """
+    Rank a hand decomposition, the most expensive one is used.
+
+    The highest score wins, and on an equal score a real yakuman wins over counted (kazoe)
+    yakuman built from regular yaku, as on Tenhou.
+    """
+    total = hand["cost"]["total"] if hand["cost"] else -1
+    has_yakuman = any(yaku.is_yakuman for yaku in hand["hand_yaku"])
+    return total, has_yakuman, hand["han"], hand["fu"]
+
+
 # suit bitmask: sou=1, pin=2, man=4
 _ALL_SUITS_MASK = 7
 
-_DEFAULT_CONFIG = HandConfig()
-
 
 class HandCalculator:
+    """
+    Hand value estimator.
+
+    Evaluate a winning hand's han, fu, yaku, and payment amounts. Accepts tiles in
+    136-format, an optional :class:`~mahjong.hand_calculating.hand_config.HandConfig` for
+    win conditions and rule variants, and optional melds and dora/ura-dora indicators. When multiple
+    valid decompositions exist, the highest-scoring result is returned.
+    """
+
+    # basic hand validation
     ERR_NO_WINNING_TILE = "winning_tile_not_in_hand"
+    """``win_tile`` index is not present in the ``tiles`` array."""
+    ERR_HAND_NOT_WINNING = "hand_not_winning"
+    """No valid decomposition exists; the hand is not a winning hand."""
+    ERR_NO_YAKU = "no_yaku"
+    """Hand can be decomposed but has zero han (no yaku applies)."""
+
+    # riichi constraints
     ERR_OPEN_HAND_RIICHI = "open_hand_riichi_not_allowed"
+    """Riichi declared on an open hand (open melds present)."""
     ERR_OPEN_HAND_DABURI = "open_hand_daburi_not_allowed"
+    """Double riichi declared on an open hand."""
     ERR_IPPATSU_WITHOUT_RIICHI = "ippatsu_without_riichi_not_allowed"
-    ERR_HAND_NOT_WINNING = "hand_not_winning"
-    ERR_NO_YAKU = "no_yaku"
+    """Ippatsu claimed without riichi or double riichi."""
+
+    # win-condition conflicts
     ERR_CHANKAN_WITH_TSUMO = "chankan_with_tsumo_not_allowed"
+    """Chankan (robbing a kan) requires a ron win."""
     ERR_RINSHAN_WITHOUT_TSUMO = "rinshan_without_tsumo_not_allowed"
+    """Rinshan kaihou (win after kan) requires a tsumo win."""
     ERR_HAITEI_WITHOUT_TSUMO = "haitei_without_tsumo_not_allowed"
+    """Haitei raoyue (last-tile draw) requires a tsumo win."""
     ERR_HOUTEI_WITH_TSUMO = "houtei_with_tsumo_not_allowed"
+    """Houtei raoyui (last-tile discard) requires a ron win."""
     ERR_HAITEI_WITH_RINSHAN = "haitei_with_rinshan_not_allowed"
+    """Haitei and rinshan are mutually exclusive (different last-tile sources)."""
     ERR_HOUTEI_WITH_CHANKAN = "houtei_with_chankan_not_allowed"
+    """Houtei and chankan are mutually exclusive."""
+
+    # tenhou (blessing of heaven) constraints
     ERR_TENHOU_NOT_AS_DEALER = "tenhou_not_as_dealer_not_allowed"
+    """Tenhou is exclusive to the dealer (East player)."""
     ERR_TENHOU_WITHOUT_TSUMO = "tenhou_without_tsumo_not_allowed"
+    """Tenhou requires a tsumo win on the dealer's first draw."""
     ERR_TENHOU_WITH_MELD = "tenhou_with_meld_not_allowed"
+    """Tenhou requires a closed hand with no declared melds."""
+
+    # chiihou (blessing of earth) constraints
     ERR_CHIIHOU_AS_DEALER = "chiihou_as_dealer_not_allowed"
+    """Chiihou is exclusive to non-dealer players."""
     ERR_CHIIHOU_WITHOUT_TSUMO = "chiihou_without_tsumo_not_allowed"
+    """Chiihou requires a tsumo win on the player's first draw."""
     ERR_CHIIHOU_WITH_MELD = "chiihou_with_meld_not_allowed"
+    """Chiihou requires a closed hand with no declared melds."""
+
+    # renhou (blessing of man) constraints
     ERR_RENHOU_AS_DEALER = "renhou_as_dealer_not_allowed"
+    """Renhou is exclusive to non-dealer players."""
     ERR_RENHOU_WITH_TSUMO = "renhou_with_tsumo_not_allowed"
+    """Renhou requires a ron win before the player's first draw."""
     ERR_RENHOU_WITH_MELD = "renhou_with_meld_not_allowed"
-
-    # more possible errors, like tenhou and haitei can't be together (so complicated :<)
+    """Renhou requires a closed hand with no declared melds."""
 
     @staticmethod
     def estimate_hand_value(
@@ -64,16 +113,84 @@ class HandCalculator:
         ura_dora_indicators: Collection[int] | None = None,
     ) -> HandResponse:
         """
-        :param tiles: array with 14 tiles in 136-tile format
-        :param win_tile: 136-tile format tile that caused win (ron or tsumo)
-        :param melds: array with Meld objects
-        :param dora_indicators: array of tiles in 136-tile format
-        :param config: HandConfig object
-        :param scores_calculator_factory: ScoresCalculator class or subclass
-        :param ura_dora_indicators: array of tiles in 136-tile format (only counted with riichi)
-        :return: HandResponse object
+        Estimate the point value of a winning hand.
+
+        Validate the hand and win conditions, decompose the hand into all possible
+        block combinations, evaluate yaku and fu for each decomposition, and return
+        the highest-scoring result as a :class:`~mahjong.hand_calculating.hand_response.HandResponse`.
+
+        Basic closed ron with tanyao:
+
+        >>> 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
+
+        Tsumo win with riichi and pinfu:
+
+        >>> from mahjong.hand_calculating.hand_config import HandConfig
+        >>> tiles = TilesConverter.string_to_136_array(man="234789", pin="12345666")
+        >>> win_tile = TilesConverter.string_to_136_array(pin="6")[0]
+        >>> config = HandConfig(is_tsumo=True, is_riichi=True)
+        >>> result = HandCalculator.estimate_hand_value(tiles, win_tile, config=config)
+        >>> result.han
+        3
+        >>> result.fu
+        20
+        >>> result.cost["main"]
+        1300
+        >>> result.cost["additional"]
+        700
+
+        Dealer tsumo with riichi and ippatsu:
+
+        >>> from mahjong.constants import EAST
+        >>> config = HandConfig(is_tsumo=True, is_riichi=True, is_ippatsu=True, player_wind=EAST)
+        >>> result = HandCalculator.estimate_hand_value(tiles, win_tile, config=config)
+        >>> result.error is None
+        True
+
+        Open hand with melds and dora:
+
+        >>> from mahjong.meld import Meld
+        >>> tiles = TilesConverter.string_to_136_array(man="234567", pin="22", sou="234", honors="555")
+        >>> win_tile = TilesConverter.string_to_136_array(man="7")[0]
+        >>> melds = [Meld(meld_type=Meld.PON, tiles=TilesConverter.string_to_136_array(honors="555"))]
+        >>> dora_indicators = [TilesConverter.string_to_136_array(man="6")[0]]
+        >>> result = HandCalculator.estimate_hand_value(tiles, win_tile, melds=melds, dora_indicators=dora_indicators)
+        >>> result.han
+        2
+
+        Invalid hand returns an error:
+
+        >>> 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 == HandCalculator.ERR_HAND_NOT_WINNING
+        True
+
+        :param tiles: hand tiles in 136-format (14 tiles including the winning tile;
+            15 with one kan, 16 with two, etc.)
+        :param win_tile: the winning tile index in 136-format (must be present in ``tiles``)
+        :param melds: declared melds (:class:`~mahjong.meld.Meld` objects for chi, pon, kan)
+        :param dora_indicators: dora indicator tile indices in 136-format
+        :param config: hand configuration with win conditions, wind context, and optional rules;
+            defaults to a closed ron with no special conditions
+        :param scores_calculator_factory: scoring calculator class; pass
+            :class:`~mahjong.hand_calculating.scores.Aotenjou` for aotenjou (limitless) scoring
+        :param ura_dora_indicators: ura dora indicator tile indices in 136-format
+            (counted only when riichi or double riichi is declared)
+        :return: :class:`~mahjong.hand_calculating.hand_response.HandResponse` with scoring
+            details on success, or with :attr:`~mahjong.hand_calculating.hand_response.HandResponse.error`
+            set on failure
         """
-
         if not melds:
             melds = []
 
@@ -83,9 +200,9 @@ class HandCalculator:
         if not ura_dora_indicators:
             ura_dora_indicators = []
 
-        config = config or _DEFAULT_CONFIG
+        config = config or HandConfig()
 
-        hand_yaku = []
+        hand_yaku: list[Yaku] = []
         scores_calculator = scores_calculator_factory()
         tiles_34 = TilesConverter.to_34_array(tiles)
 
@@ -172,8 +289,10 @@ class HandCalculator:
         hand_options = HandDivider.divide_hand(tiles_34, melds)
 
         # precompute dora counts, invariant across all hand decompositions
-        dora_count_map = build_dora_count_map(dora_indicators)
+        dora_count_map = build_dora_count_map(dora_indicators, config.options.is_three_player)
         precomputed_dora = count_dora_for_hand(tiles_34, dora_count_map)
+        if config.num_nuki_dora > 0:
+            precomputed_dora += dora_count_map.get(NORTH, 0) * config.num_nuki_dora + config.num_nuki_dora
 
         precomputed_aka_dora = 0
         if config.options.has_aka_dora:
@@ -181,8 +300,10 @@ class HandCalculator:
 
         precomputed_ura_dora = 0
         if config.is_riichi or config.is_daburu_riichi:
-            ura_count_map = build_dora_count_map(ura_dora_indicators)
+            ura_count_map = build_dora_count_map(ura_dora_indicators, config.options.is_three_player)
             precomputed_ura_dora = count_dora_for_hand(tiles_34, ura_count_map)
+            if config.num_nuki_dora > 0:
+                precomputed_ura_dora += ura_count_map.get(NORTH, 0) * config.num_nuki_dora
 
         yakuhai_seat_wind_yaku = (
             config.yaku.seat_wind_east,
@@ -424,7 +545,7 @@ class HandCalculator:
                     if not is_aotenjou:
                         hand_yaku = yakuman_list
                     else:
-                        scores_calculator.aotenjou_filter_yaku(hand_yaku, config)  # ty: ignore[unresolved-attribute]
+                        scores_calculator.aotenjou_filter_yaku(hand_yaku, config)
                         yakuman_list = []
 
                 # calculate han
@@ -515,7 +636,7 @@ class HandCalculator:
 
                 count_of_dora = 0
                 for tile in tiles_for_dora:
-                    count_of_dora += plus_dora(tile, dora_indicators)
+                    count_of_dora += plus_dora(tile, dora_indicators, is_three_player=config.options.is_three_player)
 
                 if count_of_dora:
                     config.yaku.dora.han_open = count_of_dora
@@ -526,7 +647,9 @@ class HandCalculator:
                 if config.is_riichi or config.is_daburu_riichi:
                     count_of_ura_dora = 0
                     for tile in tiles_for_dora:
-                        count_of_ura_dora += plus_dora(tile, ura_dora_indicators)
+                        count_of_ura_dora += plus_dora(
+                            tile, ura_dora_indicators, is_three_player=config.options.is_three_player
+                        )
 
                     if count_of_ura_dora:
                         config.yaku.ura_dora.han_closed = count_of_ura_dora
@@ -542,14 +665,11 @@ class HandCalculator:
             return HandResponse(error=HandCalculator.ERR_HAND_NOT_WINNING)
 
         # find most expensive hand
-        calculated_hands = sorted(calculated_hands, key=lambda x: (x["han"], x["fu"]), reverse=True)
+        calculated_hands.sort(key=_hand_priority, reverse=True)
         # correctly sort expensive hands by fu details
-        calculated_hands = [
-            x
-            for x in calculated_hands
-            if x["han"] == calculated_hands[0]["han"] and x["fu"] == calculated_hands[0]["fu"]
-        ]
-        calculated_hands = sorted(calculated_hands, key=lambda x: sum([y["fu"] for y in x["fu_details"]]), reverse=True)
+        top_priority = _hand_priority(calculated_hands[0])
+        calculated_hands = [x for x in calculated_hands if _hand_priority(x) == top_priority]
+        calculated_hands.sort(key=lambda x: sum([y["fu"] for y in x["fu_details"]]), reverse=True)
         calculated_hand = calculated_hands[0]
 
         error = calculated_hand["error"]