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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: rivalsdata-api
-Version: 1.2.2
+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
@@ -116,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.2 → rivalsdata_api-1.2.3}/README.md

@@ -80,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.2 → rivalsdata_api-1.2.3}/docs/API.md

@@ -65,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.2 → rivalsdata_api-1.2.3}/docs/PROJECT_CONTEXT.md

@@ -69,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.2 → rivalsdata_api-1.2.3}/pyproject.toml

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

@@ -419,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.2 → 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)

{rivalsdata_api-1.2.2 → 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 {}