feat: improve code style and version from value

feat: re-add from_value

add docs

Author: TrueRou

docs/concepts/models.md

@@ -104,11 +104,13 @@
 
 继承自 `Score` 类。
 
-| 字段             | 类型         | 说明             |
-|------------------|--------------|------------------|
-| `title`          | `int`        | 曲目标题         |
-| `level_value`    | `LevelIndex` | 难度定数         |
-| `level_dx_score` | `LevelIndex` | 难度最大 DX 分数 |
+| 字段             | 类型          | 说明             |
+|------------------|---------------|------------------|
+| `title`          | `int`         | 曲目标题         |
+| `level_value`    | `LevelIndex`  | 难度定数         |
+| `level_dx_score` | `LevelIndex`  | 难度最大 DX 分数 |
+| `dx_star`        | `int \| None` | DX Star          |
+| `version`        | `int`         | 难度出现版本     |
 
 ## [PlateObject](https://api.maimai.turou.fun/maimai_py/models.html#PlateObject)
 

maimai_py/enums.py

@@ -1,5 +1,6 @@
+import functools
 from enum import Enum, IntEnum
-from typing import Union
+from typing import Optional, Union
 
 from maimai_ffi.model import region_map
 
@@ -27,9 +28,25 @@ class Version(IntEnum):
     MAIMAI_DX_FUTURE = 30000  # 舞萌DX 2077
 
     @staticmethod
-    def fromVersionNumber(num):
-        for v in reversed(Version.__members__.values()):
-            if num >= v.value: return v
+    @functools.cache
+    def _reversed_values() -> list["Version"]:
+        return list(reversed([v for v in Version.__members__.values()]))
+
+    @staticmethod
+    @functools.cache
+    def from_value(val: int) -> Optional["Version"]:
+        """Get the Version enum member from an integer value.
+
+        The function returns the highest Version whose value is less than or equal to the given integer.
+
+        Args:
+            val (int): The integer value representing the version.
+        Returns:
+            Optional[Version]: The corresponding Version enum member, or None if not found.
+        """
+        for v in Version._reversed_values():
+            if val >= v.value:
+                return v
         return None
 
 

maimai_py/maimai.py

@@ -647,7 +647,7 @@ async def _get_mapping(
                 yield (song, diff, score)
 
     @staticmethod
-    def calcuate_dx_star(dx_score, max_dx_score):
+    def _calcuate_dx_star(dx_score: int, max_dx_score: int) -> int:
         THRESHOLD = [0.85, 0.90, 0.93, 0.95, 0.97]
 
         percentage = dx_score / max_dx_score
@@ -661,15 +661,16 @@ async def _get_extended(scores: Iterable[Score], maimai_songs: MaimaiSongs) -> l
         extended_scores = []
         async for song, diff, score in MaimaiScores._get_mapping(scores, maimai_songs):
             extended_dict = dataclasses.asdict(score)
-            max_dx_score = (diff.tap_num + diff.hold_num + diff.slide_num + diff.break_num + diff.touch_num) * 3
+            level_dx_score = (diff.tap_num + diff.hold_num + diff.slide_num + diff.break_num + diff.touch_num) * 3
+            dx_star = MaimaiScores._calcuate_dx_star(score.dx_score, level_dx_score) if score.dx_score else None
             extended_dict.update(
                 {
                     "level": diff.level,  # Ensure level is set correctly.
                     "title": song.title,
+                    "dx_star": dx_star,
+                    "version": diff.version,
                     "level_value": diff.level_value,
-                    "level_dx_score": max_dx_score,
-                    "dx_star": MaimaiScores.calcuate_dx_star(score.dx_score, max_dx_score),
-                    "version": Version.fromVersionNumber(diff.version),
+                    "level_dx_score": level_dx_score,
                 }
             )
             extended_scores.append(ScoreExtend(**extended_dict))

maimai_py/models.py

@@ -505,8 +505,8 @@ class ScoreExtend(Score):
     title: str
     level_value: float
     level_dx_score: int
-    dx_star: int
-    version: Version
+    dx_star: Optional[int]
+    version: int
 
 
 @dataclass

tests/test_scores.py

@@ -1,6 +1,6 @@
 import pytest
 
-from maimai_py.enums import LevelIndex
+from maimai_py.enums import LevelIndex, Version
 from maimai_py.maimai import MaimaiClient
 from maimai_py.models import Player, PlayerIdentifier
 from maimai_py.providers import ArcadeProvider, DivingFishProvider, LXNSProvider
@@ -13,6 +13,9 @@ async def test_scores_fetching_lxns(maimai: MaimaiClient, lxns: LXNSProvider, lx
     assert my_scores.rating_b35 > 10000
     score = my_scores.by_song(1231, level_index=LevelIndex.MASTER)[0]
     assert score.dx_rating >= 308 if score.dx_rating else True  # 生命不詳 MASTER SSS+
+    assert Version.from_value(score.version) == Version.MAIMAI_DX_UNIVERSE
+    assert score.dx_star >= 1 if score.dx_star else True
+    assert score.version >= 22000
 
     bests = await maimai.bests(PlayerIdentifier(friend_code=664994421382429), provider=lxns)
     assert my_scores.rating == bests.rating