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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rivalsdata-api
-Version: 1.2.1
+Version: 1.2.3
 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,6 +86,11 @@ 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"`. Pass a numeric season ID for that season, or
@@ -110,8 +116,12 @@ 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;
-these totals describe hero participation, not distinct matches. Empty modes
+rates. The response's `metadata` identifies the source, formula, and requested
+season scope. Upstream hero-switch attribution is unknown; hero records may
+overlap within a match, so these totals cannot establish distinct match counts
+or the player's overall match win rate. All-seasons coverage is limited to
+records returned by the source; complete lifetime coverage is unverified.
+Excluded rows also produce a metadata warning. 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.

{rivalsdata_api-1.2.1 → rivalsdata_api-1.2.3}/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,6 +50,11 @@ 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"`. Pass a numeric season ID for that season, or
@@ -74,8 +80,12 @@ 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;
-these totals describe hero participation, not distinct matches. Empty modes
+rates. The response's `metadata` identifies the source, formula, and requested
+season scope. Upstream hero-switch attribution is unknown; hero records may
+overlap within a match, so these totals cannot establish distinct match counts
+or the player's overall match win rate. All-seasons coverage is limited to
+records returned by the source; complete lifetime coverage is unverified.
+Excluded rows also produce a metadata warning. 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.

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

@@ -48,6 +48,12 @@ 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),
@@ -59,8 +65,14 @@ 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.
+in `excluded`. The response includes `metadata` with `source`, `counts_basis`,
+`win_rate_formula`, `unique_matches_verified`, `hero_switch_attribution`,
+`season`, `season_scope`, and `warnings`. Numeric seasons have scope `season`,
+`"all"` and `-1` normalize to season/scope `"all"`, and an omitted season has
+scope `endpoint_default` with season `None`. Hero-switch attribution is unknown,
+so summed hero records cannot establish unique match counts or a player's
+overall match win rate. Complete lifetime coverage for all-seasons data is
+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.

{rivalsdata_api-1.2.1 → rivalsdata_api-1.2.3}/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.1`.
+- 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,6 +54,12 @@ 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. 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.
@@ -63,8 +69,12 @@ 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
+with `category="classes"`. Response `metadata` describes the source, formula,
+season scope, and limitations. Upstream hero-switch attribution and distinct
+match counts are unverified; do not derive player overall win rate from class
+totals. All-seasons coverage is limited to returned records, with complete
+lifetime coverage unverified. Excluded rows produce a metadata warning.
+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.
 

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

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

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

{rivalsdata_api-1.2.1 → rivalsdata_api-1.2.3}/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>'
             )
@@ -414,7 +419,9 @@ def get_player_stats(
     """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.
+    summed hero records, which may overlap within a match. The response metadata
+    explains the calculation and scope; class totals cannot establish a player's
+    overall match win rate. Upstream hero-switch attribution is unknown.
     Supply a season ID or "all" for combined all-seasons totals. Omitting the
     season uses the endpoint default.
     """

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

@@ -428,10 +428,11 @@ class ClassStatsRecord(DataModel):
 
 
 class ClassStatsResponse(DataModel):
-    """Derived class totals and hero/mode rows excluded from calculation."""
+    """Derived class totals, excluded rows, and calculation metadata."""
 
     classes: list[ClassStatsRecord]
     excluded: list[DataModel]
+    metadata: DataModel
 
     def __init__(self, data: Mapping[str, Any] | None = None, **values: Any) -> None:
         super().__init__(data, **values)
@@ -983,7 +984,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.1 → rivalsdata_api-1.2.3}/src/rivalsdata/resources.py

@@ -225,8 +225,10 @@ class PlayerStats(PlayerResource):
         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.
+        percentages. Counts are summed upstream hero records. The upstream
+        attribution rule for hero switches is unknown, so distinct match
+        counts cannot be established from these rows. ``metadata`` describes
+        the calculation and requested season scope.
         Unknown roles and incomplete win/loss rows are listed in ``excluded``.
         """
         groups = {
@@ -271,7 +273,34 @@ class PlayerStats(PlayerResource):
                 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})
+        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."
+        ]
+        if all_seasons:
+            warnings.append(
+                "All-seasons results cover the records returned by the source; "
+                "complete lifetime coverage is not verified."
+            )
+        if excluded:
+            warnings.append(
+                "Some hero or mode records were excluded; see excluded for details."
+            )
+        metadata = {
+            "source": "/player/stats/heroes",
+            "counts_basis": "summed_hero_records",
+            "win_rate_formula": "wins / (wins + losses) * 100",
+            "unique_matches_verified": False,
+            "hero_switch_attribution": "unknown",
+            "season": "all" if all_seasons else season,
+            "season_scope": "all" if all_seasons else (
+                "endpoint_default" if season is None else "season"
+            ),
+            "warnings": warnings,
+        }
+        return ClassStatsResponse({"classes": list(groups.values()), "excluded": excluded,
+                                   "metadata": metadata})
 
     def maps(self, *, season: int | None = None) -> list[MapRecord]:
         payload = {"season": season} if season is not None else {}