Players

Classes related to player data in the API.

Bases: Model

Represents basic information about a player.

Attributes:

Name	Type	Description
name	str	Player's in-game name.
cur_head_icon_id	str	ID of the current avatar or head icon.
rank_season	RankSeason	Ranking information for the current season.
login_os	str	Operating system used at last login (e.g., "1" = Android, "2" = iOS).
raw_dict	dict	The original JSON data used to create this instance.

Source code in marvelrivalsapi\models.py

@define(kw_only=True)
class PlayerInfo(Model):
    """
    Represents basic information about a player.

    Attributes
    ----------
    name : str
        Player's in-game name.
    cur_head_icon_id : str
        ID of the current avatar or head icon.
    rank_season : RankSeason
        Ranking information for the current season.
    login_os : str
        Operating system used at last login (e.g., "1" = Android, "2" = iOS).
    raw_dict : dict
        The original JSON data used to create this instance.
    """

    name: str
    cur_head_icon_id: str
    rank_season: RankSeason
    login_os: str
    raw_dict: dict[str, typing.Any] = field(factory=dict)

    @classmethod
    def from_dict(cls, data: dict[str, typing.Any]) -> PlayerInfo:
        """
        Create a PlayerInfo instance from a dictionary.

        Parameters
        ----------
        data : dict
            Dictionary containing player info data.

        Returns
        -------
        PlayerInfo
            A new PlayerInfo instance.
        """
        return cls(
            name=data["name"],
            cur_head_icon_id=data["cur_head_icon_id"],
            rank_season=RankSeason.from_dict(data["rank_season"]),
            login_os=data["login_os"],
            raw_dict=data.copy(),
        )

    @property
    def platform(self) -> LoginOS:
        """
        Get the platform name based on the login OS code.

        Returns
        -------
        str
            The platform name (PC, PS or Xbox).
        """
        platforms = {
            "1": "PC",
            "2": "PS",
            "3": "XBOX",
        }
        return LoginOS(platforms.get(self.login_os, 1))

platform property

Get the platform name based on the login OS code.

Returns:

Type	Description
str	The platform name (PC, PS or Xbox).

from_dict(data) classmethod

Create a PlayerInfo instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict	Dictionary containing player info data.	required

Returns:

Type	Description
PlayerInfo	A new PlayerInfo instance.

Source code in marvelrivalsapi\models.py

@classmethod
def from_dict(cls, data: dict[str, typing.Any]) -> PlayerInfo:
    """
    Create a PlayerInfo instance from a dictionary.

    Parameters
    ----------
    data : dict
        Dictionary containing player info data.

    Returns
    -------
    PlayerInfo
        A new PlayerInfo instance.
    """
    return cls(
        name=data["name"],
        cur_head_icon_id=data["cur_head_icon_id"],
        rank_season=RankSeason.from_dict(data["rank_season"]),
        login_os=data["login_os"],
        raw_dict=data.copy(),
    )

Bases: Model

Represents a player entry in the leaderboard.

Attributes:

Name	Type	Description
info	PlayerInfo	Basic information about the player.
player_uid	int	Unique identifier for the player.
matches	int	Total matches played.
wins	int	Total matches won.
kills	int	Total kills achieved.
deaths	int	Total number of deaths.
assists	int	Total number of assists.
play_time	str	Total play time in minutes, as a string with decimal value.
total_hero_damage	str	Total damage dealt to enemy heroes.
total_damage_taken	str	Total damage taken from enemies.
total_hero_heal	str	Total healing done to heroes.
mvps	int	Number of times the player was MVP (Most Valuable Player).
svps	int	Number of times the player was SVP (Second Valuable Player).
raw_dict	dict	The original JSON data used to create this instance.

Source code in marvelrivalsapi\models.py

