mahjong 1.4.0__tar.gz → 2.0.0.dev2__tar.gz

{mahjong-1.4.0 → mahjong-2.0.0.dev2}/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) [2017] [Alexey Lisikhin]
+Copyright (c) 2017 mahjong Python library contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

mahjong-2.0.0.dev2/MANIFEST.in

@@ -0,0 +1,2 @@
+prune examples
+prune tests

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

@@ -1,21 +1,23 @@
 Metadata-Version: 2.4
 Name: mahjong
-Version: 1.4.0
+Version: 2.0.0.dev2
 Summary: Mahjong hands calculation
 Author-email: Alexey Lisikhin <alexey@nihisil.com>
+Maintainer: Apricot S.
 License-Expression: MIT
 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.9
 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
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
 Dynamic: license-file
@@ -27,25 +29,27 @@ Dynamic: license-file
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/mahjong.svg)](https://pypi.python.org/pypi/mahjong)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/mahjong.svg?label=PyPI%20downloads)](https://pypi.org/project/mahjong/)
 [![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).
 
 Also calculating of shanten is supported.
 
-The code was validated on tenhou.net phoenix replays in total on **11,120,125 hands**.
+The code was validated on tenhou.net phoenix replays in total on **26,148,038 hands**.
 
 So, we can say that our hand calculator works the same way that tenhou.net hand calculation.
 
+## Documentation
+
+- [API reference](https://mahjongrepository.github.io/mahjong)
+- [Wiki](https://github.com/MahjongRepository/mahjong/wiki) — Supported rules and usage examples
+
 ## How to install
 
 ```bash
 pip install mahjong
 ```
 
-## Supported rules and usage examples
-
-You can find usage examples and information about all supported rules variations in the [wiki](https://github.com/MahjongRepository/mahjong/wiki)
-
 ## Local development setup
 
 To set up the project locally for development:
@@ -76,3 +80,7 @@ To set up the project locally for development:
     ```bash
     make check   # Runs format, lint, and tests
     ```
+
+## License
+
+This library is licensed under the [MIT license](LICENSE.txt).

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

@@ -5,25 +5,27 @@
 [![Supported Python versions](https://img.shields.io/pypi/pyversions/mahjong.svg)](https://pypi.python.org/pypi/mahjong)
 [![PyPI Downloads](https://img.shields.io/pypi/dm/mahjong.svg?label=PyPI%20downloads)](https://pypi.org/project/mahjong/)
 [![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).
 
 Also calculating of shanten is supported.
 
-The code was validated on tenhou.net phoenix replays in total on **11,120,125 hands**.
+The code was validated on tenhou.net phoenix replays in total on **26,148,038 hands**.
 
 So, we can say that our hand calculator works the same way that tenhou.net hand calculation.
 
+## Documentation
+
+- [API reference](https://mahjongrepository.github.io/mahjong)
+- [Wiki](https://github.com/MahjongRepository/mahjong/wiki) — Supported rules and usage examples
+
 ## How to install
 
 ```bash
 pip install mahjong
 ```
 
-## Supported rules and usage examples
-
-You can find usage examples and information about all supported rules variations in the [wiki](https://github.com/MahjongRepository/mahjong/wiki)
-
 ## Local development setup
 
 To set up the project locally for development:
@@ -54,3 +56,7 @@ To set up the project locally for development:
     ```bash
     make check   # Runs format, lint, and tests
     ```
+
+## License
+
+This library is licensed under the [MIT license](LICENSE.txt).

mahjong-2.0.0.dev2/mahjong/__init__.py

@@ -0,0 +1,87 @@
+"""
+_summary_.
+
+Tile representation
+###################
+
+mpsz-notation
+-------------
+
+The *mpsz-notation* is the same format used by the Tenhou (see https://tenhou.net/2/), where each tile is
+represented by a two-character string: a digit for the rank followed by a letter for the suit.
+
+The suit letters correspond to:
+
+* `m` - manzu (萬子, characters)
+* `p` - pinzu (筒子, circles)
+* `s` - souzu (索子, bamboo)
+* `z` - jihai (字牌, honors)
+
+Within the numbered suits (`m`, `p`, `s`), ranks run from `1` through `9`; the red fives are
+written with rank `0` (e.g., `0m`, `0p`, `0s`).
+
+Honors (`z`) use ranks to distinguish individual tiles:
+
+* `1` - East (東)
+* `2` - South (南)
+* `3` - West (西)
+* `4` - North (北)
+* `5` - White dragon (白, haku)
+* `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``.
+
+34-format
+---------
+
+In the *34-format*, an entry is assigned to each of the 34 tile types.
+It does **not** distinguish a red five from a normal five - both map to the same entry.
+The format is commonly used in two ways:
+
+* A sequence of length 34 where each entry represents the count of the corresponding tile type.
+* A list of tile-type indices, containing one element per tile rather than counts.
+  For example, a pon of 1m is represented as ``[0, 0, 0]``.
+
+The correspondence between the index and the tile is shown in the table below.
+
++-------+----+----+----+----+----+----+----+----+----+
+| Index | 0  | 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8  |
++-------+----+----+----+----+----+----+----+----+----+
+| Tile  | 1m | 2m | 3m | 4m | 5m | 6m | 7m | 8m | 9m |
++-------+----+----+----+----+----+----+----+----+----+
+
++-------+----+----+----+----+----+----+----+----+----+
+| Index | 9  | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 |
++-------+----+----+----+----+----+----+----+----+----+
+| Tile  | 1p | 2p | 3p | 4p | 5p | 6p | 7p | 8p | 9p |
++-------+----+----+----+----+----+----+----+----+----+
+
++-------+----+----+----+----+----+----+----+----+----+
+| Index | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 |
++-------+----+----+----+----+----+----+----+----+----+
+| Tile  | 1s | 2s | 3s | 4s | 5s | 6s | 7s | 8s | 9s |
++-------+----+----+----+----+----+----+----+----+----+
+
++-------+-----------+------------+-----------+------------+------------+------------+----------+
+| Index | 27        | 28         | 29        | 30         | 31         | 32         | 33       |
++-------+-----------+------------+-----------+------------+------------+------------+----------+
+| Tile  | East (1z) | South (2z) | West (3z) | North (4z) | White (5z) | Green (6z) | Red (7z) |
++-------+-----------+------------+-----------+------------+------------+------------+----------+
+
+136-format
+----------
+
+In the *136-format*, each physical tile (four copies of each of the 34 tile types) is assigned a unique integer.
+It is primarily used when treating tiles as individual objects rather than counts, such as melds.
+
+The integers range from 0 to 135.
+IDs are assigned in groups of four: the four copies of 1m receive `0`, `1`, `2`, and `3`;
+the four copies of 2m receive `4`, `5`, `6`, and `7`;
+and so on, up to the four copies of red dragon (7z), which receive `132`, `133`, `134`, and `135`.
+Red fives are assigned the indices `16` (`0m`), `52` (`0p`), and `88` (`0s`).
+"""

mahjong-2.0.0.dev2/mahjong/agari.py

@@ -0,0 +1,226 @@
+from collections.abc import Collection, Sequence
+
+
+class Agari:
+    """Agari (winning hand) detection."""
+
+    @staticmethod
+    def is_agari(tiles_34: Sequence[int], open_sets_34: Collection[Sequence[int]] | None = None) -> bool:
+        """
+        Determine whether the given tiles form a complete hand structure.
+
+        Validate the tile arrangement only (4 melds + 1 pair, seven pairs, or thirteen orphans),
+        not yaku or scoring. When open sets are provided, the declared meld tiles are subtracted
+        before checking.
+
+        The concealed portion can be passed alone without melds, which is valid
+        for any number of melds (0-4) plus 1 pair:
+
+        0 melds + 1 pair (valid hand):
+
+        >>> tiles_34 = [0] * 34
+        >>> tiles_34[0] = 2
+        >>> Agari.is_agari(tiles_34)
+        True
+
+        1 meld (triplet) without a pair is not a valid hand:
+
+        >>> tiles_34 = [0] * 34
+        >>> tiles_34[0] = 3
+        >>> Agari.is_agari(tiles_34)
+        False
+
+        :param tiles_34: hand in 34-format count array (length 34)
+        :param open_sets_34: declared melds as arrays of tile indices in 34-format
+        :return: True if the hand is complete
+        """
+        if open_sets_34:
+            # subtract declared meld tiles so the algorithm checks only the closed portion
+            tiles = list(tiles_34)
+            for meld in open_sets_34:
+                tiles[meld[0]] -= 1
+                tiles[meld[1]] -= 1
+                tiles[meld[2]] -= 1
+                if len(meld) > 3:
+                    tiles[meld[3]] -= 1
+        else:
+            tiles = tiles_34
+
+        j = (
+            (1 << tiles[27])
+            | (1 << tiles[28])
+            | (1 << tiles[29])
+            | (1 << tiles[30])
+            | (1 << tiles[31])
+            | (1 << tiles[32])
+            | (1 << tiles[33])
+        )
+
+        if j >= 0x10:
+            return False
+
+        # 13 orphans
+        if ((j & 3) == 2) and (
+            tiles[0]
+            * tiles[8]
+            * tiles[9]
+            * tiles[17]
+            * tiles[18]
+            * tiles[26]
+            * tiles[27]
+            * tiles[28]
+            * tiles[29]
+            * tiles[30]
+            * tiles[31]
+            * tiles[32]
+            * tiles[33]
+            == 2
+        ):
+            return True
+
+        # seven pairs
+        if not (j & 10) and sum([tiles[i] == 2 for i in range(34)]) == 7:
+            return True
+
+        if j & 2:
+            return False
+
+        n00 = tiles[0] + tiles[3] + tiles[6]
+        n01 = tiles[1] + tiles[4] + tiles[7]
+        n02 = tiles[2] + tiles[5] + tiles[8]
+
+        n10 = tiles[9] + tiles[12] + tiles[15]
+        n11 = tiles[10] + tiles[13] + tiles[16]
+        n12 = tiles[11] + tiles[14] + tiles[17]
+
+        n20 = tiles[18] + tiles[21] + tiles[24]
+        n21 = tiles[19] + tiles[22] + tiles[25]
+        n22 = tiles[20] + tiles[23] + tiles[26]
+
+        n0 = (n00 + n01 + n02) % 3
+        if n0 == 1:
+            return False
+
+        n1 = (n10 + n11 + n12) % 3
+        if n1 == 1:
+            return False
+
+        n2 = (n20 + n21 + n22) % 3
+        if n2 == 1:
+            return False
+
+        if (n0 == 2) + (n1 == 2) + (n2 == 2) + (tiles[27] == 2) + (tiles[28] == 2) + (tiles[29] == 2) + (
+            tiles[30] == 2
+        ) + (tiles[31] == 2) + (tiles[32] == 2) + (tiles[33] == 2) != 1:
+            return False
+
+        nn0 = (n00 * 1 + n01 * 2) % 3
+        m0 = Agari._to_meld(tiles, 0)
+        nn1 = (n10 * 1 + n11 * 2) % 3
+        m1 = Agari._to_meld(tiles, 9)
+        nn2 = (n20 * 1 + n21 * 2) % 3
+        m2 = Agari._to_meld(tiles, 18)
+
+        if j & 4:
+            return (
+                not (n0 | nn0 | n1 | nn1 | n2 | nn2)
+                and Agari._is_mentsu(m0)
+                and Agari._is_mentsu(m1)
+                and Agari._is_mentsu(m2)
+            )
+
+        if n0 == 2:
+            return (
+                not (n1 | nn1 | n2 | nn2)
+                and Agari._is_mentsu(m1)
+                and Agari._is_mentsu(m2)
+                and Agari._is_atama_mentsu(nn0, m0)
+            )
+
+        if n1 == 2:
+            return (
+                not (n2 | nn2 | n0 | nn0)
+                and Agari._is_mentsu(m2)
+                and Agari._is_mentsu(m0)
+                and Agari._is_atama_mentsu(nn1, m1)
+            )
+
+        return (
+            not (n0 | nn0 | n1 | nn1)
+            and Agari._is_mentsu(m0)
+            and Agari._is_mentsu(m1)
+            and Agari._is_atama_mentsu(nn2, m2)
+        )
+
+    @staticmethod
+    def _is_mentsu(m: int) -> bool:
+        a = m & 7
+        b = 0
+        c = 0
+        if a in {1, 4}:
+            b = c = 1
+        elif a == 2:
+            b = c = 2
+        m >>= 3
+        a = (m & 7) - b
+
+        if a < 0:
+            return False
+
+        for _ in range(6):
+            b = c
+            c = 0
+            if a in {1, 4}:
+                b += 1
+                c += 1
+            elif a == 2:
+                b += 2
+                c += 2
+            m >>= 3
+            a = (m & 7) - b
+            if a < 0:
+                return False
+
+        m >>= 3
+        a = (m & 7) - c
+
+        return a in {0, 3}
+
+    @staticmethod
+    def _is_atama_mentsu(nn: int, m: int) -> bool:
+        if nn == 0:
+            if (m & (7 << 6)) >= (2 << 6) and Agari._is_mentsu(m - (2 << 6)):
+                return True
+            if (m & (7 << 15)) >= (2 << 15) and Agari._is_mentsu(m - (2 << 15)):
+                return True
+            if (m & (7 << 24)) >= (2 << 24) and Agari._is_mentsu(m - (2 << 24)):
+                return True
+        elif nn == 1:
+            if (m & (7 << 3)) >= (2 << 3) and Agari._is_mentsu(m - (2 << 3)):
+                return True
+            if (m & (7 << 12)) >= (2 << 12) and Agari._is_mentsu(m - (2 << 12)):
+                return True
+            if (m & (7 << 21)) >= (2 << 21) and Agari._is_mentsu(m - (2 << 21)):
+                return True
+        elif nn == 2:
+            if (m & 7) >= 2 and Agari._is_mentsu(m - 2):
+                return True
+            if (m & (7 << 9)) >= (2 << 9) and Agari._is_mentsu(m - (2 << 9)):
+                return True
+            if (m & (7 << 18)) >= (2 << 18) and Agari._is_mentsu(m - (2 << 18)):
+                return True
+        return False
+
+    @staticmethod
+    def _to_meld(tiles: Sequence[int], d: int) -> int:
+        return (
+            tiles[d]
+            | (tiles[d + 1] << 3)
+            | (tiles[d + 2] << 6)
+            | (tiles[d + 3] << 9)
+            | (tiles[d + 4] << 12)
+            | (tiles[d + 5] << 15)
+            | (tiles[d + 6] << 18)
+            | (tiles[d + 7] << 21)
+            | (tiles[d + 8] << 24)
+        )

mahjong-2.0.0.dev2/mahjong/constants.py

@@ -0,0 +1,50 @@
+TERMINAL_INDICES = frozenset([0, 8, 9, 17, 18, 26])
+"""Tile indices (34-format) of terminal tiles — 1 and 9 of each suit (man, pin, sou)."""
+
+EAST = 27
+"""Tile index (34-format) for East wind."""
+
+SOUTH = 28
+"""Tile index (34-format) for South wind."""
+
+WEST = 29
+"""Tile index (34-format) for West wind."""
+
+NORTH = 30
+"""Tile index (34-format) for North wind."""
+
+HAKU = 31
+"""Tile index (34-format) for Haku (white dragon)."""
+
+HATSU = 32
+"""Tile index (34-format) for Hatsu (green dragon)."""
+
+CHUN = 33
+"""Tile index (34-format) for Chun (red dragon)."""
+
+WINDS = frozenset([EAST, SOUTH, WEST, NORTH])
+"""Tile indices (34-format) of all four wind tiles."""
+
+DRAGONS = frozenset([HAKU, HATSU, CHUN])
+"""Tile indices (34-format) of all three dragon tiles."""
+
+HONOR_INDICES = WINDS | DRAGONS
+"""Tile indices (34-format) of all honor tiles — winds and dragons."""
+
+TERMINAL_AND_HONOR_INDICES = TERMINAL_INDICES | HONOR_INDICES
+"""Tile indices (34-format) of all terminal and honor tiles."""
+
+FIVE_RED_MAN = 16
+"""Tile index (136-format) for the red five of man (characters)."""
+
+FIVE_RED_PIN = 52
+"""Tile index (136-format) for the red five of pin (circles)."""
+
+FIVE_RED_SOU = 88
+"""Tile index (136-format) for the red five of sou (bamboo)."""
+
+AKA_DORAS = frozenset([FIVE_RED_MAN, FIVE_RED_PIN, FIVE_RED_SOU])
+"""Tile indices (136-format) of all three red five (aka dora) tiles."""
+
+DISPLAY_WINDS = {EAST: "East", SOUTH: "South", WEST: "West", NORTH: "North"}
+"""Mapping from wind tile indices (34-format) to their English display names."""