mahjong 2.1.0__tar.gz → 2.2.0.dev1__tar.gz

{mahjong-2.1.0 → mahjong-2.2.0.dev1}/MANIFEST.in

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mahjong
-Version: 2.1.0
+Version: 2.2.0.dev1
 Summary: Mahjong hands calculation
 Author-email: Alexey Lisikhin <alexey@nihisil.com>
 Maintainer: Apricot S.
@@ -55,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.1.0 → mahjong-2.2.0.dev1}/README.md

@@ -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.1.0 → 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.1.0 → mahjong-2.2.0.dev1}/mahjong/hand_calculating/hand.py

@@ -56,6 +56,25 @@ class HandCalculator:
     ERR_NO_YAKU = "no_yaku"
     """Hand can be decomposed but has zero han (no yaku applies)."""
 
+    # count validation
+    ERR_NEGATIVE_TSUMI_NUMBER = "negative_tsumi_number_not_allowed"
+    """``HandConfig.tsumi_number`` (honba counters) is negative."""
+    ERR_NEGATIVE_KYOUTAKU_NUMBER = "negative_kyoutaku_number_not_allowed"
+    """``HandConfig.kyoutaku_number`` (riichi deposits) is negative."""
+    ERR_NEGATIVE_PAARENCHAN = "negative_paarenchan_not_allowed"
+    """``HandConfig.paarenchan`` (consecutive dealer wins) is negative."""
+    ERR_NEGATIVE_NUKI_DORA = "negative_nuki_dora_not_allowed"
+    """``HandConfig.num_nuki_dora`` (extracted north winds) is negative."""
+
+    # meld validation
+    ERR_MELD_INVALID = "meld_invalid"
+    """A meld fails :meth:`Meld.is_valid`: its tiles don't match its type, its type is unknown,
+    or a meld other than a kan or a nuki is closed."""
+    ERR_NUKI_MELD_NOT_SUPPORTED = "nuki_meld_not_supported"
+    """A nuki meld was passed; pass nuki through ``HandConfig.num_nuki_dora`` instead."""
+    ERR_MELD_TILE_NOT_IN_HAND = "meld_tile_not_in_hand"
+    """A meld tile index is not present in the ``tiles`` array."""
+
     # riichi constraints
     ERR_OPEN_HAND_RIICHI = "open_hand_riichi_not_allowed"
     """Riichi declared on an open hand (open melds present)."""
@@ -77,10 +96,14 @@ class HandCalculator:
     """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."""
+    ERR_RINSHAN_WITHOUT_KAN = "rinshan_without_kan_not_allowed"
+    """Rinshan kaihou requires a kan meld, or an extracted north wind (nuki dora)."""
+    ERR_IPPATSU_WITH_RINSHAN = "ippatsu_with_rinshan_not_allowed"
+    """Ippatsu and rinshan are mutually exclusive (declaring a kan cancels ippatsu)."""
 
     # tenhou (blessing of heaven) constraints
     ERR_TENHOU_NOT_AS_DEALER = "tenhou_not_as_dealer_not_allowed"
-    """Tenhou is exclusive to the dealer (East player)."""
+    """Tenhou is exclusive to the dealer: ``player_wind`` must be East."""
     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"
@@ -208,8 +231,19 @@ class HandCalculator:
 
         is_aotenjou = isinstance(scores_calculator, Aotenjou)
 
-        opened_melds = [x.tiles_34 for x in melds if x.opened]
-        is_open_hand = len(opened_melds) > 0
+        is_open_hand = any(meld.opened for meld in melds)
+
+        if config.tsumi_number < 0:
+            return HandResponse(error=HandCalculator.ERR_NEGATIVE_TSUMI_NUMBER)
+
+        if config.kyoutaku_number < 0:
+            return HandResponse(error=HandCalculator.ERR_NEGATIVE_KYOUTAKU_NUMBER)
+
+        if config.paarenchan < 0:
+            return HandResponse(error=HandCalculator.ERR_NEGATIVE_PAARENCHAN)
+
+        if config.num_nuki_dora < 0:
+            return HandResponse(error=HandCalculator.ERR_NEGATIVE_NUKI_DORA)
 
         # special situation
         if config.is_nagashi_mangan:
@@ -222,6 +256,10 @@ class HandCalculator:
         if win_tile not in tiles:
             return HandResponse(error=HandCalculator.ERR_NO_WINNING_TILE)
 
+        for meld in melds:
+            if meld_error := HandCalculator._validate_meld(meld, tiles):
+                return HandResponse(error=meld_error)
+
         if config.is_riichi and not config.is_daburu_riichi and is_open_hand:
             return HandResponse(error=HandCalculator.ERR_OPEN_HAND_RIICHI)
 
@@ -249,8 +287,17 @@ class HandCalculator:
         if config.is_houtei and config.is_chankan:
             return HandResponse(error=HandCalculator.ERR_HOUTEI_WITH_CHANKAN)
 
-        # raise error only when player wind is defined (and is *not* EAST)
-        if config.is_tenhou and config.player_wind and not config.is_dealer:
+        if (
+            config.is_rinshan
+            and config.num_nuki_dora == 0
+            and not any(x.type in (Meld.KAN, Meld.SHOUMINKAN) for x in melds)
+        ):
+            return HandResponse(error=HandCalculator.ERR_RINSHAN_WITHOUT_KAN)
+
+        if config.is_rinshan and config.is_ippatsu:
+            return HandResponse(error=HandCalculator.ERR_IPPATSU_WITH_RINSHAN)
+
+        if config.is_tenhou and not config.is_dealer:
             return HandResponse(error=HandCalculator.ERR_TENHOU_NOT_AS_DEALER)
 
         if config.is_tenhou and not config.is_tsumo:
@@ -319,6 +366,7 @@ class HandCalculator:
         )
 
         calculated_hands: list[_CalculatedHand] = []
+        meld_blocks = [meld._sorted_tiles_34 for meld in melds]  # noqa: SLF001
         for hand in hand_options:
             is_chiitoitsu = config.yaku.chiitoitsu.is_condition_met(hand)
             valued_tiles = [HAKU, HATSU, CHUN, config.player_wind, config.round_wind]
@@ -342,7 +390,7 @@ class HandCalculator:
             suit_mask, honor_count = classify_hand_suits(hand)
             has_honors = honor_count > 0
 
-            win_groups = HandCalculator._find_win_groups(win_tile, hand, opened_melds)
+            win_groups = HandCalculator._find_win_groups(win_tile, hand, meld_blocks)
             for win_group in win_groups:
                 cost = None
                 error = None
@@ -596,7 +644,7 @@ class HandCalculator:
                 calculated_hands.append(calculated_hand)
 
         # exception hand
-        if not is_open_hand and config.yaku.kokushi.is_condition_met(None, tiles_34):
+        if not melds and config.yaku.kokushi.is_condition_met(None, tiles_34):
             if tiles_34[win_tile // 4] == 2:
                 hand_yaku.append(config.yaku.daburu_kokushi)
             else:
@@ -687,25 +735,38 @@ class HandCalculator:
         )
 
     @staticmethod
-    def _find_win_groups(win_tile: int, hand: list[list[int]], opened_melds: list[list[int]]) -> list[list[int]]:
+    def _validate_meld(meld: Meld, tiles: Collection[int]) -> str | None:
+        if not meld.is_valid():
+            return HandCalculator.ERR_MELD_INVALID
+
+        if meld.type == Meld.NUKI:
+            return HandCalculator.ERR_NUKI_MELD_NOT_SUPPORTED
+
+        if any(tile not in tiles for tile in meld.tiles):
+            return HandCalculator.ERR_MELD_TILE_NOT_IN_HAND
+
+        return None
+
+    @staticmethod
+    def _find_win_groups(win_tile: int, hand: list[list[int]], meld_blocks: list[list[int]]) -> list[list[int]]:
         win_tile_34 = (win_tile or 0) // 4
 
-        # track which opened melds have been matched using a consumed flags array
-        consumed = [False] * len(opened_melds)
+        # track which declared melds have been matched using a consumed flags array
+        consumed = [False] * len(meld_blocks)
 
-        # collect closed sets and find unique win groups in a single pass
+        # collect undeclared sets and find unique win groups in a single pass
         seen: set[tuple[int, ...]] = set()
         win_groups: list[list[int]] = []
         for x in hand:
-            # check if this set matches an unconsumed opened meld
-            is_opened_meld = False
-            for i, meld in enumerate(opened_melds):
+            # check if this set matches an unconsumed declared meld
+            is_declared_meld = False
+            for i, meld in enumerate(meld_blocks):
                 if not consumed[i] and x == meld:
                     consumed[i] = True
-                    is_opened_meld = True
+                    is_declared_meld = True
                     break
 
-            if is_opened_meld:
+            if is_declared_meld:
                 continue
 
             # for forms like 45666 and ron on 6

{mahjong-2.1.0 → mahjong-2.2.0.dev1}/mahjong/hand_calculating/hand_config.py

@@ -206,7 +206,7 @@ class HandConfig(HandConstants):
     :vartype is_daburu_riichi: bool
     :ivar is_nagashi_mangan: all discards are terminals and honors with no calls against them
     :vartype is_nagashi_mangan: bool
-    :ivar is_tenhou: dealer wins on the initial draw
+    :ivar is_tenhou: dealer wins on the initial draw; requires ``player_wind`` to be East
     :vartype is_tenhou: bool
     :ivar is_renhou: non-dealer wins on the first go-around before any calls
     :vartype is_renhou: bool
@@ -305,7 +305,7 @@ class HandConfig(HandConstants):
         :param is_houtei: win on the discard following the last drawable tile
         :param is_daburu_riichi: player declared double riichi
         :param is_nagashi_mangan: all discards are terminals and honors
-        :param is_tenhou: dealer wins on the initial draw
+        :param is_tenhou: dealer wins on the initial draw; requires ``player_wind`` to be East
         :param is_renhou: non-dealer wins on the first go-around
         :param is_chiihou: non-dealer wins on the initial draw
         :param is_open_riichi: player declared open riichi

{mahjong-2.1.0 → mahjong-2.2.0.dev1}/mahjong/hand_calculating/yaku_list/sanankou.py

@@ -34,7 +34,7 @@ class Sanankou(Yaku):
         open_sets: set[tuple[int, ...]] = set()
         for m in melds:
             if m.opened:
-                open_sets.add(tuple(m.tiles_34))
+                open_sets.add(tuple(m._sorted_tiles_34))  # noqa: SLF001
 
         has_chi_with_win_tile = False
         closed_pon_count = 0

{mahjong-2.1.0 → mahjong-2.2.0.dev1}/mahjong/hand_calculating/yaku_list/yakuman/kokushi.py

@@ -21,9 +21,9 @@ class KokushiMusou(Yaku):
 
         :param hand: not used for kokushi; pass None
         :param tiles_34: hand in 34-format count array
-        :return: True if the hand contains one of each terminal and honor with exactly one duplicate
+        :return: True if the hand is exactly 14 tiles: one of each terminal and honor with exactly one duplicate
         """
-        return (
+        return sum(tiles_34) == 14 and (
             tiles_34[0]
             * tiles_34[8]
             * tiles_34[9]

{mahjong-2.1.0 → mahjong-2.2.0.dev1}/mahjong/meld.py

@@ -1,7 +1,9 @@
 from collections.abc import Sequence
 from functools import cached_property
 
+from mahjong.constants import NORTH
 from mahjong.tile import TilesConverter
+from mahjong.utils import is_chi, is_honor, is_pon
 
 
 class Meld:
@@ -108,10 +110,11 @@ class Meld:
         self.from_who = from_who
 
     def __setattr__(self, name: str, value: object) -> None:
-        """Invalidate the tiles_34 cache when tiles are reassigned."""
+        """Invalidate the tiles_34 caches when tiles are reassigned."""
         super().__setattr__(name, value)
-        if name == "tiles" and "tiles_34" in self.__dict__:
-            del self.__dict__["tiles_34"]
+        if name == "tiles":
+            self.__dict__.pop("tiles_34", None)
+            self.__dict__.pop("_sorted_tiles_34", None)
 
     def __str__(self) -> str:
         """
