maimai_py

View Source

 1from .maimai import MaimaiClient
 2from .exceptions import MaimaiPyError
 3from .models import MaimaiSongs, MaimaiPlates, MaimaiScores, MaimaiItems
 4from .providers import DivingFishProvider, LXNSProvider, YuzuProvider, WechatProvider, ArcadeProvider, LocalProvider
 5
 6# extended models and enums
 7from .enums import ScoreKind, LevelIndex, FCType, FSType, RateType, SongType
 8from .models import DivingFishPlayer, LXNSPlayer, ArcadePlayer, Score, PlateObject
 9from .models import Song, SongDifficulties, SongDifficulty, SongDifficultyUtage, CurveObject
10from .models import PlayerIdentifier, PlayerTrophy, PlayerIcon, PlayerNamePlate, PlayerFrame, PlayerPartner, PlayerChara, PlayerRegion
11
12
13__all__ = [
14    "MaimaiClient",
15    "MaimaiScores",
16    "MaimaiPlates",
17    "MaimaiSongs",
18    "MaimaiItems",
19    "models",
20    "enums",
21    "exceptions",
22    "providers",
23]

class MaimaiScores: View Source

724class MaimaiScores:
725    scores: list[Score]
726    """All scores of the player when `ScoreKind.ALL`, otherwise only the b50 scores."""
727    scores_b35: list[Score]
728    """The b35 scores of the player."""
729    scores_b15: list[Score]
730    """The b15 scores of the player."""
731    rating: int
732    """The total rating of the player."""
733    rating_b35: int
734    """The b35 rating of the player."""
735    rating_b15: int
736    """The b15 rating of the player."""
737
738    @staticmethod
739    def _get_distinct_scores(scores: list[Score]) -> list[Score]:
740        scores_unique = {}
741        for score in scores:
742            score_key = f"{score.id} {score.type} {score.level_index}"
743            scores_unique[score_key] = score._compare(scores_unique.get(score_key, None))
744        return list(scores_unique.values())
745
746    def __init__(
747        self, b35: list[Score] | None = None, b15: list[Score] | None = None, all: list[Score] | None = None, songs: MaimaiSongs | None = None
748    ):
749        self.scores = all or (b35 + b15 if b35 and b15 else None) or []
750        # if b35 and b15 are not provided, try to calculate them from all scores
751        if (not b35 or not b15) and all:
752            distinct_scores = MaimaiScores._get_distinct_scores(all)  # scores have to be distinct to calculate the bests
753            scores_new: list[Score] = []
754            scores_old: list[Score] = []
755            for score in distinct_scores:
756                if songs and (diff := score.difficulty):
757                    (scores_new if diff.version >= current_version.value else scores_old).append(score)
758            scores_old.sort(key=lambda score: (score.dx_rating, score.dx_score, score.achievements), reverse=True)
759            scores_new.sort(key=lambda score: (score.dx_rating, score.dx_score, score.achievements), reverse=True)
760            b35 = scores_old[:35]
761            b15 = scores_new[:15]
762        self.scores_b35 = b35 or []
763        self.scores_b15 = b15 or []
764        self.rating_b35 = int(sum((score.dx_rating or 0) for score in b35) if b35 else 0)
765        self.rating_b15 = int(sum((score.dx_rating or 0) for score in b15) if b15 else 0)
766        self.rating = self.rating_b35 + self.rating_b15
767
768    @property
769    def as_distinct(self) -> "MaimaiScores":
770        """Get the distinct scores.
771
772        Normally, player has more than one score for the same song and level, this method will return a new `MaimaiScores` object with the highest scores for each song and level.
773
774        This method won't modify the original scores object, it will return a new one.
775
776        If ScoreKind is BEST, this won't make any difference, because the scores are already the best ones.
777        """
778        distinct_scores = MaimaiScores._get_distinct_scores(self.scores)
779        songs: MaimaiSongs = default_caches._caches["msongs"]
780        assert songs is not None and isinstance(songs, MaimaiSongs)
781        return MaimaiScores(b35=self.scores_b35, b15=self.scores_b15, all=distinct_scores, songs=songs)
782
783    def by_song(
784        self, song_id: int, song_type: SongType | _UnsetSentinel = UNSET, level_index: LevelIndex | _UnsetSentinel = UNSET
785    ) -> Iterator[Score]:
786        """Get scores of the song on that type and level_index.
787
788        If song_type or level_index is not provided, all scores of the song will be returned.
789
790        Args:
791            song_id: the ID of the song to get the scores by.
792            song_type: the type of the song to get the scores by, defaults to None.
793            level_index: the level index of the song to get the scores by, defaults to None.
794        Returns:
795            the list of scores of the song, return an empty list if no score is found.
796        """
797        for score in self.scores:
798            if score.id != song_id:
799                continue
800            if song_type is not UNSET and score.type != song_type:
801                continue
802            if level_index is not UNSET and score.level_index != level_index:
803                continue
804            yield score
805
806    def filter(self, **kwargs) -> list[Score]:
807        """Filter scores by their attributes.
808
809        Make sure the attribute is of the score, and the value is of the same type. All conditions are connected by AND.
810
811        Args:
812            kwargs: the attributes to filter the scores by.
813        Returns:
814            the list of scores that match all the conditions, return an empty list if no score is found.
815        """
816        return [score for score in self.scores if all(getattr(score, key) == value for key, value in kwargs.items())]

