Change the use of class variables to instance variables to resolve issues in free-threaded builds

[Apricot-S]

Summary

Track and implement changes required for supporting the free-threaded build of CPython (PEP 703).
This work was split out from #79 (Python 3.14 support).

Background

• Python 3.14 introduces official support for free-threaded builds.
• Current code has class variables that may cause race conditions or unsafe access in a free-threaded environment.
• To ensure compatibility and stability, these class variables should be migrated to instance variables or local variables.

Tasks

• Identify all class variables that are shared across threads.
• Replace them with instance variables where appropriate.

Investigation Targets

• mahjong/
  • __init__.py
    • (none)
  • agari.py
    • (none)
  • constants.py
    • (none)
  • meld.py
    • Meld
  • shanten.py
    • Shanten
  • tile.py
    • Tile
  • utils.py
    • (none)
  • hand_calculating/
    • __init__.py
      • (none)
    • divider.py
      • HandDivider
    • fu.py
      • (none)
    • hand_config.py
      • OptionalRules
      • HandConfig
    • hand_response.py
      • HandResponse
    • hand.py
      • HandCalculator
    • scores.py
      • (none)
    • yaku_config.py
      • (none)
    • yaku.py
      • Yaku
    • yaku_list/
      • __init__.py
      • yakuman/
        • __init__.py

[Apricot-S]

Investigation results for the Shanten class

The Shanten class defines some class variables, but in practice these are shadowed by instance variables initialized inside _init(). As a result, the actual calculation works correctly even if the class variables are removed.

If the class variables are simply deleted, accessing certain attributes immediately after instantiation raises an AttributeError, since the corresponding instance variables are only created during _init(). For example, tiles and other deprecated attributes that only reflect internal state will fail if accessed before initialization. However, these attributes are deprecated and there is no meaningful reason for users to access them directly.

Therefore, the class variables may simply be removed.

Example error when class variables are deleted and tiles is accessed before initialization:

>>> from mahjong.shanten import Shanten
>>> sht = Shanten()
>>> sht.tiles
<stdin-2>:1: DeprecationWarning: `tiles` is deprecated. This attribute reflects internal state and should not be used.
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
    sht.tiles
  File "C:\xxxxxx\mahjong\mahjong\shanten.py", line 17, in tiles
    return self._tiles
           ^^^^^^^^^^^
AttributeError: 'Shanten' object has no attribute '_tiles'. Did you mean: 'tiles'?
>>>
>>> hand = [0] * 34
>>> hand[0] = 1
>>> sht.calculate_shanten(hand)
0
>>> sht.tiles
[1, 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]
>>>
>>> 

However, in #74 there is a proposal to convert some instance methods into static methods. If that change is adopted, instance variables themselves will no longer exist. In that case, it would be better to avoid two consecutive breaking changes — first in the update from v1.3.0 to v1.4.0 (raising errors before initialization), and then later in the update from v1.4.0 to v2.0.0 (always raising errors). Instead, it may be preferable to keep the current class variables for now with deprecation warnings, and then remove them entirely when moving to static methods.

Note: Thread-safety considerations

• Replacing class variables with instance variables does not make the implementation thread-safe, because instance variables are still updated within methods.
• To achieve true thread-safety, the logic needs to be moved into an internal class that creates a new instance for each calculation.
• This change is planned to be addressed together with the static method conversion proposed in [Feature Proposal] Change instance methods to static methods #74, and is scheduled for v2.0.0.

[Apricot-S]

Investigation result for the Meld class

Class variables to be removed

• who
• tiles
• type
• from_who
• called_tile
• opened

Current behavior

• These class variables are always overwritten by instance variables in __init__, so they are never referenced in normal usage.
• Example:

  Meld.tiles      # None (class variable)
  Meld().tiles    # []   (instance variable)

• All practical usage relies on the instance variables, and there is no valid reason to depend on the class variables.

Migration strategy

• The class variables are implementation artifacts, and their usage should be considered incorrect.
• Therefore, it is acceptable to remove them in v1.4.0 without deprecation warnings.
• The release notes should clearly state:
  “These class variables were internal implementation details and not part of the public API. They have been removed in this release.”

[Apricot-S]

Investigation result for the Tile class

Class variables to be removed

• value
• is_tsumogiri

Current behavior

• These class variables are always overwritten by instance variables in __init__, so they are never referenced in normal usage.
• Example:

  Tile.value              # None (class variable)
  Tile("1m", True).value  # "1m" (instance variable)

• All practical usage relies on the instance variables, and there is no valid reason to depend on the class variables.

Migration strategy

• The class variables are implementation artifacts, and their usage should be considered incorrect.
• Therefore, it is acceptable to remove them in v1.4.0 without deprecation warnings.
• The release notes should clearly state:
  “These class variables were internal implementation details and not part of the public API. They have been removed in this release.”

[Apricot-S]

Proposal for Handling Class Variable Removal

Currently, we have not implemented warnings for class variable access.
Since adding such warnings would be rather cumbersome, I’d like to propose the following release plan:

• v1.4.0

  • Release only the already committed changes (unrelated to class variable removal).
  • No warnings or removals of class variables at this stage.

• v2.0.0

  • Remove the class variables directly, without going through a deprecation-warning phase.
  • Perform this together with the planned staticmethod migration in [Feature Proposal] Change instance methods to static methods #74.

@Nihisil
Would this plan be acceptable?

[Nihisil]

Yes, that sounds good to me. Thank you for all your efforts. I will prepare release 1.4.0 with the committed changes in the next few days. Let me know if you want to squeeze anything else into that release