feat/v4.0.0 (#73)

* feat: Bump up xiangting to 4.0.0

* feat: Change the stub type

* feat: Remove undocumented custom Display implementation (#72)

* feat: Change the signature of a function

* test: Ignore PLR2004 (magic-value-comparison) in tests

* docs: Update README

* docs: Change examples

* docs: Update docstring in lib.rs

* docs: Update docstring in calculate.rs

* docs: tweak

* test: Split test files

* test: Change the order of the tests

* test: Add unit tests

* chore: Bump up version to v4.0.0

Author: Apricot-S

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "xiangting-py"
-version = "3.2.1"
+version = "4.0.0"
 description = "Python bindings for xiangting"
 authors = ["Apricot S."]
 edition = "2024"
@@ -27,4 +27,4 @@ crate-type = ["cdylib"]
 
 [dependencies]
 pyo3 = { version = "0.26.0", features = ["extension-module"] }
-xiangting = "3.2.1"
+xiangting = "4.0.0"

Cargo.toml

@@ -42,6 +42,8 @@ xiangting-py$ pip install .
 
 ## Usage
 
+### Basic Usage
+
 The hand is represented as an array of `list[int]`, where each element represents the count of a specific tile.
 The correspondence between the index and the tile is shown in the table below.
 
@@ -67,17 +69,19 @@ Calculates the replacement number, which is equal to the deficiency number (a.k.
 from xiangting import calculate_replacement_number
 
 # 123m456p789s11222z
-hand_14 = [
+hand = [
     1, 1, 1, 0, 0, 0, 0, 0, 0, # m
     0, 0, 0, 1, 1, 1, 0, 0, 0, # p
     0, 0, 0, 0, 0, 0, 1, 1, 1, # s
     2, 3, 0, 0, 0, 0, 0, # z
 ]
 
-replacement_number = calculate_replacement_number(hand_14, None)
+replacement_number = calculate_replacement_number(hand, None)
 assert replacement_number == 0
 ```
 
+### Handling Melds
+
 In the calculation for a hand with melds (副露),
 the melded tiles can be included or excluded when counting tiles to determine if a hand contains four identical ones.
 
@@ -92,8 +96,8 @@ from xiangting import (
     calculate_replacement_number,
 )
 
-# 123m1z (3 melds)
-hand_4 = [
+# 123m1z
+hand = [
     1, 1, 1, 0, 0, 0, 0, 0, 0, # m
     0, 0, 0, 0, 0, 0, 0, 0, 0, # p
     0, 0, 0, 0, 0, 0, 0, 0, 0, # s
@@ -105,18 +109,19 @@ melds = [
     FuluMianzi.Shunzi(12, ClaimedTilePosition.LOW),
     FuluMianzi.Gangzi(24),
     FuluMianzi.Kezi(27),
-    None,
 ]
 
-replacement_number_wo_melds = calculate_replacement_number(hand_4, None)
+replacement_number_wo_melds = calculate_replacement_number(hand, None)
 assert replacement_number_wo_melds == 1
 
-replacement_number_w_melds = calculate_replacement_number(hand_4, melds)
+replacement_number_w_melds = calculate_replacement_number(hand, melds)
 assert replacement_number_w_melds == 2
 ```
 
+### Support for Three-Player Mahjong
+
 In three-player mahjong, the tiles from 2m (二萬) to 8m (八萬) are not used.
-Additionally, melded sequences (明順子) are not allowed.
+In addition, melded sequences (明順子) are not allowed.
 
 ```python
 from xiangting import (
@@ -125,17 +130,17 @@ from xiangting import (
 )
 
 # 1111m111122233z
-hand_13 = [
+hand = [
     4, 0, 0, 0, 0, 0, 0, 0, 0, # m
     0, 0, 0, 0, 0, 0, 0, 0, 0, # p
     0, 0, 0, 0, 0, 0, 0, 0, 0, # s
     4, 3, 2, 0, 0, 0, 0, # z
 ]
 
-replacement_number_4p = calculate_replacement_number(hand_13, None)
+replacement_number_4p = calculate_replacement_number(hand, None)
 assert replacement_number_4p == 2
 
-replacement_number_3p = calculate_replacement_number_3_player(hand_13, None)
+replacement_number_3p = calculate_replacement_number_3_player(hand, None)
 assert replacement_number_3p == 3
 ```
 

README.md

@@ -9,7 +9,7 @@
 project = "xiangting"
 copyright = "2024, Apricot S."
 author = "Apricot S."
-release = "3.2.1"
+release = "4.0.0"
 version = release
 
 

docs/conf.py

@@ -5,12 +5,12 @@
 from xiangting import calculate_replacement_number
 
 # 123m456p789s11222z
-hand_14 = [
+hand = [
     1, 1, 1, 0, 0, 0, 0, 0, 0, # m
     0, 0, 0, 1, 1, 1, 0, 0, 0, # p
     0, 0, 0, 0, 0, 0, 1, 1, 1, # s
     2, 3, 0, 0, 0, 0, 0, # z
 ]  # fmt: skip
 
-replacement_number = calculate_replacement_number(hand_14, None)
+replacement_number = calculate_replacement_number(hand, None)
 assert replacement_number == 0

examples/closed_hand.py examples/basic.pyexamples/closed_hand.py renamed to examples/basic.py

@@ -8,8 +8,8 @@
     calculate_replacement_number,
 )
 
-# 123m1z (3 melds)
-hand_4 = [
+# 123m1z
+hand = [
     1, 1, 1, 0, 0, 0, 0, 0, 0, # m
     0, 0, 0, 0, 0, 0, 0, 0, 0, # p
     0, 0, 0, 0, 0, 0, 0, 0, 0, # s
@@ -21,11 +21,10 @@
     FuluMianzi.Shunzi(12, ClaimedTilePosition.LOW),
     FuluMianzi.Gangzi(24),
     FuluMianzi.Kezi(27),
-    None,
 ]
 
-replacement_number_wo_melds = calculate_replacement_number(hand_4, None)
+replacement_number_wo_melds = calculate_replacement_number(hand, None)
 assert replacement_number_wo_melds == 1
 
-replacement_number_w_melds = calculate_replacement_number(hand_4, melds)
+replacement_number_w_melds = calculate_replacement_number(hand, melds)
 assert replacement_number_w_melds == 2

examples/open_hand.py examples/melds.pyexamples/open_hand.py renamed to examples/melds.py

@@ -8,15 +8,15 @@
 )
 
 # 1111m111122233z
-hand_13 = [
+hand = [
     4, 0, 0, 0, 0, 0, 0, 0, 0, # m
     0, 0, 0, 0, 0, 0, 0, 0, 0, # p
     0, 0, 0, 0, 0, 0, 0, 0, 0, # s
     4, 3, 2, 0, 0, 0, 0, # z
 ]  # fmt: skip
 
-replacement_number_4p = calculate_replacement_number(hand_13, None)
+replacement_number_4p = calculate_replacement_number(hand, None)
 assert replacement_number_4p == 2
 
-replacement_number_3p = calculate_replacement_number_3_player(hand_13, None)
+replacement_number_3p = calculate_replacement_number_3_player(hand, None)
 assert replacement_number_3p == 3

examples/player_4_and_3.py examples/three_player.pyexamples/player_4_and_3.py renamed to examples/three_player.py

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "xiangting"
-version = "3.2.1"
+version = "4.0.0"
 description = "Python bindings for xiangting"
 authors = [{ name = "Apricot S." }]
 license = "MIT"
@@ -103,7 +103,8 @@ convention = "google"
     "PLR2004", # magic-value-comparison
 ]
 "./tests/*" = [
-    "S101", # assert
+    "S101",    # assert
+    "PLR2004", # magic-value-comparison
 ]
 
 [tool.mypy]