@define(kw_only=True)
class LeaderboardPlayer(Model):
    """
    Represents a player entry in the leaderboard.

    Attributes
    ----------
    info : PlayerInfo
        Basic information about the player.
    player_uid : int
        Unique identifier for the player.
    matches : int
        Total matches played.
    wins : int
        Total matches won.
    kills : int
        Total kills achieved.
    deaths : int
        Total number of deaths.
    assists : int
        Total number of assists.
    play_time : str
        Total play time in minutes, as a string with decimal value.
    total_hero_damage : str
        Total damage dealt to enemy heroes.
    total_damage_taken : str
        Total damage taken from enemies.
    total_hero_heal : str
        Total healing done to heroes.
    mvps : int
        Number of times the player was MVP (Most Valuable Player).
    svps : int
        Number of times the player was SVP (Second Valuable Player).
    raw_dict : dict
        The original JSON data used to create this instance.
    """

    info: PlayerInfo
    player_uid: int
    matches: int
    wins: int
    kills: int
    deaths: int
    assists: int
    play_time: str
    total_hero_damage: str
    total_damage_taken: str
    total_hero_heal: str
    mvps: int
    svps: int
    raw_dict: dict[str, typing.Any] = field(factory=dict)

    @classmethod
    def from_dict(cls, data: dict[str, typing.Any]) -> LeaderboardPlayer:
        """
        Create a LeaderboardPlayer instance from a dictionary.

        Parameters
        ----------
        data : dict
            Dictionary containing leaderboard player data.

        Returns
        -------
        LeaderboardPlayer
            A new LeaderboardPlayer instance.
        """
        return cls(
            info=PlayerInfo.from_dict(data["info"]),
            player_uid=data["player_uid"],
            matches=data["matches"],
            wins=data["wins"],
            kills=data["kills"],
            deaths=data["deaths"],
            assists=data["assists"],
            play_time=data["play_time"],
            total_hero_damage=data["total_hero_damage"],
            total_damage_taken=data["total_damage_taken"],
            total_hero_heal=data["total_hero_heal"],
            mvps=data["mvps"],
            svps=data["svps"],
            raw_dict=data.copy(),
        )

    @property
    def win_rate(self) -> float:
        """
        Calculate win rate for this player.

        Returns
        -------
        float
            Win rate as a decimal between 0 and 1.
        """
        return self.wins / self.matches if self.matches > 0 else 0.0

    @property
    def kda(self) -> float:
        """
        Calculate KDA (Kills + Assists / Deaths) ratio.

        Returns
        -------
        float
            KDA ratio. Uses deaths = 1 if deaths = 0.
        """
        return (self.kills + self.assists) / (self.deaths or 1)

    @property
    def avg_kills(self) -> float:
        """
        Calculate average kills per match.

        Returns
        -------
        float
            Average kills per match.
        """
        return self.kills / self.matches if self.matches > 0 else 0.0

    @property
    def avg_deaths(self) -> float:
        """
        Calculate average deaths per match.

        Returns
        -------
        float
            Average deaths per match.
        """
        return self.deaths / self.matches if self.matches > 0 else 0.0

    @property
    def avg_assists(self) -> float:
        """
        Calculate average assists per match.

        Returns
        -------
        float
            Average assists per match.
        """
        return self.assists / self.matches if self.matches > 0 else 0.0

    @property
    def avg_hero_damage(self) -> float:
        """
        Calculate average hero damage per match.

        Returns
        -------
        float
            Average hero damage per match.
        """
        try:
            return (
                float(self.total_hero_damage) / self.matches
                if self.matches > 0
                else 0.0
            )
        except (ValueError, TypeError):
            return 0.0

    @property
    def mvp_rate(self) -> float:
        """
        Calculate rate of MVP awards.

        Returns
        -------
        float
            Percentage of matches where player was MVP, as a decimal.
        """
        return self.mvps / self.matches if self.matches > 0 else 0.0

avg_assists property

Calculate average assists per match.

Returns:

Type	Description
float	Average assists per match.

avg_deaths property

Calculate average deaths per match.

Returns:

Type	Description
float	Average deaths per match.

avg_hero_damage property

Calculate average hero damage per match.

Returns:

Type	Description
float	Average hero damage per match.

avg_kills property

Calculate average kills per match.

Returns:

Type	Description
float	Average kills per match.

kda property

Calculate KDA (Kills + Assists / Deaths) ratio.

Returns:

Type	Description
float	KDA ratio. Uses deaths = 1 if deaths = 0.

mvp_rate property

Calculate rate of MVP awards.

Returns:

Type	Description
float	Percentage of matches where player was MVP, as a decimal.

win_rate property

Calculate win rate for this player.

Returns:

Type	Description
float	Win rate as a decimal between 0 and 1.

from_dict(data) classmethod

Create a LeaderboardPlayer instance from a dictionary.

Parameters:

Name	Type	Description	Default
data	dict	Dictionary containing leaderboard player data.	required

Returns:

Type	Description
LeaderboardPlayer	A new LeaderboardPlayer instance.

Source code in marvelrivalsapi\models.py

@classmethod
def from_dict(cls, data: dict[str, typing.Any]) -> LeaderboardPlayer:
    """
    Create a LeaderboardPlayer instance from a dictionary.

    Parameters
    ----------
    data : dict
        Dictionary containing leaderboard player data.

    Returns
    -------
    LeaderboardPlayer
        A new LeaderboardPlayer instance.
    """
    return cls(
        info=PlayerInfo.from_dict(data["info"]),
        player_uid=data["player_uid"],
        matches=data["matches"],
        wins=data["wins"],
        kills=data["kills"],
        deaths=data["deaths"],
        assists=data["assists"],
        play_time=data["play_time"],
        total_hero_damage=data["total_hero_damage"],
        total_damage_taken=data["total_damage_taken"],
        total_hero_heal=data["total_hero_heal"],
        mvps=data["mvps"],
        svps=data["svps"],
        raw_dict=data.copy(),
    )