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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rivalsdata-api
-Version: 1.2.0
+Version: 1.2.2
 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
@@ -64,6 +64,7 @@ print(hero_id("Loki"))  # 1016
 with RivalsDataClient() as rd:
     player = rd.get_player("GS-")  # numeric UID works too
     print(player.name, player.level, player.rank_game_season)
+    print(player.win_rate)  # Current-season competitive win rate
 
     # Player profile sections are lazy resource managers.
     hero_season = player.heroes.fetch(season=20)
@@ -85,20 +86,34 @@ with RivalsDataClient() as rd:
 print(hero_season[0].win_rate)  # integer percent when wins/losses are present
 ```
 
+The player overview's overall win rate (`player.win_rate`) is the **current-season
+competitive win rate**. It uses the latest available competitive season with
+usable counts when a direct source rate is absent; it does not combine seasons.
+Hero and class stats use the season selector supplied to their own methods.
+
 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`,
+`category="classes"`. Pass a numeric season ID for that season, or
+`season="all"` for combined all-seasons data, matching `player.heroes.fetch`.
+Omitting the season uses the endpoint default. `player.stats.heroes` also
+accepts `season="all"`. 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)
+    player = rd.get_player("GS-")
+    stats = player.stats.classes(season=20)
+    all_seasons = player.stats.classes(season="all")
     for row in stats.classes:
         print(row.player_class, row.competitive.win_rate)
     print(stats.excluded)  # Unknown roles or incomplete win/loss records
 ```
 
+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.
+
 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;

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

@@ -28,6 +28,7 @@ print(hero_id("Loki"))  # 1016
 with RivalsDataClient() as rd:
     player = rd.get_player("GS-")  # numeric UID works too
     print(player.name, player.level, player.rank_game_season)
+    print(player.win_rate)  # Current-season competitive win rate
 
     # Player profile sections are lazy resource managers.
     hero_season = player.heroes.fetch(season=20)
@@ -49,20 +50,34 @@ with RivalsDataClient() as rd:
 print(hero_season[0].win_rate)  # integer percent when wins/losses are present
 ```
 
+The player overview's overall win rate (`player.win_rate`) is the **current-season
+competitive win rate**. It uses the latest available competitive season with
+usable counts when a direct source rate is absent; it does not combine seasons.
+Hero and class stats use the season selector supplied to their own methods.
+
 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`,
+`category="classes"`. Pass a numeric season ID for that season, or
+`season="all"` for combined all-seasons data, matching `player.heroes.fetch`.
+Omitting the season uses the endpoint default. `player.stats.heroes` also
+accepts `season="all"`. 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)
+    player = rd.get_player("GS-")
+    stats = player.stats.classes(season=20)
+    all_seasons = player.stats.classes(season="all")
     for row in stats.classes:
         print(row.player_class, row.competitive.win_rate)
     print(stats.excluded)  # Unknown roles or incomplete win/loss records
 ```
 
+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.
+
 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;

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

@@ -48,12 +48,22 @@ integer percentage from a direct win-rate field, `wins`/`losses`, or the
 competitive profile row's `win_count`/`battle_count`. If the source provides
 none of these, it returns `None`.
 
+The player overview's overall win rate (`Player.win_rate`) refers to the current
+competitive season, using the latest available competitive season with usable
+counts when a direct source rate is absent. It does not sum historical seasons.
+MCP overview/dashboard descriptions identify this scope, and the dashboard labels
+the value as a season win rate. Hero and class rates follow their season selectors.
+
 ## 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
+accepting a numeric season ID or `season="all"` (sent to the API as `-1`). The
+all-seasons selection combines the returned hero records across seasons;
+omitting the season keeps the endpoint default. `player.stats.heroes` and MCP
+`get_player_stats` support the same selector. The method also sums
+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.

