maimai_py.maimai

   1import asyncio
   2import dataclasses
   3import hashlib
   4import warnings
   5from collections import defaultdict
   6from functools import cached_property
   7from typing import Any, AsyncGenerator, Callable, Generic, Iterable, Literal, Optional, Type, TypeVar
   8
   9from aiocache import BaseCache, SimpleMemoryCache
  10from httpx import AsyncClient
  11
  12from maimai_py.models import *
  13from maimai_py.providers import *
  14from maimai_py.utils import UNSET, _UnsetSentinel
  15
  16PlayerItemType = TypeVar("PlayerItemType", bound=PlayerItem)
  17
  18T = TypeVar("T", bound=Score)
  19
  20
  21class MaimaiItems(Generic[PlayerItemType]):
  22    _client: "MaimaiClient"
  23    _namespace: str
  24
  25    def __init__(self, client: "MaimaiClient", namespace: str) -> None:
  26        """@private"""
  27        self._client = client
  28        self._namespace = namespace
  29
  30    async def _configure(self, provider: Union[IItemListProvider, _UnsetSentinel] = UNSET) -> "MaimaiItems":
  31        cache_obj, cache_ttl = self._client._cache, self._client._cache_ttl
  32        # Check if the provider is unset, which means we want to access the cache directly.
  33        if isinstance(provider, _UnsetSentinel):
  34            if await cache_obj.get("provider", None, namespace=self._namespace) is not None:
  35                return self
  36        # Really assign the unset provider to the default one.
  37        provider = LXNSProvider() if PlayerItemType in [PlayerIcon, PlayerNamePlate, PlayerFrame] else LocalProvider()
  38        # Check if the current provider hash is different from the previous one, which means we need to reconfigure.
  39        current_provider_hash = provider._hash()
  40        previous_provider_hash = await cache_obj.get("provider", "", namespace=self._namespace)
  41        # If different or previous is empty, we need to reconfigure the items.
  42        if current_provider_hash != previous_provider_hash:
  43            val: dict[int, Any] = await getattr(provider, f"get_{self._namespace}")(self._client)
  44            await asyncio.gather(
  45                cache_obj.set("provider", current_provider_hash, ttl=cache_ttl, namespace=self._namespace),  # provider
  46                cache_obj.set("ids", [key for key in val.keys()], namespace=self._namespace),  # ids
  47                cache_obj.multi_set(val.items(), namespace=self._namespace),  # items
  48            )
  49        return self
  50
  51    async def get_all(self) -> list[PlayerItemType]:
  52        """All items as list.
  53
  54        This method will iterate all items in the cache, and yield each item one by one. Unless you really need to iterate all items, you should use `by_id` or `filter` instead.
  55
  56        Returns:
  57            A list with all items in the cache, return an empty list if no item is found.
  58        """
  59        item_ids: Optional[list[int]] = await self._client._cache.get("ids", namespace=self._namespace)
  60        assert item_ids is not None, f"Items not found in cache {self._namespace}, please call configure() first."
  61        return await self._client._multi_get(item_ids, namespace=self._namespace)
  62
  63    async def get_batch(self, ids: Iterable[int]) -> list[PlayerItemType]:
  64        """Get items by their IDs.
  65
  66        Args:
  67            ids: the IDs of the items.
  68        Returns:
  69            A list of items if they exist, otherwise return an empty list.
  70        """
  71        return await self._client._multi_get(ids, namespace=self._namespace)
  72
  73    async def by_id(self, id: int) -> Optional[PlayerItemType]:
  74        """Get an item by its ID.
  75
  76        Args:
  77            id: the ID of the item.
  78        Returns:
  79            the item if it exists, otherwise return None.
  80        """
  81        return await self._client._cache.get(id, namespace=self._namespace)
  82
  83    async def filter(self, **kwargs) -> list[PlayerItemType]:
  84        """Filter items by their attributes.
  85
  86        Ensure that the attribute is of the item, and the value is of the same type. All conditions are connected by AND.
  87
  88        Args:
  89            kwargs: the attributes to filter the items by.
  90        Returns:
  91            an async generator yielding items that match all the conditions, yields no items if no item is found.
  92        """
  93        cond = lambda item: all(getattr(item, key) == value for key, value in kwargs.items() if value is not None)
  94        return [item for item in await self.get_all() if cond(item)]
  95
  96
  97class MaimaiSongs:
  98    _client: "MaimaiClient"
  99
 100    def __init__(self, client: "MaimaiClient") -> None:
 101        """@private"""
 102        self._client = client
 103
 104    async def _configure(
 105        self,
 106        provider: Union[ISongProvider, _UnsetSentinel],
 107        alias_provider: Union[IAliasProvider, None, _UnsetSentinel],
 108        curve_provider: Union[ICurveProvider, None, _UnsetSentinel],
 109    ) -> "MaimaiSongs":
 110        cache_obj, cache_ttl = self._client._cache, self._client._cache_ttl
 111        # Check if all providers are unset, which means we want to access the cache directly.
 112        if isinstance(provider, _UnsetSentinel) and isinstance(alias_provider, _UnsetSentinel) and isinstance(curve_provider, _UnsetSentinel):
 113            if await cache_obj.get("provider", None, namespace="songs") is not None:
 114                return self
 115        # Really assign the unset providers to the default ones.
 116        provider = provider if not isinstance(provider, _UnsetSentinel) else LXNSProvider()
 117        alias_provider = alias_provider if not isinstance(alias_provider, _UnsetSentinel) else YuzuProvider()
 118        curve_provider = curve_provider if not isinstance(curve_provider, _UnsetSentinel) else None  # Don't fetch curves if not provided.
 119        # Check if the current provider hash is different from the previous one, which means we need to reconfigure.
 120        current_provider_hash = hashlib.md5(
 121            (provider._hash() + (alias_provider._hash() if alias_provider else "") + (curve_provider._hash() if curve_provider else "")).encode()
 122        ).hexdigest()
 123        previous_provider_hash = await cache_obj.get("provider", "", namespace="songs")
 124        # If different or previous is empty, we need to reconfigure the songs.
 125        if current_provider_hash != previous_provider_hash:
 126            # Get the resources from the providers in parallel.
 127            songs, song_aliases, song_curves = await asyncio.gather(
 128                provider.get_songs(self._client),
 129                alias_provider.get_aliases(self._client) if alias_provider else asyncio.sleep(0, result={}),
 130                curve_provider.get_curves(self._client) if curve_provider else asyncio.sleep(0, result={}),
 131            )
 132
 133            # Build the song objects and set their aliases and curves if provided.
 134            for song in songs:
 135                if alias_provider is not None and (aliases := song_aliases.get(song.id, None)):
 136                    song.aliases = aliases
 137                if curve_provider is not None:
 138                    if curves := song_curves.get((song.id, SongType.DX), None):
 139                        diffs = song.get_difficulties(SongType.DX)
 140                        [diff.__setattr__("curve", curves[i]) for i, diff in enumerate(diffs) if i < len(curves)]
 141                    if curves := song_curves.get((song.id, SongType.STANDARD), None):
 142                        diffs = song.get_difficulties(SongType.STANDARD)
 143                        [diff.__setattr__("curve", curves[i]) for i, diff in enumerate(diffs) if i < len(curves)]
 144                    if curves := song_curves.get((song.id, SongType.UTAGE), None):
 145                        diffs = song.get_difficulties(SongType.UTAGE)
 146                        [diff.__setattr__("curve", curves[i]) for i, diff in enumerate(diffs) if i < len(curves)]
 147
 148            # Set the cache with the songs, aliases, and versions.
 149            await asyncio.gather(
 150                cache_obj.set("provider", current_provider_hash, ttl=cache_ttl, namespace="songs"),  # provider
 151                cache_obj.set("ids", [song.id for song in songs], namespace="songs"),  # ids
 152                cache_obj.multi_set(iter((song.id, song) for song in songs), namespace="songs"),  # songs
 153                cache_obj.multi_set(iter((song.title, song.id) for song in songs), namespace="tracks"),  # titles
 154                cache_obj.multi_set(iter((li, id) for id, ul in song_aliases.items() for li in ul), namespace="aliases"),  # aliases
 155                cache_obj.set(
 156                    "versions",
 157                    {f"{song.id} {diff.type} {diff.level_index}": diff.version for song in songs for diff in song.get_difficulties()},
 158                    namespace="songs",
 159                ),  # versions
 160            )
 161        return self
 162
 163    async def get_all(self) -> list[Song]:
 164        """All songs as list.
 165
 166        This method will iterate all songs in the cache, and yield each song one by one. Unless you really need to iterate all songs, you should use `by_id` or `filter` instead.
 167
 168        Returns:
 169            A list of all songs in the cache, return an empty list if no song is found.
 170        """
 171        song_ids: Optional[list[int]] = await self._client._cache.get("ids", namespace="songs")
 172        assert song_ids is not None, "Songs not found in cache, please call configure() first."
 173        return await self._client._multi_get(song_ids, namespace="songs")
 174
 175    async def get_batch(self, ids: Iterable[int]) -> list[Song]:
 176        """Get songs by their IDs.
 177
 178        Args:
 179            ids: the IDs of the songs.
 180        Returns:
 181            A list of songs if they exist, otherwise return an empty list.
 182        """
 183        return await self._client._multi_get(ids, namespace="songs")
 184
 185    async def by_id(self, id: int) -> Optional[Song]:
 186        """Get a song by its ID.
 187
 188        Args:
 189            id: the ID of the song, always smaller than `10000`, should (`% 10000`) if necessary.
 190        Returns:
 191            the song if it exists, otherwise return None.
 192        """
 193        return await self._client._cache.get(id, namespace="songs")
 194
 195    async def by_title(self, title: str) -> Optional[Song]:
 196        """Get a song by its title.
 197
 198        Args:
 199            title: the title of the song.
 200        Returns:
 201            the song if it exists, otherwise return None.
 202        """
 203        song_id = await self._client._cache.get(title, namespace="tracks")
 204        song_id = 383 if title == "Link(CoF)" else song_id
 205        return await self._client._cache.get(song_id, namespace="songs") if song_id else None
 206
 207    async def by_alias(self, alias: str) -> Optional[Song]:
 208        """Get song by one possible alias.
 209
 210        Args:
 211            alias: one possible alias of the song.
 212        Returns:
 213            the song if it exists, otherwise return None.
 214        """
 215        if song_id := await self._client._cache.get(alias, namespace="aliases"):
 216            if song := await self._client._cache.get(song_id, namespace="songs"):
 217                return song
 218
 219    async def by_artist(self, artist: str) -> list[Song]:
 220        """Get songs by their artist, case-sensitive.
 221
 222        Args:
 223            artist: the artist of the songs.
 224        Returns:
 225            an async generator yielding songs that match the artist.
 226        """
 227        return [song for song in await self.get_all() if song.artist == artist]
 228
 229    async def by_genre(self, genre: Genre) -> list[Song]:
 230        """Get songs by their genre, case-sensitive.
 231
 232        Args:
 233            genre: the genre of the songs.
 234        Returns:
 235            an async generator yielding songs that match the genre.
 236        """
 237        return [song for song in await self.get_all() if song.genre == genre]
 238
 239    async def by_bpm(self, minimum: int, maximum: int) -> list[Song]:
 240        """Get songs by their BPM.
 241
 242        Args:
 243            minimum: the minimum (inclusive) BPM of the songs.
 244            maximum: the maximum (inclusive) BPM of the songs.
 245        Returns:
 246            an async generator yielding songs that match the BPM.
 247        """
 248        return [song for song in await self.get_all() if minimum <= song.bpm <= maximum]
 249
 250    async def by_versions(self, versions: Version) -> list[Song]:
 251        """Get songs by their versions, versions are fuzzy matched version of major maimai version.
 252
 253        Args:
 254            versions: the versions of the songs.
 255        Returns:
 256            an async generator yielding songs that match the versions.
 257        """
 258        cond = lambda song: versions.value <= song.version < all_versions[all_versions.index(versions) + 1].value
 259        return [song for song in await self.get_all() if cond(song)]
 260
 261    async def by_keywords(self, keywords: str) -> list[Song]:
 262        """Get songs by their keywords, keywords are matched with song title, artist and aliases.
 263
 264        Args:
 265            keywords: the keywords to match the songs.
 266        Returns:
 267            a list of songs that match the keywords, case-insensitive.
 268        """
 269        exact_matches = []
 270        fuzzy_matches = []
 271
 272        # Process all songs in a single pass
 273        for song in await self.get_all():
 274            # Check for exact matches
 275            if (
 276                keywords.lower() == song.title.lower()
 277                or keywords.lower() == song.artist.lower()
 278                or any(keywords.lower() == alias.lower() for alias in (song.aliases or []))
 279            ):
 280                exact_matches.append(song)
 281            # Check for fuzzy matches
 282            elif keywords.lower() in f"{song.title} + {song.artist} + {''.join(a for a in (song.aliases or []))}".lower():
 283                fuzzy_matches.append(song)
 284
 285        # Return exact matches if found, otherwise return fuzzy matches
 286        return exact_matches + fuzzy_matches if exact_matches else fuzzy_matches
 287
 288    async def filter(self, **kwargs) -> list[Song]:
 289        """Filter songs by their attributes.
 290
 291        Ensure that the attribute is of the song, and the value is of the same type. All conditions are connected by AND.
 292
 293        Args:
 294            kwargs: the attributes to filter the songs by.
 295        Returns:
 296            a list of songs that match all the conditions.
 297        """
 298        cond = lambda song: all(getattr(song, key) == value for key, value in kwargs.items() if value is not None)
 299        return [song for song in await self.get_all() if cond(song)]
 300
 301
 302class MaimaiPlates:
 303    _client: "MaimaiClient"
 304
 305    _kind: str  # The kind of the plate, e.g. "将", "神".
 306    _version: str  # The version of the plate, e.g. "真", "舞".
 307    _versions: set[Version] = set()  # The matched versions set of the plate.
 308    _matched_songs: list[Song] = []
 309    _matched_scores: list[ScoreExtend] = []
 310
 311    def __init__(self, client: "MaimaiClient") -> None:
 312        """@private"""
 313        self._client = client
 314
 315    async def _configure(self, plate: str, scores: list[Score]) -> "MaimaiPlates":
 316        maimai_songs = await self._client.songs()
 317        self._version = plate_aliases.get(plate[0], plate[0])
 318        self._kind = plate_aliases.get(plate[1:], plate[1:])
 319
 320        versions = list()  # in case of invalid plate, we will raise an error
 321        if self._version == "真":
 322            versions = [plate_to_version["初"], plate_to_version["真"]]
 323        if self._version in ["霸", "舞"]:
 324            versions = [ver for ver in plate_to_version.values() if ver.value < 20000]
 325        if plate_to_version.get(self._version):
 326            versions = [plate_to_version[self._version]]
 327        if not versions or self._kind not in ["将", "者", "极", "舞舞", "神"]:
 328            raise InvalidPlateError(f"Invalid plate: {self._version}{self._kind}")
 329        versions.append([ver for ver in plate_to_version.values() if ver.value > versions[-1].value][0])
 330        self._versions = set(versions)
 331
 332        song_diff_versions: dict[str, int] = await self._client._cache.get("versions", namespace="songs") or {}
 333        versioned_matched_songs = set()
 334        for k, v in song_diff_versions.items():
 335            if any(v >= o.value and v < versions[i + 1].value for i, o in enumerate(versions[:-1])):
 336                versioned_matched_songs.add(int(k.split(" ")[0]))
 337        self._matched_songs = await self._client._multi_get(list(versioned_matched_songs), namespace="songs")
 338
 339        versioned_joined_scores: dict[str, Score] = {}
 340        for score in scores:
 341            score_key = f"{score.id} {score.type} {score.level_index}"
 342            if score_version := song_diff_versions.get(score_key, None):
 343                if any(score_version >= o.value and score_version < versions[i + 1].value for i, o in enumerate(versions[:-1])):
 344                    if not (score.level_index == LevelIndex.ReMASTER and self.no_remaster):
 345                        versioned_joined_scores[score_key] = score._join(versioned_joined_scores.get(score_key, None))
 346        self._matched_scores = await MaimaiScores._get_extended(versioned_joined_scores.values(), maimai_songs)
 347
 348        return self
 349
 350    @cached_property
 351    def _major_type(self) -> SongType:
 352        return SongType.DX if any(ver.value > 20000 for ver in self._versions) else SongType.STANDARD
 353
 354    @cached_property
 355    def no_remaster(self) -> bool:
 356        """Whether it is required to play ReMASTER levels in the plate.
 357
 358        Only 舞 and 霸 plates require ReMASTER levels, others don't.
 359        """
 360        return self._version not in ["舞", "霸"]
 361
 362    def _get_levels(self, song: Song) -> set[LevelIndex]:
 363        levels = set(diff.level_index for diff in song.get_difficulties(self._major_type))
 364        if self.no_remaster and LevelIndex.ReMASTER in levels:
 365            levels.remove(LevelIndex.ReMASTER)
 366        return levels
 367
 368    async def get_remained(self) -> list[PlateObject]:
 369        """Get the remained songs and scores of the player on this plate.
 370
 371        If player has ramained levels on one song, the song and ramained `level_index` will be included in the result, otherwise it won't.
 372
 373        The distinct scores which NOT met the plate requirement will be included in the result, the finished scores won't.
 374
 375        Returns:
 376            A list of `PlateObject` containing the song and the scores.
 377        """
 378        # Group scores by song ID to pre-fill the PlateObject.
 379        grouped = defaultdict(list)
 380        [grouped[score.id].append(score) for score in self._matched_scores]
 381        # Create PlateObject for each song with its levels and scores.
 382        results = {song.id: PlateObject(song=song, levels=self._get_levels(song), scores=grouped.get(song.id, [])) for song in self._matched_songs}
 383
 384        def extract(score: ScoreExtend) -> None:
 385            results[score.id].scores.remove(score)
 386            if score.level_index in results[score.id].levels:
 387                results[score.id].levels.remove(score.level_index)
 388
 389        if self._kind == "者":
 390            [extract(score) for score in self._matched_scores if score.rate.value <= RateType.A.value]
 391        elif self._kind == "将":
 392            [extract(score) for score in self._matched_scores if score.rate.value <= RateType.SSS.value]
 393        elif self._kind == "极":
 394            [extract(score) for score in self._matched_scores if score.fc and score.fc.value <= FCType.FC.value]
 395        elif self._kind == "舞舞":
 396            [extract(score) for score in self._matched_scores if score.fs and score.fs.value <= FSType.FSD.value]
 397        elif self._kind == "神":
 398            [extract(score) for score in self._matched_scores if score.fc and score.fc.value <= FCType.AP.value]
 399
 400        return [plate for plate in results.values() if len(plate.levels) > 0]
 401
 402    async def get_cleared(self) -> list[PlateObject]:
 403        """Get the cleared songs and scores of the player on this plate.
 404
 405        If player has levels (one or more) that met the requirement on the song, the song and cleared `level_index` will be included in the result, otherwise it won't.
 406
 407        The distinct scores which met the plate requirement will be included in the result, the unfinished scores won't.
 408
 409        Returns:
 410            A list of `PlateObject` containing the song and the scores.
 411        """
 412        results = {song.id: PlateObject(song=song, levels=set(), scores=[]) for song in self._matched_songs}
 413
 414        def insert(score: ScoreExtend) -> None:
 415            results[score.id].scores.append(score)
 416            results[score.id].levels.add(score.level_index)
 417
 418        if self._kind == "者":
 419            [insert(score) for score in self._matched_scores if score.rate.value <= RateType.A.value]
 420        elif self._kind == "将":
 421            [insert(score) for score in self._matched_scores if score.rate.value <= RateType.SSS.value]
 422        elif self._kind == "极":
 423            [insert(score) for score in self._matched_scores if score.fc and score.fc.value <= FCType.FC.value]
 424        elif self._kind == "舞舞":
 425            [insert(score) for score in self._matched_scores if score.fs and score.fs.value <= FSType.FSD.value]
 426        elif self._kind == "神":
 427            [insert(score) for score in self._matched_scores if score.fc and score.fc.value <= FCType.AP.value]
 428
 429        return [plate for plate in results.values() if len(plate.levels) > 0]
 430
 431    async def get_played(self) -> list[PlateObject]:
 432        """Get the played songs and scores of the player on this plate.
 433
 434        If player has ever played levels on the song, whether they met or not, the song and played `level_index` will be included in the result.
 435
 436        All distinct scores will be included in the result.
 437
 438        Returns:
 439            A list of `PlateObject` containing the song and the scores.
 440        """
 441        results = {song.id: PlateObject(song=song, levels=set(), scores=[]) for song in self._matched_songs}
 442
 443        for score in self._matched_scores:
 444            results[score.id].scores.append(score)
 445            results[score.id].levels.add(score.level_index)
 446
 447        return [plate for plate in results.values() if len(plate.levels) > 0]
 448
 449    async def get_all(self) -> list[PlateObject]:
 450        """Get all songs and scores on this plate, usually used for overall statistics of the plate.
 451
 452        All songs will be included in the result, with played `level_index`, whether they met or not.
 453
 454        All distinct scores will be included in the result.
 455
 456        Returns:
 457            A list of `PlateObject` containing the song and the scores.
 458        """
 459        results = {song.id: PlateObject(song=song, levels=set(), scores=[]) for song in self._matched_songs}
 460
 461        for score in self._matched_scores:
 462            results[score.id].scores.append(score)
 463            results[score.id].levels.add(score.level_index)
 464
 465        return [plate for plate in results.values()]
 466
 467    async def count_played(self) -> int:
 468        """Get the number of played levels on this plate.
 469
 470        Returns:
 471            The number of played levels on this plate.
 472        """
 473        return len([level for plate in await self.get_played() for level in plate.levels])
 474
 475    async def count_cleared(self) -> int:
 476        """Get the number of cleared levels on this plate.
 477
 478        Returns:
 479            The number of cleared levels on this plate.
 480        """
 481        return len([level for plate in await self.get_cleared() for level in plate.levels])
 482
 483    async def count_remained(self) -> int:
 484        """Get the number of remained levels on this plate.
 485
 486        Returns:
 487            The number of remained levels on this plate.
 488        """
 489        return len([level for plate in await self.get_remained() for level in plate.levels])
 490
 491    async def count_all(self) -> int:
 492        """Get the number of all levels on this plate.
 493
 494        Returns:
 495            The number of all levels on this plate.
 496        """
 497        return sum(len(self._get_levels(plate.song)) for plate in await self.get_all())
 498
 499
 500class MaimaiScores:
 501    _client: "MaimaiClient"
 502
 503    scores: list[ScoreExtend]
 504    """All scores of the player."""
 505    scores_b35: list[ScoreExtend]
 506    """The b35 scores of the player."""
 507    scores_b15: list[ScoreExtend]
 508    """The b15 scores of the player."""
 509    rating: int
 510    """The total rating of the player."""
 511    rating_b35: int
 512    """The b35 rating of the player."""
 513    rating_b15: int
 514    """The b15 rating of the player."""
 515
 516    def __init__(self, client: "MaimaiClient"):
 517        self._client = client
 518
 519    async def configure(self, scores: list[Score], b50_only: bool = False) -> "MaimaiScores":
 520        """Initialize the scores by the scores list.
 521
 522        This method will sort the scores by their dx_rating, dx_score and achievements, and split them into b35 and b15 scores.
 523
 524        Args:
 525            scores: the scores list to initialize.
 526        Returns:
 527            The MaimaiScores object with the scores initialized.
 528        """
 529        maimai_songs = await self._client.songs()  # Ensure songs are configured.
 530        song_diff_versions: dict[str, int] = await self._client._cache.get("versions", namespace="songs") or {}
 531        self.scores, self.scores_b35, self.scores_b15 = [], [], []
 532
 533        # Remove duplicates from scores based on id, type and level_index.
 534        scores_unique: dict[str, Score] = {}
 535        for score in scores:
 536            score_key = f"{score.id} {score.type} {score.level_index}"
 537            scores_unique[score_key] = score._compare(scores_unique.get(score_key, None))
 538
 539        # Extend scores and categorize them into b35 and b15 based on their versions.
 540        self.scores = await MaimaiScores._get_extended(scores_unique.values(), maimai_songs)
 541        for score in self.scores:
 542            if score_version := song_diff_versions.get(f"{score.id} {score.type} {score.level_index}", None):
 543                (self.scores_b15 if score_version >= current_version.value else self.scores_b35).append(score)
 544
 545        # Sort scores by dx_rating, dx_score and achievements, and limit the number of scores.
 546        self.scores_b35.sort(key=lambda score: (score.dx_rating or 0, score.dx_score or 0, score.achievements or 0), reverse=True)
 547        self.scores_b15.sort(key=lambda score: (score.dx_rating or 0, score.dx_score or 0, score.achievements or 0), reverse=True)
 548        self.scores_b35 = self.scores_b35[:35]
 549        self.scores_b15 = self.scores_b15[:15]
 550        self.scores = self.scores_b35 + self.scores_b15 if b50_only else self.scores
 551
 552        # Calculate the total rating.
 553        self.rating_b35 = int(sum((score.dx_rating or 0) for score in self.scores_b35))
 554        self.rating_b15 = int(sum((score.dx_rating or 0) for score in self.scores_b15))
 555        self.rating = self.rating_b35 + self.rating_b15
 556
 557        return self
 558
 559    @staticmethod
 560    async def _get_mapping(scores: Iterable[T], maimai_songs: MaimaiSongs) -> AsyncGenerator[tuple[Song, SongDifficulty, T], None]:
 561        required_songs = await maimai_songs.get_batch(set(score.id for score in scores))
 562        required_songs_dict = {song.id: song for song in required_songs if song is not None}
 563        for score in scores:
 564            song = required_songs_dict.get(score.id, None)
 565            diff = song.get_difficulty(score.type, score.level_index) if song else None
 566            if score and song and diff:
 567                yield (song, diff, score)
 568
 569    @staticmethod
 570    async def _get_extended(scores: Iterable[Score], maimai_songs: MaimaiSongs) -> list[ScoreExtend]:
 571        extended_scores = []
 572        async for song, diff, score in MaimaiScores._get_mapping(scores, maimai_songs):
 573            extended_dict = dataclasses.asdict(score)
 574            extended_dict.update(
 575                {
 576                    "level": diff.level,  # Ensure level is set correctly.
 577                    "title": song.title,
 578                    "level_value": diff.level_value,
 579                    "level_dx_score": (diff.tap_num + diff.hold_num + diff.slide_num + diff.break_num + diff.touch_num) * 3,
 580                }
 581            )
 582            extended_scores.append(ScoreExtend(**extended_dict))
 583        return extended_scores
 584
 585    async def get_mapping(self) -> list[tuple[Song, SongDifficulty, ScoreExtend]]:
 586        """Get all scores with their corresponding songs.
 587
 588        This method will return a list of tuples, each containing a song, its corresponding difficulty, and the score.
 589
 590        If the song or difficulty is not found, the whole tuple will be excluded from the result.
 591
 592        Args:
 593            override_scores: a list of scores to override the current instance scores, defaults to UNSET.
 594        Returns:
 595            A list of tuples, each containing (song, difficulty, score).
 596        """
 597        maimai_songs, result = await self._client.songs(), []
 598        async for v in self._get_mapping(self.scores, maimai_songs):
 599            result.append(v)
 600        return result
 601
 602    def get_player_bests(self) -> PlayerBests:
 603        """Get the best scores of the player.
 604
 605        This method will return a PlayerBests object containing the best scores of the player, sorted by their dx_rating, dx_score and achievements.
 606
 607        Returns:
 608            A PlayerBests object containing the best scores of the player.
 609        """
 610        return PlayerBests(
 611            rating=self.rating,
 612            rating_b35=self.rating_b35,
 613            rating_b15=self.rating_b15,
 614            scores_b35=self.scores_b35,
 615            scores_b15=self.scores_b15,
 616        )
 617
 618    def by_song(
 619        self, song_id: int, song_type: Union[SongType, _UnsetSentinel] = UNSET, level_index: Union[LevelIndex, _UnsetSentinel] = UNSET
 620    ) -> list[ScoreExtend]:
 621        """Get scores of the song on that type and level_index.
 622
 623        If song_type or level_index is not provided, it won't be filtered by that attribute.
 624
 625        Args:
 626            song_id: the ID of the song to get the scores by.
 627            song_type: the type of the song to get the scores by, defaults to None.
 628            level_index: the level index of the song to get the scores by, defaults to None.
 629        Returns:
 630            A list of scores that match the song ID, type and level index.
 631            If no score is found, an empty list will be returned.
 632        """
 633        return [
 634            score
 635            for score in self.scores
 636            if score.id == song_id
 637            and (score.type == song_type or isinstance(song_type, _UnsetSentinel))
 638            and (score.level_index == level_index or isinstance(level_index, _UnsetSentinel))
 639        ]
 640
 641    def filter(self, **kwargs) -> list[Score]:
 642        """Filter scores by their attributes.
 643
 644        Make sure the attribute is of the score, and the value is of the same type. All conditions are connected by AND.
 645
 646        Args:
 647            kwargs: the attributes to filter the scores by.
 648        Returns:
 649            an iterator of scores that match all the conditions, yields no items if no score is found.
 650        """
 651        return [score for score in self.scores if all(getattr(score, key) == value for key, value in kwargs.items() if value is not None)]
 652
 653
 654class MaimaiAreas:
 655    _client: "MaimaiClient"
 656    _lang: str
 657
 658    def __init__(self, client: "MaimaiClient") -> None:
 659        """@private"""
 660        self._client = client
 661
 662    async def _configure(self, lang: str, provider: Union[IAreaProvider, _UnsetSentinel]) -> "MaimaiAreas":
 663        self._lang = lang
 664        cache_obj, cache_ttl = self._client._cache, self._client._cache_ttl
 665        # Check if the provider is unset, which means we want to access the cache directly.
 666        if isinstance(provider, _UnsetSentinel):
 667            if await self._client._cache.get("provider", None, namespace=f"areas_{lang}") is not None:
 668                return self
 669        # Really assign the unset provider to the default one.
 670        provider = provider if not isinstance(provider, _UnsetSentinel) else LocalProvider()
 671        # Check if the current provider hash is different from the previous one, which means we need to reconfigure.
 672        current_provider_hash = provider._hash()
 673        previous_provider_hash = await cache_obj.get("provider", "", namespace=f"areas_{lang}")
 674        if current_provider_hash != previous_provider_hash:
 675            areas = await provider.get_areas(lang, self._client)
 676            await asyncio.gather(
 677                cache_obj.set("provider", hash(provider), ttl=cache_ttl, namespace=f"areas_{lang}"),  # provider
 678                cache_obj.set("ids", [area.id for area in areas.values()], namespace=f"areas_{lang}"),  # ids
 679                cache_obj.multi_set(iter((k, v) for k, v in areas.items()), namespace=f"areas_{lang}"),  # areas
 680            )
 681        return self
 682
 683    async def get_all(self) -> list[Area]:
 684        """All areas as list.
 685
 686        This method will iterate all areas in the cache. Unless you really need to iterate all areas, you should use `by_id` or `by_name` instead.
 687
 688        Returns:
 689            A list of all areas in the cache, return an empty list if no area is found.
 690        """
 691        area_ids: Optional[list[int]] = await self._client._cache.get("ids", namespace=f"areas_{self._lang}")
 692        assert area_ids is not None, "Areas not found in cache, please call configure() first."
 693        return await self._client._multi_get(area_ids, namespace=f"areas_{self._lang}")
 694
 695    async def get_batch(self, ids: Iterable[str]) -> list[Area]:
 696        """Get areas by their IDs.
 697
 698        Args:
 699            ids: the IDs of the areas.
 700        Returns:
 701            A list of areas if they exist, otherwise return an empty list.
 702        """
 703        return await self._client._multi_get(ids, namespace=f"areas_{self._lang}")
 704
 705    async def by_id(self, id: str) -> Optional[Area]:
 706        """Get an area by its ID.
 707
 708        Args:
 709            id: the ID of the area.
 710        Returns:
 711            the area if it exists, otherwise return None.
 712        """
 713        return await self._client._cache.get(id, namespace=f"areas_{self._lang}")
 714
 715    async def by_name(self, name: str) -> Optional[Area]:
 716        """Get an area by its name, language-sensitive.
 717
 718        Args:
 719            name: the name of the area.
 720        Returns:
 721            the area if it exists, otherwise return None.
 722        """
 723        return next((area for area in await self.get_all() if area.name == name), None)
 724
 725
 726class MaimaiClient:
 727    """The main client of maimai.py."""
 728
 729    _client: AsyncClient
 730    _cache: BaseCache
 731    _cache_ttl: int
 732
 733    def __new__(cls, *args, **kwargs):
 734        if hasattr(cls, "_instance"):
 735            warn_message = (
 736                "MaimaiClient is a singleton, args are ignored in this case, due to the singleton nature. "
 737                "If you think this is a mistake, please check MaimaiClientMultithreading. "
 738            )
 739            warnings.warn(warn_message, stacklevel=2)
 740            return cls._instance
 741        orig = super(MaimaiClient, cls)
 742        cls._instance = orig.__new__(cls)
 743        return cls._instance
 744
 745    def __init__(
 746        self,
 747        timeout: float = 20.0,
 748        cache: Union[BaseCache, _UnsetSentinel] = UNSET,
 749        cache_ttl: int = 60 * 60 * 24,
 750        **kwargs,
 751    ) -> None:
 752        """Initialize the maimai.py client.
 753
 754        Args:
 755            timeout: the timeout of the requests, defaults to 20.0.
 756            cache: the cache to use, defaults to `aiocache.SimpleMemoryCache()`.
 757            cache_ttl: the TTL of the cache, defaults to 60 * 60 * 24.
 758            kwargs: other arguments to pass to the `httpx.AsyncClient`.
 759        """
 760        self._client = AsyncClient(timeout=timeout, **kwargs)
 761        self._cache = SimpleMemoryCache() if isinstance(cache, _UnsetSentinel) else cache
 762        self._cache_ttl = cache_ttl
 763
 764    async def _multi_get(self, keys: Iterable[Any], namespace: Optional[str] = None) -> list[Any]:
 765        keys_list = list(keys)
 766        if len(keys_list) != 0:
 767            return await self._cache.multi_get(keys_list, namespace=namespace)
 768        return []
 769
 770    async def songs(
 771        self,
 772        provider: Union[ISongProvider, _UnsetSentinel] = UNSET,
 773        alias_provider: Union[IAliasProvider, None, _UnsetSentinel] = UNSET,
 774        curve_provider: Union[ICurveProvider, None, _UnsetSentinel] = UNSET,
 775    ) -> MaimaiSongs:
 776        """Fetch all maimai songs from the provider.
 777
 778        Available providers: `DivingFishProvider`, `LXNSProvider`.
 779
 780        Available alias providers: `YuzuProvider`, `LXNSProvider`.
 781
 782        Available curve providers: `DivingFishProvider`.
 783
 784        Args:
 785            provider: override the data source to fetch the player from, defaults to `LXNSProvider`.
 786            alias_provider: override the data source to fetch the song aliases from, defaults to `YuzuProvider`.
 787            curve_provider: override the data source to fetch the song curves from, defaults to `None`.
 788        Returns:
 789            A wrapper of the song list, for easier access and filtering.
 790        Raises:
 791            httpx.RequestError: Request failed due to network issues.
 792        """
 793        songs = MaimaiSongs(self)
 794        return await songs._configure(provider, alias_provider, curve_provider)
 795
 796    async def players(
 797        self,
 798        identifier: PlayerIdentifier,
 799        provider: IPlayerProvider = LXNSProvider(),
 800    ) -> Player:
 801        """Fetch player data from the provider.
 802
 803        Available providers: `DivingFishProvider`, `LXNSProvider`, `ArcadeProvider`.
 804
 805        Possible returns: `DivingFishPlayer`, `LXNSPlayer`, `ArcadePlayer`.
 806
 807        Args:
 808            identifier: the identifier of the player to fetch, e.g. `PlayerIdentifier(username="turou")`.
 809            provider: the data source to fetch the player from, defaults to `LXNSProvider`.
 810        Returns:
 811            The player object of the player, with all the data fetched. Depending on the provider, it may contain different objects that derived from `Player`.
 812        Raises:
 813            InvalidPlayerIdentifierError: Player identifier is invalid for the provider, or player is not found.
 814            InvalidDeveloperTokenError: Developer token is not provided or token is invalid.
 815            PrivacyLimitationError: The user has not accepted the 3rd party to access the data.
 816            httpx.RequestError: Request failed due to network issues.
 817        Raises:
 818            TitleServerNetworkError: Only for ArcadeProvider, maimai title server related errors, possibly network problems.
 819            TitleServerBlockedError: Only for ArcadeProvider, maimai title server blocked the request, possibly due to ip filtered.
 820            ArcadeIdentifierError: Only for ArcadeProvider, maimai user id is invalid, or the user is not found.
 821        """
 822        return await provider.get_player(identifier, self)
 823
 824    async def scores(
 825        self,
 826        identifier: PlayerIdentifier,
 827        provider: IScoreProvider = LXNSProvider(),
 828    ) -> MaimaiScores:
 829        """Fetch player's ALL scores from the provider.
 830
 831        All scores of the player will be fetched, if you want to fetch only the best scores (for better performance), use `maimai.bests()` instead.
 832
 833        For WechatProvider, PlayerIdentifier must have the `credentials` attribute, we suggest you to use the `maimai.wechat()` method to get the identifier.
 834        Also, PlayerIdentifier should not be cached or stored in the database, as the cookies may expire at any time.
 835
 836        For ArcadeProvider, PlayerIdentifier must have the `credentials` attribute, which is the player's encrypted userId, can be detrived from `maimai.qrcode()`.
 837        Credentials can be reused, since it won't expire, also, userId is encrypted, can't be used in any other cases outside the maimai.py
 838
 839        For more information about the PlayerIdentifier of providers, please refer to the documentation of each provider.
 840
 841        Available providers: `DivingFishProvider`, `LXNSProvider`, `WechatProvider`, `ArcadeProvider`.
 842
 843        Args:
 844            identifier: the identifier of the player to fetch, e.g. `PlayerIdentifier(friend_code=664994421382429)`.
 845            provider: the data source to fetch the player and scores from, defaults to `LXNSProvider`.
 846        Returns:
 847            The scores object of the player, with all the data fetched.
 848        Raises:
 849            InvalidPlayerIdentifierError: Player identifier is invalid for the provider, or player is not found.
 850            InvalidDeveloperTokenError: Developer token is not provided or token is invalid.
 851            PrivacyLimitationError: The user has not accepted the 3rd party to access the data.
 852            httpx.RequestError: Request failed due to network issues.
 853        Raises:
 854            TitleServerNetworkError: Only for ArcadeProvider, maimai title server related errors, possibly network problems.
 855            TitleServerBlockedError: Only for ArcadeProvider, maimai title server blocked the request, possibly due to ip filtered.
 856            ArcadeIdentifierError: Only for ArcadeProvider, maimai user id is invalid, or the user is not found.
 857        """
 858        scores = await provider.get_scores_all(identifier, self)
 859
 860        maimai_scores = MaimaiScores(self)
 861        return await maimai_scores.configure(scores)
 862
 863    async def bests(
 864        self,
 865        identifier: PlayerIdentifier,
 866        provider: IScoreProvider = LXNSProvider(),
 867    ) -> MaimaiScores:
 868        """Fetch player's B50 scores from the provider.
 869
 870        Though MaimaiScores is used, this method will only return the best 50 scores. if you want all scores, please use `maimai.scores()` method instead.
 871
 872        For WechatProvider, PlayerIdentifier must have the `credentials` attribute, we suggest you to use the `maimai.wechat()` method to get the identifier.
 873        Also, PlayerIdentifier should not be cached or stored in the database, as the cookies may expire at any time.
 874
 875        For ArcadeProvider, PlayerIdentifier must have the `credentials` attribute, which is the player's encrypted userId, can be detrived from `maimai.qrcode()`.
 876        Credentials can be reused, since it won't expire, also, userId is encrypted, can't be used in any other cases outside the maimai.py
 877
 878        For more information about the PlayerIdentifier of providers, please refer to the documentation of each provider.
 879
 880        Available providers: `DivingFishProvider`, `LXNSProvider`, `WechatProvider`, `ArcadeProvider`.
 881
 882        Args:
 883            identifier: the identifier of the player to fetch, e.g. `PlayerIdentifier(friend_code=664994421382429)`.
 884            provider: the data source to fetch the player and scores from, defaults to `LXNSProvider`.
 885        Returns:
 886            The scores object of the player, with all the data fetched.
 887        Raises:
 888            InvalidPlayerIdentifierError: Player identifier is invalid for the provider, or player is not found.
 889            InvalidDeveloperTokenError: Developer token is not provided or token is invalid.
 890            PrivacyLimitationError: The user has not accepted the 3rd party to access the data.
 891            httpx.RequestError: Request failed due to network issues.
 892        Raises:
 893            TitleServerNetworkError: Only for ArcadeProvider, maimai title server related errors, possibly network problems.
 894            TitleServerBlockedError: Only for ArcadeProvider, maimai title server blocked the request, possibly due to ip filtered.
 895            ArcadeIdentifierError: Only for ArcadeProvider, maimai user id is invalid, or the user is not found.
 896        """
 897        maimai_scores = MaimaiScores(self)
 898        best_scores = await provider.get_scores_best(identifier, self)
 899        return await maimai_scores.configure(best_scores, b50_only=True)
 900
 901    async def minfo(
 902        self,
 903        song: Union[Song, int, str],
 904        identifier: Optional[PlayerIdentifier],
 905        provider: IScoreProvider = LXNSProvider(),
 906    ) -> Optional[PlayerSong]:
 907        """Fetch player's scores on the specific song.
 908
 909        This method will return all scores of the player on the song.
 910
 911        For more information about the PlayerIdentifier of providers, please refer to the documentation of each provider.
 912
 913        Available providers: `DivingFishProvider`, `LXNSProvider`, `WechatProvider`, `ArcadeProvider`.
 914
 915        Args:
 916            song: the song to fetch the scores from, can be a `Song` object, or a song_id (int), or keywords (str).
 917            identifier: the identifier of the player to fetch, e.g. `PlayerIdentifier(friend_code=664994421382429)`.
 918            provider: the data source to fetch the player and scores from, defaults to `LXNSProvider`.
 919        Returns:
 920            A wrapper of the song and the scores, with full song model, and matched player scores.
 921            If the identifier is not provided, the song will be returned as is, without scores.
 922            If the song is not found, None will be returned.
 923        Raises:
 924            InvalidPlayerIdentifierError: Player identifier is invalid for the provider, or player is not found.
 925            InvalidDeveloperTokenError: Developer token is not provided or token is invalid.
 926            PrivacyLimitationError: The user has not accepted the 3rd party to access the data.
 927            httpx.RequestError: Request failed due to network issues.
 928        Raises:
 929            TitleServerNetworkError: Only for ArcadeProvider, maimai title server related errors, possibly network problems.
 930            TitleServerBlockedError: Only for ArcadeProvider, maimai title server blocked the request, possibly due to ip filtered.
 931            ArcadeIdentifierError: Only for ArcadeProvider, maimai user id is invalid, or the user is not found.
 932        """
 933        maimai_songs, scores = await self.songs(), []
 934        if isinstance(song, str):
 935            search_result = await maimai_songs.by_keywords(song)
 936            song = search_result[0] if len(search_result) > 0 else song
 937        if isinstance(song, int):
 938            search_result = await maimai_songs.by_id(song)
 939            song = search_result if search_result is not None else song
 940        if isinstance(song, Song):
 941            extended_scores = []
 942            if identifier is not None:
 943                scores = await provider.get_scores_one(identifier, song, self)
 944                extended_scores = await MaimaiScores._get_extended(scores, maimai_songs)
 945            return PlayerSong(song, extended_scores)
 946
 947    async def regions(self, identifier: PlayerIdentifier, provider: IRegionProvider = ArcadeProvider()) -> list[PlayerRegion]:
 948        """Get the player's regions that they have played.
 949
 950        Args:
 951            identifier: the identifier of the player to fetch, e.g. `PlayerIdentifier(credentials="encrypted_user_id")`.
 952            provider: the data source to fetch the player from, defaults to `ArcadeProvider`.
 953        Returns:
 954            The list of regions that the player has played.
 955        Raises:
 956            TitleServerNetworkError: Only for ArcadeProvider, maimai title server related errors, possibly network problems.
 957            TitleServerBlockedError: Only for ArcadeProvider, maimai title server blocked the request, possibly due to ip filtered.
 958            ArcadeIdentifierError: Only for ArcadeProvider, maimai user id is invalid, or the user is not found.
 959        """
 960        return await provider.get_regions(identifier, self)
 961
 962    async def updates(
 963        self,
 964        identifier: PlayerIdentifier,
 965        scores: Iterable[Score],
 966        provider: IScoreUpdateProvider = LXNSProvider(),
 967    ) -> None:
 968        """Update player's scores to the provider.
 969
 970        This method is used to update the player's scores to the provider, usually used for updating scores fetched from other providers.
 971
 972        For more information about the PlayerIdentifier of providers, please refer to the documentation of each provider.
 973
 974        Available providers: `DivingFishProvider`, `LXNSProvider`.
 975
 976        Args:
 977            identifier: the identifier of the player to update, e.g. `PlayerIdentifier(friend_code=664994421382429)`.
 978            scores: the scores to update, usually the scores fetched from other providers.
 979            provider: the data source to update the player scores to, defaults to `LXNSProvider`.
 980        Returns:
 981            Nothing, failures will raise exceptions.
 982        Raises:
 983            InvalidPlayerIdentifierError: Player identifier is invalid for the provider, or player is not found, or the import token / password is invalid.
 984            InvalidDeveloperTokenError: Developer token is not provided or token is invalid.
 985            PrivacyLimitationError: The user has not accepted the 3rd party to access the data.
 986            httpx.RequestError: Request failed due to network issues.
 987        """
 988        await provider.update_scores(identifier, scores, self)
 989
 990    async def plates(
 991        self,
 992        identifier: PlayerIdentifier,
 993        plate: str,
 994        provider: IScoreProvider = LXNSProvider(),
 995    ) -> MaimaiPlates:
 996        """Get the plate achievement of the given player and plate.
 997
 998        Available providers: `DivingFishProvider`, `LXNSProvider`, `ArcadeProvider`.
 999
1000        Args:
1001            identifier: the identifier of the player to fetch, e.g. `PlayerIdentifier(friend_code=664994421382429)`.
1002            plate: the name of the plate, e.g. "樱将", "真舞舞".
1003            provider: the data source to fetch the player and scores from, defaults to `LXNSProvider`.
1004        Returns:
1005            A wrapper of the plate achievement, with plate information, and matched player scores.
1006        Raises:
1007            InvalidPlayerIdentifierError: Player identifier is invalid for the provider, or player is not found.
1008            InvalidPlateError: Provided version or plate is invalid.
1009            InvalidDeveloperTokenError: Developer token is not provided or token is invalid.
1010            PrivacyLimitationError: The user has not accepted the 3rd party to access the data.
1011            httpx.RequestError: Request failed due to network issues.
1012        Raises:
1013            TitleServerNetworkError: Only for ArcadeProvider, maimai title server related errors, possibly network problems.
1014            TitleServerBlockedError: Only for ArcadeProvider, maimai title server blocked the request, possibly due to ip filtered.
1015            ArcadeIdentifierError: Only for ArcadeProvider, maimai user id is invalid, or the user is not found.
1016        """
1017        scores = await provider.get_scores_all(identifier, self)
1018        maimai_plates = MaimaiPlates(self)
1019        return await maimai_plates._configure(plate, scores)
1020
1021    async def identifiers(
1022        self,
1023        code: Union[str, dict[str, str]],
1024        provider: Union[IPlayerIdentifierProvider, _UnsetSentinel] = UNSET,
1025    ) -> PlayerIdentifier:
1026        """Get the player identifier from the provider.
1027
1028        This method is combination of `maimai.wechat()` and `maimai.qrcode()`, which will return the player identifier of the player.
1029
1030        For WechatProvider, code should be a dictionary with `r`, `t`, `code`, and `state` keys, or a string that contains the URL parameters.
1031
1032        For ArcadeProvider, code should be a string that begins with `SGWCMAID`, which is the QR code of the player.
1033
1034        Available providers: `WechatProvider`, `ArcadeProvider`.
1035
1036        Args:
1037            code: the code to get the player identifier, can be a string or a dictionary with `r`, `t`, `code`, and `state` keys.
1038            provider: override the default provider, defaults to `ArcadeProvider`.
1039        Returns:
1040            The player identifier of the player.
1041        Raises:
1042            InvalidWechatTokenError: Wechat token is expired, please re-authorize.
1043            AimeServerError: Maimai Aime server error, may be invalid QR code or QR code has expired.
1044            httpx.RequestError: Request failed due to network issues.
1045        """
1046        if isinstance(provider, _UnsetSentinel):
1047            provider = ArcadeProvider()
1048        return await provider.get_identifier(code, self)
1049
1050    async def items(self, item: Type[PlayerItemType], provider: Union[IItemListProvider, _UnsetSentinel] = UNSET) -> MaimaiItems[PlayerItemType]:
1051        """Fetch maimai player items from the cache default provider.
1052
1053        Available items: `PlayerIcon`, `PlayerNamePlate`, `PlayerFrame`, `PlayerTrophy`, `PlayerChara`, `PlayerPartner`.
1054
1055        Args:
1056            item: the item type to fetch, e.g. `PlayerIcon`.
1057            provider: override the default item list provider, defaults to `LXNSProvider` and `LocalProvider`.
1058        Returns:
1059            A wrapper of the item list, for easier access and filtering.
1060        Raises:
1061            FileNotFoundError: The item file is not found.
1062            httpx.RequestError: Request failed due to network issues.
1063        """
1064        maimai_items = MaimaiItems[PlayerItemType](self, item._namespace())
1065        return await maimai_items._configure(provider)
1066
1067    async def areas(self, lang: Literal["ja", "zh"] = "ja", provider: IAreaProvider = LocalProvider()) -> MaimaiAreas:
1068        """Fetch maimai areas from the provider.
1069
1070        Available providers: `LocalProvider`.
1071
1072        Args:
1073            lang: the language of the area to fetch, available languages: `ja`, `zh`.
1074            provider: override the default area provider, defaults to `ArcadeProvider`.
1075        Returns:
1076            A wrapper of the area list, for easier access and filtering.
1077        Raises:
1078            FileNotFoundError: The area file is not found.
1079        """
1080        maimai_areas = MaimaiAreas(self)
1081        return await maimai_areas._configure(lang, provider)
1082
1083    async def wechat(
1084        self,
1085        r: Optional[str] = None,
1086        t: Optional[str] = None,
1087        code: Optional[str] = None,
1088        state: Optional[str] = None,
1089    ) -> Union[str, PlayerIdentifier]:
1090        """Get the player identifier from the Wahlap Wechat OffiAccount.
1091
1092        Call the method with no parameters to get the URL, then redirect the user to the URL with your mitmproxy enabled.
1093
1094        Your mitmproxy should intercept the response from tgk-wcaime.wahlap.com, then call the method with the parameters from the intercepted response.
1095
1096        With the parameters from specific user's response, the method will return the user's player identifier.
1097
1098        Never cache or store the player identifier, as the cookies may expire at any time.
1099
1100        Args:
1101            r: the r parameter from the request, defaults to None.
1102            t: the t parameter from the request, defaults to None.
1103            code: the code parameter from the request, defaults to None.
1104            state: the state parameter from the request, defaults to None.
1105        Returns:
1106            The player identifier if all parameters are provided, otherwise return the URL to get the identifier.
1107        Raises:
1108            WechatTokenExpiredError: Wechat token is expired, please re-authorize.
1109            httpx.RequestError: Request failed due to network issues.
1110        """
1111        if r is None or t is None or code is None or state is None:
1112            resp = await self._client.get("https://tgk-wcaime.wahlap.com/wc_auth/oauth/authorize/maimai-dx")
1113            return resp.headers["location"].replace("redirect_uri=https", "redirect_uri=http")
1114        return await WechatProvider().get_identifier({"r": r, "t": t, "code": code, "state": state}, self)
1115
1116    async def qrcode(self, qrcode: str, http_proxy: Optional[str] = None) -> PlayerIdentifier:
1117        """Get the player identifier from the Wahlap QR code.
1118
1119        Player identifier is the encrypted userId, can't be used in any other cases outside the maimai.py.
1120
1121        Args:
1122            qrcode: the QR code of the player, should begin with SGWCMAID.
1123            http_proxy: the http proxy to use for the request, defaults to None.
1124        Returns:
1125            The player identifier of the player.
1126        Raises:
1127            AimeServerError: Maimai Aime server error, may be invalid QR code or QR code has expired.
1128        """
1129        provider = ArcadeProvider(http_proxy=http_proxy)
1130        return await provider.get_identifier(qrcode, self)
1131
1132    async def updates_chain(
1133        self,
1134        source: list[tuple[IScoreProvider, Optional[PlayerIdentifier], dict[str, Any]]],
1135        target: list[tuple[IScoreUpdateProvider, Optional[PlayerIdentifier], dict[str, Any]]],
1136        source_mode: Literal["fallback", "parallel"] = "fallback",
1137        target_mode: Literal["fallback", "parallel"] = "parallel",
1138        source_callback: Optional[Callable[[MaimaiScores, Optional[BaseException], dict[str, Any]], None]] = None,
1139        target_callback: Optional[Callable[[MaimaiScores, Optional[BaseException], dict[str, Any]], None]] = None,
1140    ) -> None:
1141        """Chain updates from source providers to target providers.
1142
1143        This method will fetch scores from the source providers, merge them, and then update the target providers with the merged scores.
1144
1145        The dict in source and target tuples can contain any additional context that will be passed to the callbacks.
1146
1147        Args:
1148            source: a list of tuples, each containing a source provider, an optional player identifier, and additional context.
1149                If the identifier is None, the provider will be ignored.
1150            target: a list of tuples, each containing a target provider, an optional player identifier, and additional context.
1151                If the identifier is None, the provider will be ignored.
1152            source_mode: how to handle source tasks, either "fallback" (default) or "parallel".
1153                In "fallback" mode, only the first successful source pair will be scheduled.
1154                In "parallel" mode, all source pairs will be scheduled.
1155            target_mode: how to handle target tasks, either "fallback" or "parallel" (default).
1156                In "fallback" mode, only the first successful target pair will be scheduled.
1157                In "parallel" mode, all target pairs will be scheduled.
1158            source_callback: an optional callback function that will be called with the source provider,
1159                callback with provider, fetched scores and any exception that occurred during fetching.
1160            target_callback: an optional callback function that will be called with the target provider,
1161                callback with provider, merged scores and any exception that occurred during updating.
1162        Returns:
1163            Nothing, failures will notify by callbacks.
1164        """
1165        source_tasks, target_tasks = [], []
1166
1167        # Fetch scores from the source providers.
1168        for sp, ident, kwargs in source:
1169            if ident is not None:
1170                if source_mode == "parallel" or (source_mode == "fallback" and len(source_tasks) == 0):
1171                    source_task = asyncio.create_task(self.scores(ident, sp))
1172                    if source_callback is not None:
1173                        source_task.add_done_callback(lambda t, k=kwargs: source_callback(t.result(), t.exception(), k))
1174                    source_tasks.append(source_task)
1175        source_gather_results = await asyncio.gather(*source_tasks, return_exceptions=True)
1176        maimai_scores_list = [result for result in source_gather_results if isinstance(result, MaimaiScores)]
1177
1178        # Merge scores from all maimai_scores instances.
1179        scores_unique: dict[str, Score] = {}
1180        for maimai_scores in maimai_scores_list:
1181            for score in maimai_scores.scores:
1182                score_key = f"{score.id} {score.type} {score.level_index}"
1183                scores_unique[score_key] = score._join(scores_unique.get(score_key, None))
1184        merged_scores = list(scores_unique.values())
1185        merged_maimai_scores = await MaimaiScores(self).configure(list(scores_unique.values()))
1186
1187        # Update scores to the target providers.
1188        for tp, ident, kwargs in target:
1189            if ident is not None:
1190                if target_mode == "parallel" or (target_mode == "fallback" and len(target_tasks) == 0):
1191                    target_task = asyncio.create_task(self.updates(ident, merged_scores, tp))
1192                    if target_callback is not None:
1193                        target_task.add_done_callback(lambda t, k=kwargs: target_callback(merged_maimai_scores, t.exception(), k))
1194                    target_tasks.append(target_task)
1195        await asyncio.gather(*target_tasks, return_exceptions=True)
1196
1197
1198class MaimaiClientMultithreading(MaimaiClient):
1199    """Multi-threading version of maimai.py.
1200    Introduced by issue #28. Users who want to share the same client instance across multiple threads can use this class.
1201    """
1202
1203    def __new__(cls, *args, **kwargs):
1204        # Override the singleton behavior by always creating a new instance
1205        return super(MaimaiClient, cls).__new__(cls)