MaimaiScores( b35: list[maimai_py.models.Score] | None = None, b15: list[maimai_py.models.Score] | None = None, all: list[maimai_py.models.Score] | None = None, songs: MaimaiSongs | None = None) View Source

746    def __init__(
747        self, b35: list[Score] | None = None, b15: list[Score] | None = None, all: list[Score] | None = None, songs: MaimaiSongs | None = None
748    ):
749        self.scores = all or (b35 + b15 if b35 and b15 else None) or []
750        # if b35 and b15 are not provided, try to calculate them from all scores
751        if (not b35 or not b15) and all:
752            distinct_scores = MaimaiScores._get_distinct_scores(all)  # scores have to be distinct to calculate the bests
753            scores_new: list[Score] = []
754            scores_old: list[Score] = []
755            for score in distinct_scores:
756                if songs and (diff := score.difficulty):
757                    (scores_new if diff.version >= current_version.value else scores_old).append(score)
758            scores_old.sort(key=lambda score: (score.dx_rating, score.dx_score, score.achievements), reverse=True)
759            scores_new.sort(key=lambda score: (score.dx_rating, score.dx_score, score.achievements), reverse=True)
760            b35 = scores_old[:35]
761            b15 = scores_new[:15]
762        self.scores_b35 = b35 or []
763        self.scores_b15 = b15 or []
764        self.rating_b35 = int(sum((score.dx_rating or 0) for score in b35) if b35 else 0)
765        self.rating_b15 = int(sum((score.dx_rating or 0) for score in b15) if b15 else 0)
766        self.rating = self.rating_b35 + self.rating_b15

scores: list[maimai_py.models.Score]

All scores of the player when ScoreKind.ALL, otherwise only the b50 scores.

scores_b35: list[maimai_py.models.Score]

The b35 scores of the player.

scores_b15: list[maimai_py.models.Score]

The b15 scores of the player.

rating: int

The total rating of the player.

rating_b35: int

The b35 rating of the player.

rating_b15: int

The b15 rating of the player.

as_distinct: MaimaiScores View Source

768    @property
769    def as_distinct(self) -> "MaimaiScores":
770        """Get the distinct scores.
771
772        Normally, player has more than one score for the same song and level, this method will return a new `MaimaiScores` object with the highest scores for each song and level.
773
774        This method won't modify the original scores object, it will return a new one.
775
776        If ScoreKind is BEST, this won't make any difference, because the scores are already the best ones.
777        """
778        distinct_scores = MaimaiScores._get_distinct_scores(self.scores)
779        songs: MaimaiSongs = default_caches._caches["msongs"]
780        assert songs is not None and isinstance(songs, MaimaiSongs)
781        return MaimaiScores(b35=self.scores_b35, b15=self.scores_b15, all=distinct_scores, songs=songs)

Get the distinct scores.

Normally, player has more than one score for the same song and level, this method will return a new MaimaiScores object with the highest scores for each song and level.

This method won't modify the original scores object, it will return a new one.

If ScoreKind is BEST, this won't make any difference, because the scores are already the best ones.

def by_song( self, song_id: int, song_type: maimai_py.enums.SongType | maimai_py.utils.sentinel._UnsetSentinel = Unset, level_index: maimai_py.enums.LevelIndex | maimai_py.utils.sentinel._UnsetSentinel = Unset) -> Iterator[maimai_py.models.Score]: View Source

783    def by_song(
784        self, song_id: int, song_type: SongType | _UnsetSentinel = UNSET, level_index: LevelIndex | _UnsetSentinel = UNSET
785    ) -> Iterator[Score]:
786        """Get scores of the song on that type and level_index.
787
788        If song_type or level_index is not provided, all scores of the song will be returned.
789
790        Args:
791            song_id: the ID of the song to get the scores by.
792            song_type: the type of the song to get the scores by, defaults to None.
793            level_index: the level index of the song to get the scores by, defaults to None.
794        Returns:
795            the list of scores of the song, return an empty list if no score is found.
796        """
797        for score in self.scores:
798            if score.id != song_id:
799                continue
800            if song_type is not UNSET and score.type != song_type:
801                continue
802            if level_index is not UNSET and score.level_index != level_index:
803                continue
804            yield score

