mahjong.tile

class mahjong.tile.Tile(value, is_tsumogiri)[source]

Container for a single discarded tile record.

Not used internally by the library. Provided as a convenience data class for consumers that need to track discards with tsumogiri information.

Variables:

value – tile index (typically in 136-format)
is_tsumogiri – True if the tile was discarded immediately after drawing it

Parameters:

value (Any)
is_tsumogiri (Any)

__init__(value, is_tsumogiri)[source]

Initialize a tile record.

Parameters:

value (Any) – tile index (typically in 136-format)
is_tsumogiri (Any) – True if the tile was discarded immediately after drawing it

Return type:

None

class mahjong.tile.TilesConverter[source]

Utility class for converting between tile representation formats.

All methods are static — no instance is needed. The class supports conversion between mpsz-notation strings, 34-format arrays, and 136-format arrays.

static to_one_line_string(tiles, print_aka_dora=False)[source]

Convert a collection of 136-format tile indices to an mpsz-notation string.

When print_aka_dora is False, red fives are printed as 5. When True, they are printed as 0.

>>> TilesConverter.to_one_line_string([0, 4, 8, 12, 16, 24, 32])
'1234579m'
>>> TilesConverter.to_one_line_string([0, 4, 8, 12, 16, 24, 32], print_aka_dora=True)
'1234079m'

Parameters:

tiles (Collection[int]) – tile indices in 136-format
print_aka_dora (bool) – render red fives as 0 instead of 5

Returns:

mpsz-notation string representing the tiles

Return type:

str

static to_34_array(tiles)[source]

Convert a collection of 136-format tile indices to a 34-format count array.

Each element of the returned list holds the number of copies present for that tile type.

>>> TilesConverter.to_34_array([0, 1, 2, 3])
[4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Parameters:: tiles (Collection[int]) – tile indices in 136-format
Returns:: list of length 34 with tile counts
Return type:: list[int]

static to_136_array(tiles)[source]

Convert a 34-format count array to a list of 136-format tile indices.

For each tile type with count n, the first n physical tile indices are selected (e.g., count 2 of 1m yields indices [0, 1]).

>>> tiles_34 = [2] + [0] * 33
>>> TilesConverter.to_136_array(tiles_34)
[0, 1]

Parameters:: tiles (Sequence[int]) – 34-format count array (length 34)
Returns:: list of tile indices in 136-format
Return type:: list[int]

static string_to_136_array(sou=None, pin=None, man=None, honors=None, has_aka_dora=False)[source]

Convert per-suit digit strings to a list of 136-format tile indices.

Each suit string contains digit characters representing tile ranks. When has_aka_dora is True, 0 or r in a suit string produces the red five for that suit.

>>> TilesConverter.string_to_136_array(man="123")
[0, 4, 8]
>>> TilesConverter.string_to_136_array(man="0", has_aka_dora=True)
[16]

Parameters:

sou (str | None) – souzu (bamboo) tile ranks
pin (str | None) – pinzu (circles) tile ranks
man (str | None) – manzu (characters) tile ranks
honors (str | None) – honor tile ranks (1-7 for East through Red dragon)
has_aka_dora (bool) – enable red five handling (0 and r map to aka dora)

Returns:

list of tile indices in 136-format

Return type:

list[int]

static string_to_34_array(sou=None, pin=None, man=None, honors=None)[source]

Convert per-suit digit strings to a 34-format count array.

Equivalent to calling string_to_136_array() followed by to_34_array().

>>> TilesConverter.string_to_34_array(man="111")
[3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Parameters:

sou (str | None) – souzu (bamboo) tile ranks
pin (str | None) – pinzu (circles) tile ranks
man (str | None) – manzu (characters) tile ranks
honors (str | None) – honor tile ranks (1-7 for East through Red dragon)

Returns:

list of length 34 with tile counts

Return type:

list[int]

static find_34_tile_in_136_array(tile34, tiles)[source]

Find the first 136-format index that corresponds to a given 34-format tile type.

A single 34-format index maps to four possible 136-format indices (e.g., tile type 0 maps to indices 0, 1, 2, 3). Return the first one present in tiles, or None if no match is found.

>>> TilesConverter.find_34_tile_in_136_array(0, [1, 4, 8])
1
>>> TilesConverter.find_34_tile_in_136_array(0, [4, 8]) is None
True

Parameters:

tile34 (int | None) – tile type index in 34-format, or None
tiles (Collection[int]) – collection of tile indices in 136-format to search

Returns:

first matching 136-format index, or None

Return type:

int | None

static one_line_string_to_136_array(string, has_aka_dora=False)[source]

Parse a combined mpsz-notation string into a list of 136-format tile indices.

The string contains digit sequences terminated by suit letters: m (man), p (pin), s (sou), z or h (honors). For example, "123m456p789s11z" represents 1-2-3 man, 4-5-6 pin, 7-8-9 sou, and a pair of East winds.

When has_aka_dora is True, 0 or r in the string produces the red five for the corresponding suit.

>>> TilesConverter.one_line_string_to_136_array("123m456s")
[0, 4, 8, 84, 88, 92]
>>> TilesConverter.one_line_string_to_136_array("0m", has_aka_dora=True)
[16]

Parameters:

string (str) – mpsz-notation string (e.g., "123m456p789s11z")
has_aka_dora (bool) – enable red five handling (0 and r map to aka dora)

Returns:

list of tile indices in 136-format

Return type:

list[int]

static one_line_string_to_34_array(string, has_aka_dora=False)[source]

Parse a combined mpsz-notation string into a 34-format count array.

Equivalent to calling one_line_string_to_136_array() followed by to_34_array().

>>> TilesConverter.one_line_string_to_34_array("111m")
[3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Parameters:

string (str) – mpsz-notation string (e.g., "123m456p789s11z")
has_aka_dora (bool) – enable red five handling (0 and r map to aka dora)

Returns:

list of length 34 with tile counts

Return type:

list[int]