{rivalsdata_api-1.2.0 → rivalsdata_api-1.2.2}/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.0`.
+- Version: `1.2.2`.
 - Python `>=3.10`, Hatchling build, `src/` layout.
 - Runtime HTTP dependency: `curl-cffi`; optional browser fallback: Camoufox.
 - Public entry point: `RivalsDataClient`.
@@ -54,8 +54,18 @@ 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.
 
+The player overview's overall win rate (`player.win_rate`) is for the current
+competitive season (latest available season with usable counts when there is no
+direct source rate), not an all-seasons aggregate. Keep this scope explicit in
+docs, MCP descriptions, and dashboard labels. Hero/class stats have separate
+season selectors.
+
 `player.stats.classes(season=...)` groups observed hero IDs into tank, support,
-and DPS. It sums games, wins, losses, and available MVP/SVP counts separately
+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
 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.0 → rivalsdata_api-1.2.2}/pyproject.toml

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

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

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

@@ -108,7 +108,11 @@ def search_players(name: str) -> dict[str, Any]:
 
 @mcp.tool()
 def get_player(uid_or_name: str) -> dict[str, Any]:
-    """Get a public player overview by numeric UID or in-game name."""
+    """Get a public player overview by numeric UID or in-game name.
+
+    The overview's overall win rate refers to the current competitive season
+    (latest available season with usable counts), not all seasons combined.
+    """
     return _call(lambda client, value: client.get_player(value).raw, uid_or_name)
 
 
@@ -141,6 +145,7 @@ def show_player_dashboard(
     combining live-match, hero, and match-history pulls. MCP Apps hosts can
     render the returned dashboard resource; all values are escaped before HTML
     output.
+    The competitive record and win rate are for the latest available season.
     """
     with RivalsDataClient() as client:
         player = client.get_player(uid_or_name)
@@ -168,7 +173,7 @@ def show_player_dashboard(
             competitive_summary = (
                 f'<div class="competitive-line">'
                 f'<span>{battles:,} competitive games</span>'
-                + (f'<span>{rate}% win rate</span>' if rate is not None else "")
+                + (f'<span>{rate}% season win rate</span>' if rate is not None else "")
                 + (f'<span>{escape(str(score))} RP</span>' if score is not None else "")
                 + '</div>'
             )
@@ -408,19 +413,23 @@ def get_player_matches(
 
 @mcp.tool()
 def get_player_stats(
-    uid_or_name: str, category: str = "heroes", season: int | None = None
+    uid_or_name: str, category: str = "heroes",
+    season: int | Literal["all"] | None = None,
 ) -> Any:
     """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.
+    Supply a season ID or "all" for combined all-seasons totals. Omitting the
+    season uses the endpoint default.
     """
     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")
     def fetch(client: RivalsDataClient, value: str, category: str,
-              season: int | None) -> Any:
-        return getattr(client.get_player(value).stats, methods[category])(season=season)
+              season: int | Literal["all"] | 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)
 
 

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

@@ -983,7 +983,11 @@ class Player(DataModel):
 
     @property
     def win_rate(self) -> int | None:
-        """Overall competitive win rate when the profile includes wins/losses."""
+        """Current-season competitive win rate when profile counts are available.
+
+        Uses a direct source rate or the latest available competitive season
+        with usable counts. This property does not aggregate across seasons.
+        """
         direct = StatRecord(self._data).win_rate
         if direct is not None:
             return direct

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

@@ -205,13 +205,25 @@ class PlayerHeroes(PlayerResource):
 class PlayerStats(PlayerResource):
     """Detailed per-player statistics tabs."""
 
-    def heroes(self, *, season: int | None = None) -> list[HeroStatsRecord]:
-        payload = {"season": season} if season is not None else {}
+    def heroes(
+        self, *, season: int | Literal["all"] | None = None
+    ) -> list[HeroStatsRecord]:
+        """Fetch mode-specific hero stats for a season or all seasons.
+
+        ``season="all"`` sends the API's all-seasons selector (-1). Omitting
+        ``season`` preserves the endpoint default.
+        """
+        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)
 
-    def classes(self, *, season: int | None = None) -> ClassStatsResponse:
+    def classes(
+        self, *, season: int | Literal["all"] | None = None
+    ) -> ClassStatsResponse:
         """Sum hero records by tank/support/dps, separately for each mode.
 
+        Supply a season ID or ``season="all"`` for combined all-seasons totals.
+        Omitting ``season`` preserves the endpoint default.
         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.

{rivalsdata_api-1.2.0 → rivalsdata_api-1.2.2}/tests/test_class_stats.py

@@ -1,3 +1,5 @@
+import pytest
+
 from rivalsdata import (
     ClassModeStats,
     ClassStatsRecord,
@@ -55,3 +57,46 @@ 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
+
+
+class SeasonClient:
+    def _post_json(self, path, payload):
+        self.request = path, payload
+        wins = {None: 2, 20: 3, -1: 12}[payload.get("season")]
+        return [{"hero_id": 1016, "competitive": {"wins": wins, "losses": 1}}]
+
+
+@pytest.mark.parametrize("season,payload,wins", [
+    (None, {"uid": 123}, 2),
+    (20, {"uid": 123, "season": 20}, 3),
+    ("all", {"uid": 123, "season": -1}, 12),
+    (-1, {"uid": 123, "season": -1}, 12),
+])
+def test_class_season_selector_uses_the_selected_hero_data(season, payload, wins):
+    client = SeasonClient()
+    result = PlayerStats(client, 123).classes(season=season)
+    assert client.request == ("/player/stats/heroes", payload)
+    assert result.classes[1].competitive.wins == wins
+
+
+def test_detailed_hero_stats_accept_the_same_all_seasons_selector():
+    client = SeasonClient()
+    rows = PlayerStats(client, 123).heroes(season="all")
+    assert client.request == ("/player/stats/heroes", {"uid": 123, "season": -1})
+    assert rows[0].competitive.wins == 12
+
+
+def test_mcp_stats_exposes_all_seasons_and_forwards_the_selector(monkeypatch):
+    import asyncio
+    from types import SimpleNamespace
+
+    server = pytest.importorskip("rivalsdata.mcp_server", exc_type=ImportError)
+    client = SeasonClient()
+    client.get_player = lambda value: SimpleNamespace(stats=PlayerStats(client, 123))
+    monkeypatch.setattr(server, "_call", lambda fn, *a, **kw: fn(client, *a, **kw))
+    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
+    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"]