vlrdevapi 2.4.1__tar.gz → 3.1.0__tar.gz

{vlrdevapi-2.4.1 → vlrdevapi-3.1.0}/.github/workflows/docs-check.yml

@@ -22,38 +22,28 @@ jobs:
           python-version: '3.12'
 
       - name: Install package
-        run: uv sync --group dev
+        run: uv sync --group dev --all-extras
 
-      # main always validates live against fresh vlr.gg data; never uses the
-      # cache. Branch/PR runs reuse fixtures cached by earlier runs in the
-      # same PR (within a 2h TTL), falling back to live fetches for anything
-      # missing, so the check is correct even with a partially-stale cache.
-      - name: Run MDX examples check (main, live)
-        if: github.ref_name == 'main'
-        run: uv run scripts/check_mdx_examples.py --live
-
-      # actions/cache v6.1.0, pinned to a reviewed commit SHA.
-      - name: Restore fixture cache (branch)
+      # Restore fixture cache scoped to the current ref (branch or main) and version prefix (v3).
+      # This ensures caches are never shared across unrelated branches or older versions.
+      - name: Restore fixture cache
         id: mdx-fixtures
-        if: github.ref_name != 'main'
         uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9
         with:
           path: fixtures.tar.gz
-          key: mdx-fixtures-${{ github.ref_name }}-run-${{ github.run_id }}
+          key: mdx-fixtures-v3-${{ github.ref_name }}-run-${{ github.run_id }}
           restore-keys: |
-            mdx-fixtures-${{ github.ref_name }}-
+            mdx-fixtures-v3-${{ github.ref_name }}-
 
-      - name: Unpack fixtures (branch)
-        if: github.ref_name != 'main'
+      - name: Unpack fixtures
         run: |
           if [ -f fixtures.tar.gz ]; then
             mkdir -p .cache
             tar -C .cache -xzf fixtures.tar.gz
           fi
 
-      - name: Check fixture cache age (branch, 2h TTL)
+      - name: Check fixture cache age (2h TTL)
         id: cache-age
-        if: github.ref_name != 'main'
         run: |
           matched="${{ steps.mdx-fixtures.outputs.cache-matched-key }}"
           now=$(date +%s)
@@ -73,8 +63,7 @@ jobs:
           fi
           echo "now=$now" >> "$GITHUB_OUTPUT"
 
-      - name: Run MDX examples check (branch)
-        if: github.ref_name != 'main'
+      - name: Run MDX examples check
         run: |
           if [ "${{ steps.cache-age.outputs.fresh }}" == "true" ]; then
             uv run scripts/check_mdx_examples.py --skip-warm
@@ -84,8 +73,8 @@ jobs:
 
       # always(): a run that fails validation still saved its warm fixtures,
       # so the next fix commit restores and validates fast instead of warming.
-      - name: Package fixtures (branch)
-        if: always() && github.ref_name != 'main' && steps.cache-age.outputs.fresh == 'false'
+      - name: Package fixtures
+        if: always() && steps.cache-age.outputs.fresh == 'false'
         run: |
           mkdir -p .cache/mdx-html
           if [ -n "$(ls -A .cache/mdx-html)" ]; then
@@ -94,9 +83,9 @@ jobs:
             rm -f fixtures.tar.gz
           fi
 
-      - name: Save fixture cache (branch)
-        if: always() && github.ref_name != 'main' && steps.cache-age.outputs.fresh == 'false'
+      - name: Save fixture cache
+        if: always() && steps.cache-age.outputs.fresh == 'false'
         uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9
         with:
           path: fixtures.tar.gz
-          key: mdx-fixtures-${{ github.ref_name }}-${{ steps.cache-age.outputs.now }}
+          key: mdx-fixtures-v3-${{ github.ref_name }}-${{ steps.cache-age.outputs.now }}

{vlrdevapi-2.4.1 → vlrdevapi-3.1.0}/.github/workflows/publish.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11', '3.12', '3.13', '3.14']
+        python-version: ['3.11', '3.12', '3.13', '3.14', '3.15']
 
     steps:
       - uses: actions/checkout@v7
@@ -23,7 +23,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync --group dev
+        run: uv sync --group dev --all-extras
 
       - name: Download fixtures
         run: uv run python scripts/download_fixtures.py

{vlrdevapi-2.4.1 → vlrdevapi-3.1.0}/.github/workflows/test.yml

@@ -5,6 +5,8 @@ on:
     paths:
       - 'src/**'
       - 'tests/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
       - 'scripts/download_fixtures.py'
       - '.github/workflows/test.yml'
   push:
@@ -12,6 +14,8 @@ on:
     paths:
       - 'src/**'
       - 'tests/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
       - 'scripts/download_fixtures.py'
       - '.github/workflows/test.yml'
 
@@ -20,7 +24,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11', '3.12', '3.13', '3.14']
+        python-version: ['3.11', '3.12', '3.13', '3.14', '3.15']
 
     steps:
       - uses: actions/checkout@v7
@@ -30,7 +34,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: uv sync --group dev
+        run: uv sync --group dev --all-extras
 
       - name: Download fixtures
         run: uv run python scripts/download_fixtures.py

{vlrdevapi-2.4.1 → vlrdevapi-3.1.0}/.gitignore

@@ -30,4 +30,6 @@ main.py
 official-docs/node_modules/
 
 # Zensical cache
-docs-py/.cache/
+docs-py/.cache/
+
+temp/

{vlrdevapi-2.4.1 → vlrdevapi-3.1.0}/CHANGELOG.md

@@ -5,6 +5,175 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [3.1.0] - 2026-10-25
+
+### Added
+
+- **Multi-Format Tabular Export Layer** — All Pydantic models now inherit from `ExportableModel`, enabling seamless tabular serialization into popular data science formats:
+  - `.to_records()` — extracts clean, unnested lists of Python dictionaries with semantic flattening across every namespace.
+  - `.to_df()` — converts records directly into a `pandas.DataFrame`.
+  - `.to_polars()` — converts records directly into a native `polars.DataFrame` with typed nested arrays (`pl.List(pl.String)`).
+  - `.to_csv(path=None)` — exports to standard CSV format with semicolon-delimited lists (`"Player;IGL"`) and in-memory string output when `path` is omitted.
+  - `.to_parquet(path, index=False)` — writes Apache Parquet files via pandas and pyarrow.
+  - `.to_excel(path, sheet_name="Sheet1", index=False)` — exports Excel `.xlsx` spreadsheets via pandas and openpyxl.
+  - `.to_json(path=None, indent=2)` — exports clean serialized JSON to string or disk with comprehensive recursive datetime and list handling.
+  - `.to_markdown(columns=None)` — generates GitHub-flavored markdown tables with proper column alignments, pipe escaping, and zero dependencies.
+- **Granular Optional Dependency Extras** — Data export dependencies are strictly optional and modular:
+  - `vlrdevapi[pandas]`: installs `pandas>=2.0.0`
+  - `vlrdevapi[polars]`: installs `polars>=1.0.0`
+  - `vlrdevapi[excel]`: installs `openpyxl>=3.1.0` and `pandas>=2.0.0`
+  - `vlrdevapi[parquet]`: installs `pyarrow>=14.0.0` and `pandas>=2.0.0`
+  - `vlrdevapi[mcp]`: installs `mcp>=1.2.0`
+  - `vlrdevapi[all]`: installs all optional tabular, file, and MCP dependencies.
+  - Missing dependencies provide actionable, friendly install prompts with exact pip commands instead of generic import errors.
+- **First-Class Model Context Protocol (MCP) Server** — Built-in MCP server for AI agents and LLMs (Claude Desktop, Cursor, Zed, Antigravity):
+  - CLI executable `vlrdevapi-mcp` (or `python -m vlrdevapi.mcp.server`, `uvx vlrdevapi-mcp`).
+  - Standard `stdio` transport with structured, formatted tool definitions.
+  - 40 tools covering all endpoints across Matches, Series, Teams, Players, Events, and News.
+  - High-level composite tools for complex agent tasks:
+    - `get_match_full_context(series_id)` — aggregates overview, player statistics, and streams/VODs into a single response.
+    - `get_team_overview(team_id)` — combines team info, roster, upcoming schedule, and tournament placements.
+    - `compare_teams(team_id_1, team_id_2, last_days=60)` — side-by-side comparison of two teams with rosters and recent map statistics/forms.
+    - `get_player_career_summary(player_id)` — consolidated dossier with profile, current teams, agent pool ratings, and tournament placements.
+    - `get_h2h_matchup(team_id_1, team_id_2)` — head-to-head match history between two organizations.
+    - `get_tournament_dossier(event_id)` — tournament overview with participating teams, stages, and standings.
+    - `get_live_and_upcoming_schedule(limit)` — live ticker combined with upcoming match schedule.
+    - `get_news_digest(limit, include_top_article_body)` — latest esports headlines with optional top article body.
+    - `series_map_summary(series_id, game_id)` — targeted map-level overview combining economy, replay timeline, and player stats.
+- **Python 3.15 Ready** — Added Python 3.15 to the CI/CD test and publish workflows, verified across uv python matrix.
+- **Production/Stable Status** — Package status promoted to `Development Status :: 5 - Production/Stable` in package metadata.
+
+### Improved
+
+- **Semantic Model Flattening** — Tabular export extractors (`.to_records()`) now generate clean, non-redundant rows:
+  - Upcoming/completed matches omit static status columns and resolve unannounced teams as `"TBD"`.
+  - Player agent statistics provide unnested, clean numeric columns (`acs`, `kd`, `adr`, `kast`, `kpr`, `apr`).
+  - Series player stats properly segregate map rows, labeling the aggregate map view as `"All Maps"`.
+  - Team rosters separate `primary_role` and multi-role lists.
+- **Unified Serialization in MCP Tools** — MCP server tools now leverage `ExportableModel.to_dict()` and `ExportableModel.to_json()`, eliminating redundant ad-hoc JSON conversion and drastically speeding up tool invocations.
+- **CSV Multi-Value List Formatting** — Agent lists and team roles are formatted with standard semicolon delimiters (`"neon;raze;jett"`) instead of Python `repr()` strings, ensuring full compatibility with spreadsheet applications and analytical parsers.
+- **Parser Corrections** — Fixed swapped KAST and ADR columns in `player.agents()` table extraction to match VLR.gg's actual table headers.
+
+## [3.0.0] - 2026-10-23
+
+### Breaking
+
+- **`BuyType` re-tiered to match vlr.gg** — the economy tab no longer uses
+  its old four spend tiers. `SEMI_ECO` and `SEMI_BUY` are removed and the
+  remaining tiers follow VLR's current categories based on total team
+  spend: `ECO` (under 10k), `HALF_BUY` (10k–18k), and `FULL_BUY` (18k+).
+  A new `PISTOL` member marks pistol-round buys (previously reported as
+  `ECO`). Code switching on `BuyType.SEMI_ECO` / `BuyType.SEMI_BUY` needs
+  updating; string values are `"Pistol"`, `"Eco"`, `"Half-buy"`,
+  `"Full-buy"`.
+
+### Added
+
+- **Buy-type matrix** — `EconomyData` now carries the economy tab's
+  buy-type matrix as `buy_matrix_team1` / `buy_matrix_team2`
+  (`TeamBuyMatrix`): the Pistol / Conv. / Bonus summary and the
+  `On Eco` / `On Half buy` / `On Full buy` records
+  (`BuyTierRecord.vs_eco` / `vs_half` / `vs_full`), each a
+  `won`/`total` `EconScore`. Unplayed matchups are `None`.
+  `series.economy(game_id="all")` on the parser also now returns the
+  all-maps aggregate matrix instead of an empty result.
+- **Convenience accessors** — flat summary shortcuts
+  (`pistol_team1` / `converted_team1` / `bonus_team1` and the
+  `_team2` counterparts), `full_buy` / `half_buy` / `eco` aliases on
+  `TeamBuyMatrix`, and a combined `total` on `BuyTierRecord` for the
+  overall won/total on a tier regardless of the opponent's buy type.
+- **Round economy in `series.rounds`** — `RoundData` now carries the
+  per-round economy from the economy tab: `bank_team1`/`bank_team2`,
+  `spent_team1`/`spent_team2`, `buy_type_team1`/`buy_type_team2`, and
+  `is_pistol_round`. `series.rounds` fetches and merges the economy tab
+  automatically (economy fields stay `None`/empty when that page is
+  unavailable), making it the single round-by-round source alongside
+  `win_type` and the winner's `side`.
+- **Series replay (logs tab)** — new `series.replay(series_id, game_id)`
+  returning the per-round kill-feed timeline (`ReplayData` /
+  `ReplayRound` / `ReplayEvent`): events typed by the `ReplayEventType`
+  enum (`KILL`, `PLANT`, `DEFUSE`, plus derived `BOOM` detonation and
+  `RESURRECT` events with `derived=True`, since vlr.gg logs neither as
+  feed rows), round clocks in both display (`clock`) and numeric
+  (`seconds`) form, kill cause (weapon or ability, e.g. `Sheriff`,
+  `Overdrive`, `Tour de Force`, `Spike`), killer/victim positions with
+  distance in minimap units, spike sites, and per-event alive snapshots
+  (name, agent, team, side, minimap coordinates, facing angle). Each
+  `ReplayRound` also includes `loadouts` (`list[PlayerRoundLoadout]`)
+  and the `loadout_for(player)` helper, capturing every player's
+  equipped weapon at round start, armor (supporting `No armor`,
+  `Light armor`, `Heavy armor`, and `Regen Shield`), and credits
+  left / spent in the buy phase. Real vlr.gg team and player IDs are
+  resolved from the game's overview tab
+  (one extra request, `team1_id`/`team2_id` and `player_id` fields) and
+  matched strictly within each player's team so duplicate names never
+  cross teams; unplayed maps or maps without round data return an
+  empty timeline gracefully.
+- **Series head-to-head history** — `SeriesInfo.head_to_head` exposes
+  previous meetings between the two teams, parsed from the same overview
+  page. Each `SeriesHeadToHeadMatch` includes the series ID/URL, event,
+  stage, date, both team names/scores, and which side won.
+- **Series streams in `series.vods()`** — `SeriesVods.streams` now contains
+  live broadcasts and watch-party streams alongside the existing `vods`
+  list. Each `SeriesStream` exposes the platform, channel, URL, stream
+  type, and country code. `SeriesVod` also gains `platform`, `map_number`,
+  and `start_seconds`.
+- **Player total winnings** — `PlayerInfo.total_winnings` and
+  `total_winnings_currency` now expose the total from the player's Event
+  Placements card.
+- **New `player.placements()` namespace** — returns `PlayerPlacements` with
+  individual `PlayerEventPlacement` rows (event, year, stage, placement,
+  prize, team) and the player's total winnings.
+- **New grand-final fixtures** — series 130685 (LOUD vs OpTic, Champions
+  2022 GF) and 754737 (LOUD vs Vitality, Champions 2026 GF) are now
+  covered by tests across economy, info/pick-bans, players, rounds, and
+  performance parsers.
+
+### Fixed
+
+- **`team.upcoming_matches()` no longer returns completed matches** — the
+  parser now scopes its search to the heading's section wrapper instead of
+  the whole team-summary column, so "Recent Results" is excluded.
+- **`series.info()` on upcoming/live series** — `best_of` is now read from
+  whichever match-header note contains the format (vlr.gg renders the
+  countdown twice before `BoN`), and `TBD` map tabs are no longer marked
+  `played`.
+- **`team.completed_matches()` pagination** — added `limit` (default `50`)
+  and `return_all`; extra pages are fetched only when the requested limit
+  needs them. `TeamCompletedMatches.has_next_page` reports whether more
+  matches exist beyond the returned results.
+- **Team match `stage`/`bracket`** — both fields are now parsed separately
+  from the team matches page (e.g. `stage="Playoffs"`, `bracket="LBF"`),
+  and enrichment no longer concatenates them into `"Playoffs - LBF"`.
+- **Parser whitespace** — shared `normalize_whitespace()` collapses raw tabs,
+  newlines, and repeated spaces in parsed event/stage/bracket/role values
+  instead of leaving values such as `"Playoffs ⋅\n\t\t\tLBF"`.
+- **`events.matches()` team countries** — `MatchTeam` now exposes
+  `country_name`, parsed from the team flag on the event matches page.
+- **Thread-local HTTP client lifecycle** — parallel requests now reuse
+  thread-local clients and close every client after fetching or enrichment,
+  reducing client-creation overhead and preventing resource leaks.
+
+### Changed
+
+- **`RoundData.win_type` is now a `RoundWinType` enum** instead of a
+  human-readable string. Use `round.win_type.full_name` for display text and
+  `round.win_type.value` (`"elimination"`, `"defuse"`, `"spike_detonation"`,
+  `"time_expired"`) for the raw value.
+
+### Documentation
+
+- Series economy reference updated for the new `BuyType` values,
+  buy-matrix fields, and nested models; series rounds reference updated
+  for the merged per-round economy fields; new series replay reference
+  page for the kill-feed timeline module.
+- Updated the `team.completed_matches`, `team.upcoming_matches`,
+  `events.matches`, and `series.rounds` references for `bracket`,
+  `country_name`, and the `RoundWinType` enum.
+- Updated `series.info`, `series.vods`, and `player.info`, and added a
+  `player.placements` reference for head-to-head history, streams, VOD
+  metadata, and event placements.
+
 ## [2.4.1] - 2026-10-17
 
 ### Fixed
@@ -316,6 +485,8 @@ The API surface, module structure, and type system are all new.
 - `aiohttp` and `asyncio` dependencies.
 - v1.x match/event/team parsing modules.
 
+[3.1.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v3.0.0...v3.1.0
+[3.0.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.4.1...v3.0.0
 [2.4.1]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.4.0...v2.4.1
 [2.4.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.3.0...v2.4.0
 [2.3.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.2.0...v2.3.0

{vlrdevapi-2.4.1 → vlrdevapi-3.1.0}/CODE_OF_CONDUCT.md

@@ -15,5 +15,6 @@ diverse, inclusive, and healthy community.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the project maintainers at vanshb@riftwatch.org. All complaints
+reported to the project maintainers via the repository at
+https://github.com/vanshbordia/vlrdevapi. All complaints
 will be reviewed and investigated.