rivalsdata-api 1.1.1__tar.gz → 1.2.0__tar.gz

{rivalsdata_api-1.1.1 → rivalsdata_api-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rivalsdata-api
-Version: 1.1.1
+Version: 1.2.0
 Summary: Python client and MCP server for public Marvel Rivals stats from RivalsData
 Project-URL: Homepage, https://github.com/GS-Rionnag/rivalsdata-api
 Project-URL: Repository, https://github.com/GS-Rionnag/rivalsdata-api
@@ -85,6 +85,37 @@ with RivalsDataClient() as rd:
 print(hero_season[0].win_rate)  # integer percent when wins/losses are present
 ```
 
+Calculated player class statistics are available through
+`player.stats.classes(season=20)` and the MCP `get_player_stats` tool with
+`category="classes"`. Each row contains `player_class` (`tank`, `support`,
+`dps`), the official role, hero IDs, and separate `competitive` and `quickplay`
+totals for games, wins, losses, and available MVP/SVP counts.
+
+```python
+with RivalsDataClient() as rd:
+    stats = rd.get_player("GS-").stats.classes(season=20)
+    for row in stats.classes:
+        print(row.player_class, row.competitive.win_rate)
+    print(stats.excluded)  # Unknown roles or incomplete win/loss records
+```
+
+Win rates are `total wins / (total wins + total losses)`, rounded to an integer
+percent. They are weighted by hero records, rather than averaging hero win
+rates. Switching heroes can make one match contribute to multiple records;
+these totals describe hero participation, not distinct matches. Empty modes
+have a `None` win rate. Role mappings were observed on RivalsData on
+2026-09-30, including Deadpool's separate role IDs; generic Deadpool and unknown
+IDs are excluded rather than assigned a guessed class.
+
+Character playtime was checked with Camoufox on 2026-09-30. Player hero stats
+did not expose cumulative hours, including in All Seasons. Match details do
+provide seconds in `match.teams[].players[].heroes[].play_time`; the site shows
+these as minutes and seconds when hovering a hero portrait. Sum the relevant
+player's entries across distinct retrieved matches and divide by 3600 to get
+character hours for those matches. Incomplete history prevents treating this as
+a lifetime total. See [the playtime investigation](docs/API.md#character-playtime-investigation-2026-09-30)
+for the observed fields and example.
+
 ## MCP server (ChatGPT and Claude)
 
 Install the MCP extra and the package:

{rivalsdata_api-1.1.1 → rivalsdata_api-1.2.0}/README.md

@@ -49,6 +49,37 @@ with RivalsDataClient() as rd:
 print(hero_season[0].win_rate)  # integer percent when wins/losses are present
 ```
 
+Calculated player class statistics are available through
+`player.stats.classes(season=20)` and the MCP `get_player_stats` tool with
+`category="classes"`. Each row contains `player_class` (`tank`, `support`,
+`dps`), the official role, hero IDs, and separate `competitive` and `quickplay`
+totals for games, wins, losses, and available MVP/SVP counts.
+
+```python
+with RivalsDataClient() as rd:
+    stats = rd.get_player("GS-").stats.classes(season=20)
+    for row in stats.classes:
+        print(row.player_class, row.competitive.win_rate)
+    print(stats.excluded)  # Unknown roles or incomplete win/loss records
+```
+
+Win rates are `total wins / (total wins + total losses)`, rounded to an integer
+percent. They are weighted by hero records, rather than averaging hero win
+rates. Switching heroes can make one match contribute to multiple records;
+these totals describe hero participation, not distinct matches. Empty modes
+have a `None` win rate. Role mappings were observed on RivalsData on
+2026-09-30, including Deadpool's separate role IDs; generic Deadpool and unknown
+IDs are excluded rather than assigned a guessed class.
+
+Character playtime was checked with Camoufox on 2026-09-30. Player hero stats
+did not expose cumulative hours, including in All Seasons. Match details do
+provide seconds in `match.teams[].players[].heroes[].play_time`; the site shows
+these as minutes and seconds when hovering a hero portrait. Sum the relevant
+player's entries across distinct retrieved matches and divide by 3600 to get
+character hours for those matches. Incomplete history prevents treating this as
+a lifetime total. See [the playtime investigation](docs/API.md#character-playtime-investigation-2026-09-30)
+for the observed fields and example.
+
 ## MCP server (ChatGPT and Claude)
 
 Install the MCP extra and the package:

{rivalsdata_api-1.1.1 → rivalsdata_api-1.2.0}/docs/API.md

@@ -50,6 +50,41 @@ none of these, it returns `None`.
 
 ## Observed UI and routes
 
+`player.stats.classes(season=...)` derives tank (Vanguard), support (Strategist),
+and DPS (Duelist) totals from `/player/stats/heroes`; it does not call a class
+endpoint. It sums games/wins/losses separately for competitive and quickplay,
+and MVP/SVP counts when every included row supplies them. Win rate is calculated
+from summed wins and losses. Unknown classes and incomplete win/loss rows appear
+in `excluded`. Hero switching can count a single match in multiple hero records,
+so class totals are participation counts rather than distinct matches.
+
+The roster at `/stats` on 2026-09-30 identifies Deadpool variants as 10571
+(tank), 10572 (DPS), and 10573 (support), Daredevil as 1055, and Angela as 1056.
+
+### Character playtime investigation (2026-09-30)
+
+Using Camoufox (the package's optional browser dependency), the public GS-
+profile (`1970288503`) was inspected in Stats > Heroes for the current season
+and All Seasons. Expanded hero cards showed games, wins/losses, win rate, KDA,
+accuracy, MVP/SVP counts, combat averages, and team-ups. Neither the UI nor the
+captured `/player/heroes` and `/player/stats/heroes` responses supplied cumulative
+hero playtime. The all-seasons stats request returned 49 hero rows, including
+Deadpool's distinct role variants.
+
+Match details do expose per-character time in seconds at
+`teams[].players[].heroes[].play_time`. For match
+`5518155_1790655030_1272083_11001_11`, the match duration was 584 seconds and GS-'s
+Loki entry contained `play_time=583.8668914120644`. Hovering the hero portrait
+displayed `Loki` and `9:43`. The observed frontend formatter takes
+`floor(play_time / 60)` minutes and `floor(play_time % 60)` seconds.
+
+Hours for a character over a supplied set of matches can be calculated by
+summing that player's matching hero entries and dividing by 3600. Include all
+matching entries (a hero can have multiple usage segments), and deduplicate
+match IDs. This produces time for the retrieved matches, not a guaranteed
+lifetime or season total: history and detail availability may be incomplete.
+No automatic bulk match fetch was added as part of class statistics.
+
 | UI route | What the UI exposes |
 | --- | --- |
 | `/` | Search, top leaderboard, favorites, top heroes, and top team-ups. |

{rivalsdata_api-1.1.1 → rivalsdata_api-1.2.0}/docs/PROJECT_CONTEXT.md

@@ -15,7 +15,7 @@ as public, stable methods. Keep requests respectful and conservative.
 ## Current package
 
 - Distribution: `rivalsdata-api`; import: `rivalsdata`.
-- Version: `1.1.0`.
+- Version: `1.2.0`.
 - Python `>=3.10`, Hatchling build, `src/` layout.
 - Runtime HTTP dependency: `curl-cffi`; optional browser fallback: Camoufox.
 - Public entry point: `RivalsDataClient`.
@@ -45,7 +45,7 @@ copy of the full response.
 Lazy subresources include `player.heroes.fetch(...)`, `player.matches.fetch(...)`,
 `player.teammates.fetch(...)`, `player.crosshairs.fetch()`,
 `player.proficiency.fetch()`, `player.punishments.fetch()`,
-`player.name_history.fetch()`, and `player.stats.heroes/maps/bans(...)`.
+`player.name_history.fetch()`, and `player.stats.heroes/maps/bans/classes(...)`.
 Client-wide resources include `client.leaderboards`, `client.heroes`,
 `client.team_ups`, `client.insights`, `client.factions`, and `client.matches`.
 `client.profiles` and `client.favorites` have typed read methods. The profile
@@ -54,6 +54,21 @@ Favorites requires numeric UIDs and returns player summary rows.
 Rows offer `.win_rate` and `.winrate` integer-percent access when data supports
 it; all original data remains in mapping access.
 
+`player.stats.classes(season=...)` groups observed hero IDs into tank, support,
+and DPS. It sums games, wins, losses, and available MVP/SVP counts separately
+for competitive and quickplay, with win rates calculated from summed wins and
+losses. The response has typed `classes` rows and an `excluded` list for unknown
+roles or incomplete win/loss data. MCP exposes it through `get_player_stats`
+with `category="classes"`. Hero switching means totals count participation,
+not unique matches. Role IDs and the corrected Angela/Daredevil IDs were
+verified against RivalsData's roster on 2026-09-30; Deadpool has separate role
+variants (10571/10572/10573), while generic 1057 remains unclassified.
+
+Camoufox inspection found no cumulative hero hours in current-season or
+all-seasons player stats. Match hero usage does include `play_time` in seconds.
+See `docs/API.md` for the recorded investigation; no playtime aggregation
+method was added.
+
 ## Observed API details
 
 The major UI areas inspected are home, player profile/tabs, global leaderboard,
@@ -103,7 +118,7 @@ Use a virtual environment. Install editable dependencies with
 fallback work. The global host Python has unrelated package conflicts; don't
 change global dependencies to resolve those.
 
-No automated test suite is currently tracked. Don't add network-dependent
-checks to routine development; use mocked tests when the project owner asks for
-tests. Ruff and wheel builds are available for code checks. Commit coherent
+Mocked tests in `tests/` cover hero lookups, typed responses, and calculated
+class stats. Keep network-dependent checks opt-in. Run pytest, Ruff, and package
+builds for code checks. Commit coherent
 milestones and push to `origin` when explicitly requested by the project owner.

{rivalsdata_api-1.1.1 → rivalsdata_api-1.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rivalsdata-api"
-version = "1.1.1"
+version = "1.2.0"
 description = "Python client and MCP server for public Marvel Rivals stats from RivalsData"
 keywords = ["marvel-rivals", "rivalsdata", "game-stats", "api-client", "mcp"]
 readme = "README.md"

{rivalsdata_api-1.1.1 → rivalsdata_api-1.2.0}/src/rivalsdata/__init__.py

@@ -7,10 +7,13 @@ from .exceptions import (
     RivalsDataError,
     RivalsDataHTTPError,
 )
-from .hero_ids import HERO_NAMES, hero_id, hero_name
+from .hero_ids import HERO_CLASSES, HERO_NAMES, hero_class, hero_id, hero_name
 from .models import (
     BanRecord,
     Character,
+    ClassModeStats,
+    ClassStatsRecord,
+    ClassStatsResponse,
     CombatAverages,
     CommBanHero,
     CommBanInsights,
@@ -74,9 +77,13 @@ from .models import (
 )
 
 __all__ = [
+    "HERO_CLASSES",
     "HERO_NAMES",
     "BanRecord",
     "Character",
+    "ClassModeStats",
+    "ClassStatsRecord",
+    "ClassStatsResponse",
     "CloudflareError",
     "CombatAverages",
     "CommBanHero",
@@ -142,7 +149,8 @@ __all__ = [
     "Top500Season",
     "XPPage",
     "XPRecord",
+    "hero_class",
     "hero_id",
     "hero_name",
 ]
-__version__ = "1.1.0"
+__version__ = "1.2.0"

{rivalsdata_api-1.1.1 → rivalsdata_api-1.2.0}/src/rivalsdata/hero_ids.py

@@ -46,9 +46,12 @@ HERO_NAMES: dict[str, str] = {
     "1052": "Iron Fist",
     "1053": "Emma Frost",
     "1054": "Phoenix",
-    "1055": "Angela",
-    "1056": "Daredevil",
+    "1055": "Daredevil",
+    "1056": "Angela",
     "1057": "Deadpool",
+    "10571": "Tankpool",
+    "10572": "DPSpool",
+    "10573": "Stratpool",
     "1058": "Gambit",
     "1059": "Elsa Bloodstone",
     "1060": "White Fox",
@@ -61,6 +64,30 @@ HERO_NAMES: dict[str, str] = {
     "1067": "Gorr the God Butcher",
 }
 
+# Observed on https://rivalsdata.com/stats on 2026-09-30. The unspecialized
+# Deadpool ID (1057) has no single role and is deliberately left unresolved.
+HERO_CLASSES: dict[str, str] = {
+    **dict.fromkeys((
+        "1011", "1018", "1022", "1027", "1035", "1037", "1039", "1042",
+        "1051", "1053", "1056", "1062", "1065", "1066", "10571",
+    ), "tank"),
+    **dict.fromkeys((
+        "1016", "1020", "1023", "1025", "1028", "1031", "1046", "1047",
+        "1050", "1058", "1060", "1064", "10573",
+    ), "support"),
+    **dict.fromkeys((
+        "1014", "1015", "1017", "1021", "1024", "1026", "1029", "1030",
+        "1032", "1033", "1034", "1036", "1038", "1040", "1041", "1043",
+        "1044", "1045", "1048", "1049", "1052", "1054", "1055", "1059",
+        "1061", "1063", "1067", "10572",
+    ), "dps"),
+}
+
+
+def hero_class(hero_id: object) -> str | None:
+    """Return tank, support, or dps for a known role-specific hero ID."""
+    return HERO_CLASSES.get(str(hero_id))
+
 
 def hero_name(hero_id: object) -> str | None:
     """Resolve a known playable hero ID, preserving unknown IDs for callers."""

{rivalsdata_api-1.1.1 → rivalsdata_api-1.2.0}/src/rivalsdata/mcp_server.py

@@ -410,10 +410,14 @@ def get_player_matches(
 def get_player_stats(
     uid_or_name: str, category: str = "heroes", season: int | None = None
 ) -> Any:
-    """Get player stats; category must be heroes, maps, or bans."""
-    methods = {"heroes": "heroes", "maps": "maps", "bans": "bans"}
+    """Get player stats: heroes, maps, bans, or calculated classes.
+
+    Classes sum hero wins/losses by tank/support/dps and game mode; these are
+    hero participation totals, which can count a match more than once.
+    """
+    methods = {"heroes": "heroes", "maps": "maps", "bans": "bans", "classes": "classes"}
     if category not in methods:
-        raise ValueError("category must be one of: heroes, maps, bans")
+        raise ValueError("category must be one of: heroes, maps, bans, classes")
     def fetch(client: RivalsDataClient, value: str, category: str,
               season: int | None) -> Any:
         return getattr(client.get_player(value).stats, methods[category])(season=season)

{rivalsdata_api-1.1.1 → rivalsdata_api-1.2.0}/src/rivalsdata/models.py

@@ -399,6 +399,47 @@ class HeroStatsRecord(Character):
                 self._data[key] = HeroModeStats(self._data[key])
 
 
+class ClassModeStats(HeroModeStats):
+    """Calculated mode totals whose win rate is always a percentage."""
+
+    @property
+    def win_rate(self) -> int | None:
+        # Upstream win-rate fields can be fractions or percentages. Derived
+        # rates use counts so that a calculated 1% is not interpreted as 100%.
+        wins, losses = self._data["wins"], self._data["losses"]
+        total = wins + losses
+        return round(wins * 100 / total) if total else None
+
+
+class ClassStatsRecord(DataModel):
+    """Calculated hero participation totals for one player class."""
+
+    player_class: str
+    role: str
+    hero_ids: list[int | str]
+    competitive: ClassModeStats
+    quickplay: ClassModeStats
+
+    def __init__(self, data: Mapping[str, Any] | None = None, **values: Any) -> None:
+        super().__init__(data, **values)
+        for key in ("competitive", "quickplay"):
+            if isinstance(self._data.get(key), Mapping):
+                self._data[key] = ClassModeStats(self._data[key])
+
+
+class ClassStatsResponse(DataModel):
+    """Derived class totals and hero/mode rows excluded from calculation."""
+
+    classes: list[ClassStatsRecord]
+    excluded: list[DataModel]
+
+    def __init__(self, data: Mapping[str, Any] | None = None, **values: Any) -> None:
+        super().__init__(data, **values)
+        self._data["classes"] = [
+            ClassStatsRecord(row) for row in self._data.get("classes", [])
+        ]
+
+
 class HeroDetail(DataModel):
     hero: Character | None
     stats: Character | None

{rivalsdata_api-1.1.1 → rivalsdata_api-1.2.0}/src/rivalsdata/resources.py

@@ -6,9 +6,11 @@ from collections.abc import Mapping
 from typing import Any, Literal
 from urllib.parse import quote
 
+from .hero_ids import hero_class
 from .models import (
     BanRecord,
     Character,
+    ClassStatsResponse,
     CommBanInsights,
     CrosshairRecord,
     DataModel,
@@ -207,6 +209,58 @@ class PlayerStats(PlayerResource):
         payload = {"season": season} if season is not None else {}
         return _many(self._post("/player/stats/heroes", **payload), HeroStatsRecord)
 
+    def classes(self, *, season: int | None = None) -> ClassStatsResponse:
+        """Sum hero records by tank/support/dps, separately for each mode.
+
+        Win rate uses total wins / (wins + losses), not the average of hero
+        percentages. Counts describe hero participation: switching heroes can
+        cause one match to contribute to multiple hero or class records.
+        Unknown roles and incomplete win/loss rows are listed in ``excluded``.
+        """
+        groups = {
+            name: {"player_class": name, "role": role, "hero_ids": [],
+                   "competitive": [], "quickplay": []}
+            for name, role in (("tank", "Vanguard"), ("support", "Strategist"),
+                               ("dps", "Duelist"))
+        }
+        excluded = []
+        for hero in self.heroes(season=season):
+            identifier = hero.get("hero_id")
+            name = hero_class(identifier)
+            if name is None:
+                excluded.append({"hero_id": identifier, "reason": "unknown_class"})
+                continue
+            group = groups[name]
+            group["hero_ids"].append(identifier)
+            for mode in ("competitive", "quickplay"):
+                row = hero.get(mode)
+                if row is None:
+                    continue
+                counts = [row.get(key) for key in ("wins", "losses")]
+                if any(not isinstance(value, (int, float)) or isinstance(value, bool)
+                       or value < 0 for value in counts):
+                    excluded.append({"hero_id": identifier, "mode": mode,
+                                     "reason": "missing_or_invalid_win_loss_counts"})
+                    continue
+                group[mode].append(row)
+        for group in groups.values():
+            for mode in ("competitive", "quickplay"):
+                rows = group[mode]
+                totals = {key: sum(row[key] for row in rows)
+                          for key in ("wins", "losses")}
+                totals["games"] = sum(
+                    row.get("games") if isinstance(row.get("games"), (int, float))
+                    else row["wins"] + row["losses"] for row in rows
+                )
+                for key in ("mvps", "svps"):
+                    if rows and all(isinstance(row.get(key), (int, float))
+                                    for row in rows):
+                        totals[key] = sum(row[key] for row in rows)
+                total = totals["wins"] + totals["losses"]
+                totals["win_rate"] = round(totals["wins"] * 100 / total) if total else None
+                group[mode] = totals
+        return ClassStatsResponse({"classes": list(groups.values()), "excluded": excluded})
+
     def maps(self, *, season: int | None = None) -> list[MapRecord]:
         payload = {"season": season} if season is not None else {}
         return _many(self._post("/player/stats/maps", **payload), MapRecord)

rivalsdata_api-1.2.0/tests/test_class_stats.py

@@ -0,0 +1,57 @@
+from rivalsdata import (
+    ClassModeStats,
+    ClassStatsRecord,
+    HeroModeStats,
+    hero_class,
+    hero_name,
+)
+from rivalsdata.resources import PlayerStats
+
+
+class HeroClient:
+    def _post_json(self, path, payload):
+        self.request = path, payload
+        return [
+            {"hero_id": 1011, "competitive": {"wins": 9, "losses": 1, "games": 10}},
+            {"hero_id": 1018, "competitive": {"wins": 1, "losses": 1, "games": 2}},
+            {"hero_id": 10571, "quickplay": {"wins": 3, "losses": 1}},
+            {"hero_id": 10572, "competitive": {"wins": 2, "losses": 0}},
+            {"hero_id": 10573, "competitive": {"wins": 0, "losses": 2}},
+            {"hero_id": 1016, "competitive": {"wins": 3}},
+            {"hero_id": 1057, "competitive": {"wins": 4, "losses": 0}},
+            {"hero_id": 9999, "competitive": {"wins": 8, "losses": 0}},
+        ]
+
+
+def test_weighted_class_totals_modes_and_exclusions():
+    client = HeroClient()
+    result = PlayerStats(client, 123).classes(season=20)
+    groups = {row.player_class: row for row in result.classes}
+
+    assert client.request == ("/player/stats/heroes", {"uid": 123, "season": 20})
+    assert isinstance(groups["tank"], ClassStatsRecord)
+    assert isinstance(groups["tank"].competitive, HeroModeStats)
+    assert groups["tank"].competitive.win_rate == 83  # 10/12; mean of hero rates is 70
+    assert groups["tank"].competitive.games == 12
+    assert groups["tank"].quickplay.games == 4
+    assert groups["tank"].quickplay.win_rate == 75
+    assert groups["support"].competitive.win_rate == 0
+    assert groups["dps"].competitive.win_rate == 100
+    assert groups["dps"].quickplay.win_rate is None
+    assert len(result.excluded) == 3
+    assert result.to_dict()["classes"][0]["competitive"]["win_rate"] == 83
+
+
+def test_roles_use_observed_ids_and_do_not_guess_generic_deadpool():
+    assert hero_class(10571) == "tank"
+    assert hero_class(10572) == "dps"
+    assert hero_class(10573) == "support"
+    assert hero_class(1057) is None
+    assert hero_name(1055) == "Daredevil"
+    assert hero_name(1056) == "Angela"
+
+
+def test_one_percent_is_not_treated_as_a_fraction():
+    row = ClassModeStats({"wins": 1, "losses": 99, "win_rate": 1})
+    assert row.win_rate == 1
+    assert row.winrate == 1