Get scores of the song on that type and level_index.

If song_type or level_index is not provided, all scores of the song will be returned.

Arguments:

song_id: the ID of the song to get the scores by.
song_type: the type of the song to get the scores by, defaults to None.
level_index: the level index of the song to get the scores by, defaults to None.

Returns:

the list of scores of the song, return an empty list if no score is found.

def filter(self, **kwargs) -> list[maimai_py.models.Score]: View Source

806    def filter(self, **kwargs) -> list[Score]:
807        """Filter scores by their attributes.
808
809        Make sure the attribute is of the score, and the value is of the same type. All conditions are connected by AND.
810
811        Args:
812            kwargs: the attributes to filter the scores by.
813        Returns:
814            the list of scores that match all the conditions, return an empty list if no score is found.
815        """
816        return [score for score in self.scores if all(getattr(score, key) == value for key, value in kwargs.items())]

Filter scores by their attributes.

Make sure the attribute is of the score, and the value is of the same type. All conditions are connected by AND.

Arguments:

kwargs: the attributes to filter the scores by.

Returns:

the list of scores that match all the conditions, return an empty list if no score is found.

class MaimaiItems(typing.Generic[~CachedType]): View Source

355class MaimaiItems(Generic[CachedType]):
356    _cached_items: dict[int, CachedType]
357
358    def __init__(self, items: dict[int, CachedType]) -> None:
359        """@private"""
360        self._cached_items = items
361
362    @property
363    def values(self) -> Iterator[CachedType]:
364        """All items as list."""
365        return iter(self._cached_items.values())
366
367    def by_id(self, id: int) -> CachedType | None:
368        """Get an item by its ID.
369
370        Args:
371            id: the ID of the item.
372        Returns:
373            the item if it exists, otherwise return None.
374        """
375        return self._cached_items.get(id, None)
376
377    def filter(self, **kwargs) -> list[CachedType]:
378        """Filter items by their attributes.
379
380        Ensure that the attribute is of the item, and the value is of the same type. All conditions are connected by AND.
381
382        Args:
383            kwargs: the attributes to filter the items by.
384        Returns:
385            the list of items that match all the conditions, return an empty list if no item is found.
386        """
387        return [item for item in self.values if all(getattr(item, key) == value for key, value in kwargs.items() if value is not None)]

Abstract base class for generic types.

On Python 3.12 and newer, generic classes implicitly inherit from Generic when they declare a parameter list after the class's name::

class Mapping[KT, VT]:
    def __getitem__(self, key: KT) -> VT:
        ...
    # Etc.

On older versions of Python, however, generic classes have to explicitly inherit from Generic.

After a class has been declared to be generic, it can then be used as follows::

def lookup_name[KT, VT](mapping: Mapping[KT, VT], key: KT, default: VT) -> VT:
    try:
        return mapping[key]
    except KeyError:
        return default

values: Iterator[~CachedType] View Source

362    @property
363    def values(self) -> Iterator[CachedType]:
364        """All items as list."""
365        return iter(self._cached_items.values())

All items as list.

def by_id(self, id: int) -> Optional[~CachedType]: View Source

367    def by_id(self, id: int) -> CachedType | None:
368        """Get an item by its ID.
369
370        Args:
371            id: the ID of the item.
372        Returns:
373            the item if it exists, otherwise return None.
374        """
375        return self._cached_items.get(id, None)

Get an item by its ID.

Arguments:

id: the ID of the item.

Returns:

the item if it exists, otherwise return None.

def filter(self, **kwargs) -> list[~CachedType]: View Source

377    def filter(self, **kwargs) -> list[CachedType]:
378        """Filter items by their attributes.
379
380        Ensure that the attribute is of the item, and the value is of the same type. All conditions are connected by AND.
381
382        Args:
383            kwargs: the attributes to filter the items by.
384        Returns:
385            the list of items that match all the conditions, return an empty list if no item is found.
386        """
387        return [item for item in self.values if all(getattr(item, key) == value for key, value in kwargs.items() if value is not None)]

Filter items by their attributes.

Ensure that the attribute is of the item, and the value is of the same type. All conditions are connected by AND.

Arguments:

kwargs: the attributes to filter the items by.

Returns:

the list of items that match all the conditions, return an empty list if no item is found.

maimai_py

Arguments:

Arguments:

Returns:

Raises:

Arguments:

Returns:

Raises:

Raises:

Arguments:

Returns:

Raises:

Raises:

Arguments:

Returns:

Raises:

Arguments:

Returns:

Raises:

Arguments:

Returns:

Raises:

Arguments:

Returns:

Raises:

Arguments:

Returns:

Raises:

Arguments:

Returns:

Raises:

Arguments:

Returns:

Raises:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns:

Arguments:

Returns: