mahjong 2.0.0.dev1__tar.gz → 2.1.0__tar.gz

{mahjong-2.0.0.dev1 → mahjong-2.1.0}/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.1.0/MANIFEST.in

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

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

@@ -1,21 +1,27 @@
 Metadata-Version: 2.4
 Name: mahjong
-Version: 2.0.0.dev1
+Version: 2.1.0
 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
+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
@@ -28,25 +34,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).
+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 **11,120,125 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.
 
+## 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:
@@ -77,3 +85,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.dev1 → mahjong-2.1.0}/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).
+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 **11,120,125 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.
 
+## 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.1.0/mahjong/__init__.py

@@ -0,0 +1,106 @@
+"""
+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
+###################
+
+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
+(e.g., ``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.dev1 → mahjong-2.1.0}/mahjong/agari.py

@@ -2,13 +2,37 @@ 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 hand is a winning hand (agari)
-        :param tiles_34: 34 tiles format array
-        :param open_sets_34: array of arrays of 34 tiles format
-        :return: boolean
+        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

mahjong-2.1.0/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."""

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.dev1 → mahjong-2.1.0}/mahjong/hand_calculating/divider.py

@@ -50,16 +50,81 @@ _Blocks = tuple[_Block, ...]
 
 
 class HandDivider:
+    """
+    Decompose a winning hand into all possible block combinations.
+
+    A valid combination consists of 4 melds (sequences, triplets, or quads) plus 1 pair.
+    Chiitoitsu (seven pairs) is also recognized when no melds are declared.
+    Multiple valid decompositions may exist for the same hand.
+
+    Each decomposition is a list of blocks, where each block is a list of tile indices
+    in 34-format:
+
+    - pair: ``[tile, tile]`` (length 2, identical tiles)
+    - triplet: ``[tile, tile, tile]`` (length 3, identical tiles)
+    - sequence: ``[tile, tile+1, tile+2]`` (length 3, consecutive tiles)
+    - quad: ``[tile, tile, tile, tile]`` (length 4, identical tiles)
+    """
+
     @staticmethod
     def divide_hand(
         tiles_34: Sequence[int],
         melds: Collection[Meld] | None = None,
     ) -> list[list[list[int]]]:
         """
-        Return a list of possible hands.
-        :param tiles_34:
-        :param melds: list of Meld objects
-        :return:
+        Return all valid decompositions of the hand into blocks.
+
+        Decompose the full hand (including any declared melds) into every possible
+        combination of 4 melds + 1 pair, or 7 pairs (chiitoitsu, only when no melds
+        are declared).
+
+        Single decomposition (one triplet, three sequences, and a pair):
+
+        >>> from mahjong.hand_calculating.divider import HandDivider
+        >>> from mahjong.tile import TilesConverter
+        >>> tiles_34 = TilesConverter.one_line_string_to_34_array("234567m23455s777z")
+        >>> result = HandDivider.divide_hand(tiles_34)
+        >>> result
+        [[[1, 2, 3], [4, 5, 6], [19, 20, 21], [22, 22], [33, 33, 33]]]
+
+        Multiple decompositions (triplets vs. sequences):
+
+        >>> tiles_34 = TilesConverter.one_line_string_to_34_array("11122233388899m")
+        >>> result = HandDivider.divide_hand(tiles_34)
+        >>> result
+        [[[0, 0, 0], [1, 1, 1], [2, 2, 2], [7, 7, 7], [8, 8]], [[0, 1, 2], [0, 1, 2], [0, 1, 2], [7, 7, 7], [8, 8]]]
+
+        Ryanpeikou form (decomposes into both 4 melds + 1 pair and chiitoitsu):
+
+        >>> tiles_34 = TilesConverter.one_line_string_to_34_array("11223344556677m")
+        >>> result = HandDivider.divide_hand(tiles_34)
+        >>> len(result)
+        4
+        >>> [[0, 0], [1, 1], [2, 2], [3, 3], [4, 4], [5, 5], [6, 6]] in result
+        True
+        >>> [[0, 1, 2], [0, 1, 2], [3, 4, 5], [3, 4, 5], [6, 6]] in result
+        True
+
+        Hands with declared melds:
+
+        >>> from mahjong.meld import Meld
+        >>> tiles_34 = TilesConverter.string_to_34_array(pin="234777888999", honors="22")
+        >>> chi_1 = Meld(meld_type=Meld.CHI, tiles=TilesConverter.string_to_136_array(pin="789"))
+        >>> chi_2 = Meld(meld_type=Meld.CHI, tiles=TilesConverter.string_to_136_array(pin="234"))
+        >>> result = HandDivider.divide_hand(tiles_34, [chi_1, chi_2])
+        >>> result
+        [[[10, 11, 12], [15, 16, 17], [15, 16, 17], [15, 16, 17], [28, 28]]]
+
+        Invalid hands return an empty list:
+
+        >>> HandDivider.divide_hand([5] * 34)
+        []
+
+        :param tiles_34: hand in 34-format count array (length 34), including tiles from melds
+        :param melds: declared melds (:class:`~mahjong.meld.Meld` objects); their tiles are
+            subtracted from ``tiles_34`` before decomposing the concealed portion
+        :return: list of decompositions, where each decomposition is a list of blocks
+            (each block is a list of tile indices in 34-format)
         """
         if not HandDivider._validate_tiles(tiles_34):
             return []

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

