mahjong 2.0.0.dev2__tar.gz → 2.2.0.dev1__tar.gz

{mahjong-2.0.0.dev2 → mahjong-2.2.0.dev1}/MANIFEST.in

@@ -1,2 +1,3 @@
 prune examples
+prune scripts
 prune tests

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mahjong
-Version: 2.0.0.dev2
+Version: 2.2.0.dev1
 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.
 
@@ -50,36 +55,10 @@ So, we can say that our hand calculator works the same way that tenhou.net hand
 pip install mahjong
 ```
 
-## Local development setup
+## Contributing
 
-To set up the project locally for development:
-
-1. Clone the repository:
-
-    ```bash
-    git clone https://github.com/MahjongRepository/mahjong.git
-    cd mahjong
-    ```
-
-2. Setup env using [uv](https://github.com/astral-sh/uv):
-
-    ```bash
-    uv sync
-    ```
-
-3. Run tests to verify setup:
-
-    ```bash
-    make tests
-    # Or directly:
-    uv run pytest
-    ```
-
-4. Run full checks before committing:
-
-    ```bash
-    make check   # Runs format, lint, and tests
-    ```
+For guidance on setting up a development environment and contributing to mahjong,
+see [Contributing to mahjong](CONTRIBUTING.md).
 
 ## License
 

{mahjong-2.0.0.dev2 → mahjong-2.2.0.dev1}/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.
 
@@ -26,36 +26,10 @@ So, we can say that our hand calculator works the same way that tenhou.net hand
 pip install mahjong
 ```
 
-## Local development setup
+## Contributing
 
-To set up the project locally for development:
-
-1. Clone the repository:
-
-    ```bash
-    git clone https://github.com/MahjongRepository/mahjong.git
-    cd mahjong
-    ```
-
-2. Setup env using [uv](https://github.com/astral-sh/uv):
-
-    ```bash
-    uv sync
-    ```
-
-3. Run tests to verify setup:
-
-    ```bash
-    make tests
-    # Or directly:
-    uv run pytest
-    ```
-
-4. Run full checks before committing:
-
-    ```bash
-    make check   # Runs format, lint, and tests
-    ```
+For guidance on setting up a development environment and contributing to mahjong,
+see [Contributing to mahjong](CONTRIBUTING.md).
 
 ## License
 

{mahjong-2.0.0.dev2 → mahjong-2.2.0.dev1}/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.2.0.dev1/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.2.0.dev1}/mahjong/hand_calculating/divider.py

@@ -2,6 +2,7 @@ from collections.abc import Collection, Sequence
 from dataclasses import dataclass
 from enum import IntEnum
 from functools import lru_cache
+from itertools import product
 from typing import Literal
 
 from mahjong.meld import Meld
@@ -21,7 +22,7 @@ class _Block:
 
     @classmethod
     def from_meld(cls, meld: Meld) -> "_Block":
-        tile_34 = meld.tiles_34[0]
+        tile_34 = meld._sorted_tiles_34[0]  # noqa: SLF001
         match meld.type:
             case Meld.CHI:
                 return cls(tile_34, _BlockType.SEQUENCE)
@@ -160,29 +161,27 @@ class HandDivider:
         man_combinations = HandDivider._decompose_single_color_hand(hand[0:9], 0)
         pin_combinations = HandDivider._decompose_single_color_hand(hand[9:18], 9)
         sou_combinations = HandDivider._decompose_single_color_hand(hand[18:27], 18)
-        honors = HandDivider._decompose_honors_hand(hand[27:34])
+        honors_combinations = HandDivider._decompose_honors_hand(hand[27:34])
 
         combinations: list[list[_Block]] = []
 
         if not melds and (chiitoitsu := HandDivider._decompose_chiitoitsu(hand)):
             combinations.append(chiitoitsu)
 
-        for man in man_combinations:
-            for pin in pin_combinations:
-                for sou in sou_combinations:
-                    # For invalid suits, *_combinations will be [] and the loop will not be executed.
-                    all_blocks = [*man, *pin, *sou, *honors]
+        # For invalid suits or honors, *_combinations will be [] and the loop will not be executed.
+        for man, pin, sou, honors in product(man_combinations, pin_combinations, sou_combinations, honors_combinations):
+            all_blocks = [*man, *pin, *sou, *honors]
 
-                    num_pair = sum(block.ty == _BlockType.PAIR for block in all_blocks)
-                    if num_pair != 1:
-                        continue
+            num_pair = sum(block.ty == _BlockType.PAIR for block in all_blocks)
+            if num_pair != 1:
+                continue
 
-                    all_blocks.extend(melds)
-                    if len(all_blocks) != 5:
-                        continue
+            all_blocks.extend(melds)
+            if len(all_blocks) != 5:
+                continue
 
-                    all_blocks.sort()
-                    combinations.append(all_blocks)
+            all_blocks.sort()
+            combinations.append(all_blocks)
 
         combinations.sort()
         return tuple(tuple(blocks) for blocks in combinations)
@@ -282,7 +281,9 @@ class HandDivider:
         return combinations
 
     @staticmethod
-    def _decompose_honors_hand(honors_hand: list[int]) -> list[_Block]:
+    def _decompose_honors_hand(honors_hand: list[int]) -> list[list[_Block]]:
+        # If there is no honor tile, returns [[]].
+        # If the honors cannot be decomposed, returns [].
         has_pair = False
         blocks: list[_Block] = []
         for i, count in enumerate(honors_hand):
@@ -299,4 +300,4 @@ class HandDivider:
                 case _:
                     return []
 
-        return blocks
+        return [blocks]

{mahjong-2.0.0.dev2 → mahjong-2.2.0.dev1}/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)
         """