rivalsdata-api 1.2.3__tar.gz → 1.3.0__tar.gz

{rivalsdata_api-1.2.3 → rivalsdata_api-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rivalsdata-api
-Version: 1.2.3
+Version: 1.3.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
@@ -114,6 +114,29 @@ For MCP, use `get_player_stats(uid_or_name="GS-", category="classes", season=20)
 for one season, or `season="all"` for combined all-seasons stats. Both return
 the same class response structure.
 
+Detailed hero stats require a mode and match the website's selected tab:
+
+```python
+competitive = player.stats.heroes(mode="competitive", season="all")
+quickplay = player.stats.heroes(mode="quickplay", season=20)
+print(competitive[0].competitive.games)
+print(competitive[0].rank)  # Hero leaderboard position, or None if unavailable
+```
+
+Only heroes with data for the chosen mode are returned, with that mode's nested
+stats and a `mode` label; the other mode is omitted. Rows are sorted by the
+selected mode's games played descending, with ties retaining the JSON order.
+The source returns both modes in one response; filtering and sorting happen
+in this package, as they do on the website. Existing calls to
+`player.stats.heroes()` must now supply `mode`. MCP also requires `mode` when
+`get_player_stats` uses `category="heroes"`; other categories do not require it.
+The separate summary method `player.heroes.fetch()` keeps its existing behavior.
+
+Hero stats include the source's top-level `rank`, matching the **#N** displayed
+in the left-hand hero card. It is preserved for either mode and all-seasons
+requests when supplied by the source; it is not recalculated as a quickplay or
+all-seasons leaderboard position. Missing ranks are returned as `None`.
+
 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. The response's `metadata` identifies the source, formula, and requested

{rivalsdata_api-1.2.3 → rivalsdata_api-1.3.0}/README.md

@@ -78,6 +78,29 @@ For MCP, use `get_player_stats(uid_or_name="GS-", category="classes", season=20)
 for one season, or `season="all"` for combined all-seasons stats. Both return
 the same class response structure.
 
+Detailed hero stats require a mode and match the website's selected tab:
+
+```python
+competitive = player.stats.heroes(mode="competitive", season="all")
+quickplay = player.stats.heroes(mode="quickplay", season=20)
+print(competitive[0].competitive.games)
+print(competitive[0].rank)  # Hero leaderboard position, or None if unavailable
+```
+
+Only heroes with data for the chosen mode are returned, with that mode's nested
+stats and a `mode` label; the other mode is omitted. Rows are sorted by the
+selected mode's games played descending, with ties retaining the JSON order.
+The source returns both modes in one response; filtering and sorting happen
+in this package, as they do on the website. Existing calls to
+`player.stats.heroes()` must now supply `mode`. MCP also requires `mode` when
+`get_player_stats` uses `category="heroes"`; other categories do not require it.
+The separate summary method `player.heroes.fetch()` keeps its existing behavior.
+
+Hero stats include the source's top-level `rank`, matching the **#N** displayed
+in the left-hand hero card. It is preserved for either mode and all-seasons
+requests when supplied by the source; it is not recalculated as a quickplay or
+all-seasons leaderboard position. Missing ranks are returned as `None`.
+
 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. The response's `metadata` identifies the source, formula, and requested

{rivalsdata_api-1.2.3 → rivalsdata_api-1.3.0}/docs/API.md

@@ -21,7 +21,7 @@ and `.raw` so upstream additions are not discarded.
 | Player match history | `POST /player/matches/cached` (or `/player/matches`) | `uid`, `cursor`, optional `season`; cached endpoint also accepts `mode`, `hero`, `teammate` | Cached response keys observed: `matches`, `next_cursor`, `source`; match rows include `assists`, `deaths`, `game_mode_id`, `game_play_mode_id`, `hero_id`, `is_mvp`, `is_svp`, `is_win`, `kills`, `map_id`, `match_uid`, `os`, `placement`, `platform`, `rank_level`, `rank_score`, `score_change`, `season`, `team_score`, `timestamp`, `winner_camp`. A sample profile marked its history private; a private profile can return no visible match rows. |
 | Player teammates | `POST /player/teammates` | `uid`, optional `season`, `mode` | Array rows: `games`, `icon`, `losses`, `name`, `teammate_uid`, `wins`. |
 | Player proficiency | `POST /player/proficiency` | `uid` | Object keyed by account id (sample: `11001_{uid}`); each account has `hero_proficiency_infos` keyed by hero id, with `proficiency_level` and `proficiency_point`. |
-| Player hero stats | `POST /player/stats/heroes` | `uid`, optional `season` | Array rows: `competitive`, `hero_id`, `quickplay`, `rank`. Each mode includes games, wins/losses, KDA, MVP/SVP counts, accuracy, and `per_10`/`per_game` combat averages. |
+| Player hero stats | `POST /player/stats/heroes` | `uid`, optional `season`; wrapper requires `mode` (not sent upstream) | Source rows: `competitive`, `hero_id`, `quickplay`, `rank`. Each mode includes games, wins/losses, KDA, MVP/SVP counts, accuracy, and `per_10`/`per_game` combat averages. Wrapper selects one mode, sorts by its games, and includes `rank` (or `None`). |
 | Player map stats | `POST /player/stats/maps` | `uid`, optional `season` | Array rows: `map`, `competitive`, `quickplay`; each mode has games, wins, losses, winrate. |
 | Player ban stats | `POST /player/stats/bans` | `uid`, optional `season` | Array rows: `hero_id`, `matches`, `wins`, `losses`, `winrate`. |
 | Player punishments | `POST /player/punishments` | `uid` | Object keys: `chat`, `login`, `rank`; non-null entries include `expire`, `name`, `reason`, `time`, `uid`. |
@@ -77,6 +77,34 @@ unverified. Warnings flag those limitations and any excluded records.
 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.
 
+### Detailed hero mode selection and ordering
+
+`player.stats.heroes(mode="competitive", season="all")` requires either
+`"competitive"` or `"quickplay"`. Missing mode raises `TypeError`; unsupported
+values raise `ValueError`. The upstream `/player/stats/heroes` request still
+contains only UID and optional season, because the source returns both modes
+together. The wrapper filters heroes without the selected mode's data, omits
+the other mode's key, adds `mode`, and sorts by selected-mode `games` descending.
+Equal game counts retain source order. Access stats through the selected nested
+key, such as `row.competitive` or `row.quickplay`.
+
+`row.rank` is the source-supplied hero leaderboard position from the top-level
+JSON `rank` field, or `None` when unavailable. On 2026-10-01, GS-'s left-hand
+Loki card showed #408; both `/player/heroes` and `/player/stats/heroes` supplied
+`rank: 408` for hero 1016. The detailed Stats tab did not display that field.
+Mode filtering preserves it. All-seasons requests may also return a rank, but
+the wrapper does not infer its leaderboard period or recalculate it per mode.
+
+Camoufox inspection of GS-'s All Seasons page on 2026-10-01 found the JSON sorted
+by combined competitive + quickplay games. The Competitive tab's 40 rows and
+Quickplay tab's 39 rows each exactly matched sorting by that mode's games.
+Switching tabs sent no additional hero-stats request.
+
+MCP `get_player_stats(category="heroes", mode=..., season=...)` requires mode
+for heroes and rejects missing or invalid values before making a request.
+Other categories retain their behavior; class stats still aggregate both modes
+from the complete source response. `player.heroes.fetch()` is unchanged.
+
 ### Character playtime investigation (2026-09-30)
 
 Using Camoufox (the package's optional browser dependency), the public GS-

{rivalsdata_api-1.2.3 → rivalsdata_api-1.3.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.2.2`.
+- Version: `1.3.0`.
 - Python `>=3.10`, Hatchling build, `src/` layout.
 - Runtime HTTP dependency: `curl-cffi`; optional browser fallback: Camoufox.
 - Public entry point: `RivalsDataClient`.
@@ -65,7 +65,17 @@ and DPS. Supply a numeric season ID for one season or `season="all"` for
 combined all-seasons stats; the latter sends `season=-1` to the upstream API.
 The detailed `player.stats.heroes` method and MCP stats tool accept the same
 selector. Omitting the season keeps the endpoint default.
-It sums games, wins, losses, and available MVP/SVP counts separately
+Detailed `player.stats.heroes` now requires `mode="competitive"` or
+`mode="quickplay"`; it filters to that mode, omits the opposite mode key, and
+sorts by selected-mode games descending (stable ties), matching the website.
+MCP requires mode for category heroes; other categories do not require it.
+Class aggregation uses a private full-response fetch so both class modes stay
+available. Hero summaries (`player.heroes.fetch`) remain unchanged.
+Detailed hero rows always expose `rank` (None if absent), preserving the
+source's top-level hero leaderboard position shown as #N in the left card.
+It is not recalculated for quickplay or all seasons. GS-'s Loki was #408 in
+both the card and both hero endpoint responses on 2026-10-01.
+Class calculation 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`

{rivalsdata_api-1.2.3 → rivalsdata_api-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "rivalsdata-api"
-version = "1.2.3"
+version = "1.3.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.2.3 → rivalsdata_api-1.3.0}/src/rivalsdata/__init__.py

@@ -153,4 +153,4 @@ __all__ = [
     "hero_id",
     "hero_name",
 ]
-__version__ = "1.2.2"
+__version__ = "1.3.0"

{rivalsdata_api-1.2.3 → rivalsdata_api-1.3.0}/src/rivalsdata/mcp_server.py

@@ -415,9 +415,15 @@ def get_player_matches(
 def get_player_stats(
     uid_or_name: str, category: str = "heroes",
     season: int | Literal["all"] | None = None,
+    mode: Literal["competitive", "quickplay"] | None = None,
 ) -> Any:
     """Get player stats: heroes, maps, bans, or calculated classes.
 
+    Heroes REQUIRE mode="competitive" or mode="quickplay". Only that mode's
+    hero records are returned, sorted by its games played descending to match
+    the website. Mode is not used for the other categories.
+    Hero rows include rank: the source's hero leaderboard position, also shown
+    as #N in the left-hand profile card, or null when the source has no rank.
     Classes sum hero wins/losses by tank/support/dps and game mode; these are
     summed hero records, which may overlap within a match. The response metadata
     explains the calculation and scope; class totals cannot establish a player's
@@ -428,11 +434,17 @@ def get_player_stats(
     methods = {"heroes": "heroes", "maps": "maps", "bans": "bans", "classes": "classes"}
     if category not in methods:
         raise ValueError("category must be one of: heroes, maps, bans, classes")
+    if category == "heroes" and mode not in ("competitive", "quickplay"):
+        raise ValueError("heroes require mode=competitive or mode=quickplay")
     def fetch(client: RivalsDataClient, value: str, category: str,
-              season: int | Literal["all"] | None) -> Any:
+              season: int | Literal["all"] | None,
+              mode: Literal["competitive", "quickplay"] | None) -> Any:
         season_id = -1 if season == "all" else season
-        return getattr(client.get_player(value).stats, methods[category])(season=season_id)
-    return _call(fetch, uid_or_name, category, season)
+        filters: dict[str, Any] = {"season": season_id}
+        if category == "heroes":
+            filters["mode"] = mode
+        return getattr(client.get_player(value).stats, methods[category])(**filters)
+    return _call(fetch, uid_or_name, category, season, mode)
 
 
 @mcp.tool()

{rivalsdata_api-1.2.3 → rivalsdata_api-1.3.0}/src/rivalsdata/models.py

@@ -388,12 +388,21 @@ class HeroModeStats(StatRecord):
 
 
 class HeroStatsRecord(Character):
+    """Detailed hero stats including the source's leaderboard position.
+
+    ``rank`` is the number shown as #N in the profile's left-hand hero card.
+    It is shared source metadata, not a rank calculated for the selected mode.
+    None means the source did not supply a position.
+    """
+
+    mode: str | None
     competitive: HeroModeStats | None
     quickplay: HeroModeStats | None
     rank: int | str | None
 
     def __init__(self, data: Mapping[str, Any] | None = None, **values: Any) -> None:
         super().__init__(data, **values)
+        self._data.setdefault("rank", None)
         for key in ("competitive", "quickplay"):
             if isinstance(self._data.get(key), Mapping):
                 self._data[key] = HeroModeStats(self._data[key])

{rivalsdata_api-1.2.3 → rivalsdata_api-1.3.0}/src/rivalsdata/resources.py

@@ -206,13 +206,32 @@ class PlayerStats(PlayerResource):
     """Detailed per-player statistics tabs."""
 
     def heroes(
-        self, *, season: int | Literal["all"] | None = None
+        self, *, mode: Literal["competitive", "quickplay"],
+        season: int | Literal["all"] | None = None,
     ) -> list[HeroStatsRecord]:
-        """Fetch mode-specific hero stats for a season or all seasons.
+        """Fetch heroes for a required mode, in the website's most-played order.
 
+        The source supplies both modes together. This method keeps only heroes
+        with the selected mode's data, removes the other mode, and sorts by
+        selected-mode games descending. Ties retain the source order.
+        Each row includes ``rank`` (the source's hero leaderboard position,
+        also shown in the left-hand profile card), or None when unavailable.
         ``season="all"`` sends the API's all-seasons selector (-1). Omitting
         ``season`` preserves the endpoint default.
         """
+        if mode not in ("competitive", "quickplay"):
+            raise ValueError("mode must be competitive or quickplay")
+        heroes = [hero for hero in self._hero_records(season=season)
+                  if hero.get(mode) is not None]
+        heroes.sort(key=lambda hero: hero[mode].get("games", 0) or 0, reverse=True)
+        other_mode = "quickplay" if mode == "competitive" else "competitive"
+        return [HeroStatsRecord({key: value for key, value in hero.raw.items()
+                                 if key != other_mode}, mode=mode) for hero in heroes]
+
+    def _hero_records(
+        self, *, season: int | Literal["all"] | None = None
+    ) -> list[HeroStatsRecord]:
+        """Fetch both upstream modes for class aggregation and hero filtering."""
         season_id = -1 if season == "all" else season
         payload = {"season": season_id} if season_id is not None else {}
         return _many(self._post("/player/stats/heroes", **payload), HeroStatsRecord)
@@ -238,7 +257,7 @@ class PlayerStats(PlayerResource):
                                ("dps", "Duelist"))
         }
         excluded = []
-        for hero in self.heroes(season=season):
+        for hero in self._hero_records(season=season):
             identifier = hero.get("hero_id")
             name = hero_class(identifier)
             if name is None:
@@ -275,8 +294,8 @@ class PlayerStats(PlayerResource):
                 group[mode] = totals
         all_seasons = season in ("all", -1)
         warnings = [
-            "Hero records may overlap within a match. Class totals must not "
-            "be used to calculate the player's overall match win rate."
+            ("Hero records may overlap within a match. Class totals must not "
+             "be used to calculate the player's overall match win rate.")
         ]
         if all_seasons:
             warnings.append(

{rivalsdata_api-1.2.3 → rivalsdata_api-1.3.0}/tests/test_class_stats.py

@@ -7,7 +7,7 @@ from rivalsdata import (
     hero_class,
     hero_name,
 )
-from rivalsdata.resources import PlayerStats
+from rivalsdata.resources import PlayerHeroes, PlayerStats
 
 
 class HeroClient:
@@ -42,6 +42,7 @@ def test_weighted_class_totals_modes_and_exclusions():
     assert groups["dps"].quickplay.win_rate is None
     assert len(result.excluded) == 3
     assert result.to_dict()["classes"][0]["competitive"]["win_rate"] == 83
+    assert any("excluded" in warning for warning in result.metadata.warnings)
 
 
 def test_roles_use_observed_ids_and_do_not_guess_generic_deadpool():
@@ -77,13 +78,39 @@ def test_class_season_selector_uses_the_selected_hero_data(season, payload, wins
     result = PlayerStats(client, 123).classes(season=season)
     assert client.request == ("/player/stats/heroes", payload)
     assert result.classes[1].competitive.wins == wins
+    metadata = result.to_dict()["metadata"]
+    assert metadata["counts_basis"] == "summed_hero_records"
+    assert metadata["unique_matches_verified"] is False
+    assert metadata["hero_switch_attribution"] == "unknown"
+    assert metadata["season"] == ("all" if season in ("all", -1) else season)
+    assert metadata["season_scope"] == (
+        "all" if season in ("all", -1) else
+        "endpoint_default" if season is None else "season"
+    )
+    assert len(metadata["warnings"]) == (2 if season in ("all", -1) else 1)
 
 
 def test_detailed_hero_stats_accept_the_same_all_seasons_selector():
     client = SeasonClient()
-    rows = PlayerStats(client, 123).heroes(season="all")
+    rows = PlayerStats(client, 123).heroes(mode="competitive", season="all")
     assert client.request == ("/player/stats/heroes", {"uid": 123, "season": -1})
     assert rows[0].competitive.wins == 12
+    assert rows[0].mode == "competitive"
+    assert "quickplay" not in rows[0]
+    with pytest.raises(TypeError):
+        PlayerStats(client, 123).heroes(season="all")
+    with pytest.raises(ValueError):
+        PlayerStats(client, 123).heroes(mode="invalid", season="all")
+
+
+@pytest.mark.parametrize("season,season_id", [(None, None), (20, 20), ("all", -1)])
+def test_hero_summary_season_selector(season, season_id):
+    client = SeasonClient()
+    PlayerHeroes(client, 123).fetch(season=season)
+    expected = {"uid": 123}
+    if season_id is not None:
+        expected["season"] = season_id
+    assert client.request == ("/player/heroes", expected)
 
 
 def test_mcp_stats_exposes_all_seasons_and_forwards_the_selector(monkeypatch):
@@ -97,6 +124,8 @@ def test_mcp_stats_exposes_all_seasons_and_forwards_the_selector(monkeypatch):
     result = server.get_player_stats("123", category="classes", season="all")
     assert client.request == ("/player/stats/heroes", {"uid": 123, "season": -1})
     assert result.classes[1].competitive.wins == 12
+    assert result.metadata.season == "all"
+    assert result.metadata.season_scope == "all"
     tools = asyncio.run(server.mcp.list_tools())
     schema = next(tool.inputSchema for tool in tools if tool.name == "get_player_stats")
     assert {"const": "all", "type": "string"} in schema["properties"]["season"]["anyOf"]