@@ -7,6 +7,16 @@ from mahjong.meld import Meld
 
 
 class FuDetail(TypedDict):
+    """
+    A single fu component with its point value and reason.
+
+    Each entry in the fu breakdown returned by :meth:`FuCalculator.calculate_fu`
+    describes one source of fu (e.g., base fu, a closed pon, or a wait type).
+
+    :param fu: fu points awarded for this component
+    :param reason: identifier string matching one of the :class:`FuCalculator` reason constants
+    """
+
     fu: int
     reason: str
 
@@ -20,26 +30,61 @@ _IS_KAN = 2
 
 
 class FuCalculator:
+    """
+    Calculate fu (minipoints) for a winning hand decomposition.
+
+    Fu are computed from the hand's meld structure, wait type, pair, and winning method.
+    The result is a detailed breakdown of fu components and the total fu rounded up to
+    the nearest 10.
+    """
+
     BASE = "base"
+    """Base fu: 20 for open/tsumo, 30 for closed ron, 25 for chiitoitsu."""
+
     PENCHAN = "penchan"
+    """Penchan (edge wait): 2 fu for completing 1-2-3 with the 3, or 7-8-9 with the 7."""
+
     KANCHAN = "kanchan"
+    """Kanchan (closed wait): 2 fu for waiting on the middle tile of a sequence."""
+
     VALUED_PAIR = "valued_pair"
+    """Valued pair: 2 fu for a pair of dragon, seat wind, or round wind tiles."""
+
     DOUBLE_VALUED_PAIR = "double_valued_pair"
+    """Double valued pair: 4 fu when the pair tile is both seat wind and round wind."""
+
     PAIR_WAIT = "pair_wait"
+    """Pair wait: 2 fu for winning on the pair tile."""
+
     TSUMO = "tsumo"
+    """Tsumo: 2 fu for winning by self-draw."""
+
     HAND_WITHOUT_FU = "hand_without_fu"
+    """Open pinfu: 2 fu for an open hand with no other fu sources."""
 
     CLOSED_PON = "closed_pon"
+    """Closed pon of simple tiles: 4 fu."""
+
     OPEN_PON = "open_pon"
+    """Open pon of simple tiles: 2 fu."""
 
     CLOSED_TERMINAL_PON = "closed_terminal_pon"
+    """Closed pon of terminal or honor tiles: 8 fu."""
+
     OPEN_TERMINAL_PON = "open_terminal_pon"
+    """Open pon of terminal or honor tiles: 4 fu."""
 
     CLOSED_KAN = "closed_kan"
+    """Closed kan of simple tiles: 16 fu."""
+
     OPEN_KAN = "open_kan"
+    """Open kan of simple tiles: 8 fu."""
 
     CLOSED_TERMINAL_KAN = "closed_terminal_kan"