@@ -145,3 +148,49 @@ class Meld:
         :return: list of tile indices in 34-format
         """
         return [x // 4 for x in self.tiles]
+
+    @cached_property
+    def _sorted_tiles_34(self) -> list[int]:
+        """
+        Return the meld's 34-format tile indices sorted, so a chi given as 987p reads as 789p.
+
+        :return: sorted list of tile indices in 34-format
+        """
+        return sorted(self.tiles_34)
+
+    def is_valid(self) -> bool:
+        """
+        Check that the meld tiles match its type and that only a kan is closed.
+
+        A chi is three consecutive tiles of one suit, a pon is three identical tiles, a kan
+        or shouminkan is four identical tiles, a nuki is one to four north winds. Chi, pon and
+        shouminkan are always called, so only a kan or a nuki may be closed. Unknown types
+        are not valid.
+
+        >>> from mahjong.meld import Meld
+        >>> from mahjong.tile import TilesConverter
+        >>> Meld(meld_type=Meld.CHI, tiles=TilesConverter.string_to_136_array(man="123")).is_valid()
+        True
+
+        >>> Meld(meld_type=Meld.CHI, tiles=TilesConverter.string_to_136_array(man="89", pin="1")).is_valid()
+        False
+
+        >>> Meld(meld_type=Meld.PON, tiles=TilesConverter.string_to_136_array(man="111"), opened=False).is_valid()
+        False
+
+        :return: True if the meld is valid
+        """
+        tiles_34 = self._sorted_tiles_34
+        match self.type:
+            case Meld.CHI:
+                is_valid_shape = is_chi(tiles_34) and not is_honor(tiles_34[0]) and tiles_34[0] // 9 == tiles_34[2] // 9
+            case Meld.PON:
+                is_valid_shape = is_pon(tiles_34)
+            case Meld.KAN | Meld.SHOUMINKAN:
+                is_valid_shape = len(tiles_34) == 4 and len(set(tiles_34)) == 1
+            case Meld.NUKI:
+                is_valid_shape = 0 < len(tiles_34) <= 4 and all(tile == NORTH for tile in tiles_34)
+            case _:
+                return False
+
+        return is_valid_shape and (self.opened or self.type in (Meld.KAN, Meld.NUKI))

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mahjong
-Version: 2.1.0
+Version: 2.2.0.dev1
 Summary: Mahjong hands calculation
 Author-email: Alexey Lisikhin <alexey@nihisil.com>
 Maintainer: Apricot S.
@@ -55,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.1.0 → mahjong-2.2.0.dev1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mahjong"
-version = "2.1.0"
+version = "2.2.0.dev1"
 description = "Mahjong hands calculation"
 authors = [
     { name = "Alexey Lisikhin", email = "alexey@nihisil.com" },
@@ -51,18 +51,24 @@ mahjong = ["py.typed"]
 
 [dependency-groups]
 dev = [
-    { include-group = "lint" },
-    { include-group = "typing" },
+    { include-group = "hooks" },
     { include-group = "test" },
     { include-group = "docs" },
 ]
+hooks = [
+    "prek>=0.5.7,<0.6",
+    { include-group = "lint" },
+    { include-group = "typing" },
+]
 lint = [
     "ruff>=0.17.1,<0.18",
 ]
 typing = [
+    "tomli>=2.5.0",
     "ty>=0.0.42",
 ]
 test = [
+    "tomli>=2.5.0; python_version < '3.11'",
     "pytest>=9.0.2,<10",
     "pytest-cov>=7.0.0,<8",
 ]
@@ -115,6 +121,12 @@ convention = "pep257"
     "T201",    # print
     "INP001",  # implicit-namespace-package
 ]
+"./scripts/*" = [
+    "D",       # pydocstyle
+    "T201",    # print
+    "INP001",  # implicit-namespace-package
+    "S101",    # assert
+]
 "./tests/*" = [
     "D",       # pydocstyle
     "S101",    # assert
@@ -124,7 +136,7 @@ convention = "pep257"
 "mahjong/hand_calculating/yaku_list/*.py" = ["ARG002"] # for `is_condition_met()`
 
 [tool.ty.src]
-include = ["mahjong"]
+include = ["mahjong", "scripts"]
 
 [[tool.ty.overrides]]
 include = ["mahjong/hand_calculating/yaku_list/**"] # for `is_condition_met()`
@@ -135,8 +147,6 @@ invalid-method-override = "ignore"
 [tool.pytest]
 python_files = ["tests_*.py"]
 addopts = [
-    "-p",
-    "no:warnings",
     "--no-header",
     "--tb=short",
     "-qq",