+    """Closed kan of terminal or honor tiles: 32 fu."""
+
     OPEN_TERMINAL_KAN = "open_terminal_kan"
+    """Open kan of terminal or honor tiles: 16 fu."""
 
     # lookup table indexed by [is_terminal_or_honor][is_kan][is_open] -> (fu, reason)
     _PON_KAN_FU_TABLE = (
@@ -63,14 +108,70 @@ class FuCalculator:
         melds: Collection[Meld] | None = None,
     ) -> tuple[list[FuDetail], int]:
         """
-        Calculate hand fu with explanations
-        :param hand:
-        :param win_tile: 136 tile format
-        :param win_group: one set where win tile exists
-        :param config: HandConfig object
-        :param valued_tiles: dragons, player wind, round wind
-        :param melds: opened sets
-        :return:
+        Calculate fu for a winning hand decomposition.
+
+        Analyze the hand's meld structure, wait type, pair, and winning method to produce
+        a detailed breakdown of fu components and the total fu rounded up to the nearest 10.
+
+        Chiitoitsu (seven pairs) always receives 25 fu:
+
+        >>> from mahjong.hand_calculating.fu import FuCalculator
+        >>> from mahjong.hand_calculating.hand_config import HandConfig
+        >>> hand = [[0, 0], [1, 1], [2, 2], [3, 3], [4, 4], [5, 5], [6, 6]]
+        >>> win_tile = 24
+        >>> win_group = [6, 6]
+        >>> fu_details, fu = FuCalculator.calculate_fu(hand, win_tile, win_group, HandConfig())
+        >>> fu
+        25
+
+        A closed ron hand with only chi melds and a non-valued pair (pinfu) receives 30 fu:
+
+        >>> hand = [[0, 1, 2], [3, 4, 5], [9, 10, 11], [18, 19, 20], [27, 27]]
+        >>> win_tile = 20
+        >>> win_group = [3, 4, 5]
+        >>> fu_details, fu = FuCalculator.calculate_fu(hand, win_tile, win_group, HandConfig())
+        >>> fu
+        30
+
+        A closed pon of simple tiles adds 4 fu:
+
+        >>> hand = [[2, 2, 2], [3, 4, 5], [9, 10, 11], [18, 19, 20], [27, 27]]
+        >>> win_tile = 20
+        >>> win_group = [3, 4, 5]
+        >>> fu_details, fu = FuCalculator.calculate_fu(hand, win_tile, win_group, HandConfig())
+        >>> fu
+        40
+        >>> {"fu": 4, "reason": FuCalculator.CLOSED_PON} in fu_details
+        True
+
+        A double valued pair with an open terminal pon:
+
+        >>> from mahjong.meld import Meld
+        >>> hand = [[2, 3, 4], [9, 10, 11], [18, 19, 20], [33, 33, 33], [27, 27]]
+        >>> win_tile = 8
+        >>> win_group = [2, 3, 4]
+        >>> valued_tiles = [27, 27]
+        >>> melds = [Meld(meld_type=Meld.PON, tiles=[132, 133, 134], opened=True)]
+        >>> fu_details, fu = FuCalculator.calculate_fu(hand, win_tile, win_group, HandConfig(), valued_tiles, melds)
+        >>> fu
+        30
+        >>> {"fu": 4, "reason": FuCalculator.DOUBLE_VALUED_PAIR} in fu_details
+        True
+        >>> {"fu": 4, "reason": FuCalculator.OPEN_TERMINAL_PON} in fu_details
+        True
+
+        :param hand: decomposed hand as a collection of tile sets, each a sequence of tile
+            indices in 34-format: a pair (length 2), chi (length 3 with consecutive tiles),
+            pon (length 3 with identical tiles), or kan (length 4);
+            chiitoitsu hands have 7 pairs
+        :param win_tile: the winning tile index in 136-format
+        :param win_group: the tile set (from ``hand``) that contains the winning tile,
+            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, 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)
         """
         # chiitoitsu: always 25 fu
         if len(hand) == 7: