vlrdevapi 2.4.0__tar.gz → 3.0.0__tar.gz

{vlrdevapi-2.4.0 → vlrdevapi-3.0.0}/.github/workflows/docs-check.yml

@@ -24,36 +24,26 @@ jobs:
       - name: Install package
         run: uv sync --group dev
 
-      # 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-3.0.0/.nvmrc

@@ -0,0 +1 @@
+26.10.0

{vlrdevapi-2.4.0 → vlrdevapi-3.0.0}/.readthedocs.yaml

@@ -6,10 +6,11 @@ build:
     python: latest
   jobs:
     install:
-      - pip install zensical mkdocstrings mkdocstrings-python
+      - pip install uv
+      - uv sync --group dev
     build:
       html:
-        - cd docs-py && zensical build
+        - cd docs-py && uv run zensical build
     post_build:
       - mkdir -p $READTHEDOCS_OUTPUT/html/
       - cp --recursive docs-py/site/* $READTHEDOCS_OUTPUT/html/

{vlrdevapi-2.4.0 → vlrdevapi-3.0.0}/CHANGELOG.md

@@ -5,6 +5,163 @@ 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.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
+
+- **Series players/stats parsing** — newer vlr.gg overview tables add a
+  dedicated `.mod-agents` cell before the stat columns. Stat cells are now
+  mapped dynamically around that column, and agents are read from the new
+  cell. This fixes `SideStats` validation errors and misaligned values
+  (rating, ACS, KDA, KAST, ADR, HS%, first kills/deaths).
+- **Series economy parsing** — the round-by-round economy grid now uses the
+  newer `.vlr-rounds.ecr` markup (`.ecr-bank`, `.ecc-c`, `.ecc-sq`). Banks,
+  spends, buy types, and round winners are read from it, with the legacy
+  `.wf-table-inset.mod-econ` table kept as a fallback.
+- **Series VODs parsing** — VODs are now read from the newer `.sm-vods`
+  module (`.sm-vod-name` labels, `a.sm-ext` links), keeping the legacy
+  `.match-vods` container as a fallback.
+- **Series game map names** — the game header now renders the duration as a
+  sibling of the map name. The map name is read from `.map-name`, so the
+  duration is no longer concatenated (e.g. `Pearl` instead of `Pearl35:48`).
+
+### Changed
+
+- **Series economy team matching** — team/abbreviation resolution is now
+  case-insensitive, so team IDs resolve for pages that render short tags.
+- **HTML parsing backend** — parsing now uses selectolax's Lexbor engine
+  (`selectolax.lexbor`) instead of the discontinued Modest engine
+  (`selectolax.parser`), which selectolax removed in 1.0. This is an internal
+  change: the public API, CSS selectors, and parsed output are unchanged.
+- **Dependencies** — raised the `selectolax` minimum to `>=1.0.0` and moved
+  `pydantic` to the 2.14 series.
+
+### Documentation
+
+- **Changelog** — this release is mirrored across `CHANGELOG.md`, the
+  ReadTheDocs changelog (`docs-py/docs/changelog.md`), and the official
+  site changelog (`official-docs/app/(home)/changelog/page.tsx`).
+
 ## [2.4.0] - 2026-08-19
 
 ### Added
@@ -279,6 +436,8 @@ The API surface, module structure, and type system are all new.
 - `aiohttp` and `asyncio` dependencies.
 - v1.x match/event/team parsing modules.
 
+[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
 [2.2.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.1.0...v2.2.0

{vlrdevapi-2.4.0 → vlrdevapi-3.0.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.

vlrdevapi-3.0.0/PKG-INFO

@@ -0,0 +1,394 @@
+Metadata-Version: 2.5
+Name: vlrdevapi
+Version: 3.0.0
+Summary: A Python library to scrape data from vlr.gg
+Project-URL: Homepage, https://vlrdevapi.pages.dev/
+Project-URL: Repository, https://github.com/Vanshbordia/vlrdevapi
+Project-URL: Documentation, https://vlrdevapi.pages.dev/docs/
+License: MIT License
+        
+        Copyright (c) 2026 Vansh Bordia
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENCE
+Keywords: api,esports,python,scraper,sdk,valorant,valorant esports,vct,vlr.gg,vlrgg
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.14.1
+Requires-Dist: selectolax>=1.0.0
+Provides-Extra: test
+Requires-Dist: pytest-cov>=7.1.0; extra == 'test'
+Requires-Dist: pytest>=9.1.1; extra == 'test'
+Requires-Dist: respx>=0.23.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="official-docs/public/logo.png" width="120" alt="vlrdevapi logo">
+
+# vlrdevapi
+
+**The modern, type-safe Python library for VLR.gg Valorant esports data**
+
+[![PyPI version](https://img.shields.io/pypi/v/vlrdevapi.svg?color=fd4556)](https://pypi.org/project/vlrdevapi/)
+[![Python Version](https://img.shields.io/pypi/pyversions/vlrdevapi.svg)](https://pypi.org/project/vlrdevapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Documentation](https://img.shields.io/badge/docs-vlrdevapi.pages.dev-blue.svg)](https://vlrdevapi.pages.dev/docs/)
+
+[Documentation](https://vlrdevapi.pages.dev/docs/) · [Quickstart](https://vlrdevapi.pages.dev/docs/quickstart/) · [API Reference](https://vlrdevapi.pages.dev/docs/reference/) · [Guides](https://vlrdevapi.pages.dev/guides/) · [Changelog](https://vlrdevapi.pages.dev/changelog/) · [PyPI](https://pypi.org/project/vlrdevapi/)
+
+</div>
+
+---
+
+**vlrdevapi** is a high-performance, type-safe Python client for extracting and analyzing Valorant esports data from [VLR.gg](https://www.vlr.gg/). Built for competitive analysts, data scientists, Discord bot creators, and esports engineers, it delivers structured [Pydantic](https://docs.pydantic.dev/) models with full type hinting, built-in rate limiting, automatic retries, and comprehensive coverage across all VLR.gg entities.
+
+Whether you need live match tickers, tournament brackets, historical player ratings, round-by-round economy buy matrices, or 2D minimap kill-feed replay timelines with player loadouts, **vlrdevapi** provides a clean, idiomatic interface.
+
+---
+
+## Highlights
+
+- **Complete Valorant Esports Coverage** — Tournaments, match schedules, live scoreboards, player careers, team rosters, roster transactions, and esports news.
+- **2D Kill-Feed Replay Timelines** — Spatial `(x, y)` kill coordinates, viewing angles, kill distances, plant/defuse events, spike detonations (`boom`), resurrections, alive player snapshots, and buy-phase **player loadouts** (weapons, shields, spent credits, remaining bank).
+- **Round-by-Round Economy** — Full team buy matrices (`loadout_value`, `spent`, `bank`, buy classifications like `Eco`, `Anti-eco`, `Semi-buy`, `Semi-rifle`, and `Full buy`).
+- **Strictly Typed Pydantic Models** — Every endpoint returns validated models with full field annotations, descriptive docstrings, and IDE autocompletion.
+- **Production-Ready Reliability** — Built-in token-bucket rate limiter, exponential backoff retries, thread-safe connection pooling, and LRU-cached enrichment.
+- **Flexible Access Patterns** — Use lightweight module-level calls (`vlrdevapi.player.info(...)`), curried ID chaining (`vlrdevapi.player(11225).info()`), or a managed context manager (`with VLRClient() as client:`).
+- **Timezone Awareness** — Seamlessly convert match schedules and timestamps into any target timezone via Python's standard `zoneinfo`.
+- **Managed with [uv](https://docs.astral.sh/uv/)** — Blazing fast dependency resolution and testing workflows.
+
+---
+
+## Installation
+
+Install `vlrdevapi` using [uv](https://docs.astral.sh/uv/) (recommended) or `pip`:
+
+```bash
+# Using uv (recommended)
+uv add vlrdevapi
+
+# Using pip
+pip install vlrdevapi
+```
+
+> **Requirements:** Python 3.11 or higher.
+
+---
+
+## Quickstart
+
+### 1. Direct Module-Level Access (Zero Setup)
+
+Fetch data immediately without instantiating a client:
+
+```python
+import vlrdevapi
+
+# Get player profile and country
+player = vlrdevapi.player.info(player_id=11225)
+print(f"Player: {player.name} ({player.country})")
+
+# Get series overview
+series = vlrdevapi.series.info(series_id=542272)
+print(f"Match: {series.team1.name} vs {series.team2.name} - Score: {series.score1}:{series.score2}")
+
+# Get event details
+event = vlrdevapi.event.info(event_id=2863)
+print(f"Event: {event.name} ({event.start_date} to {event.end_date})")
+```
+
+### 2. Curried Method Chaining
+
+Bind an ID once, then query multiple sub-methods without repeating the identifier:
+
+```python
+import vlrdevapi
+
+# Bind team 2593 (FNATIC) once
+fnc = vlrdevapi.team(2593)
+
+info = fnc.info()
+print(f"{info.name} [{info.tag}] - Country: {info.country}")
+
+roster = fnc.roster()
+print(f"Active Players: {[p.ign for p in roster.players]}")
+
+placements = fnc.placements()
+print(f"Total Prize Earnings: {placements.total_winnings_currency}{placements.total_winnings:,}")
+```
+
+### 3. Managed Client Session (`VLRClient`)
+
+For production applications, high-throughput scripts, or custom concurrency tuning, use `VLRClient`:
+
+```python
+from vlrdevapi import VLRClient
+
+with VLRClient(timeout=30, requests_per_second=8, max_retries=3) as client:
+    # Live matches ticker
+    live_matches = client.matches.live()
+    for m in live_matches.matches:
+        print(f"LIVE: {m.team1.name} vs {m.team2.name} ({m.event})")
+
+    # Series performance & economy
+    series = client.series(542272)
+    econ = series.economy(game_id=1)
+    print(f"Map 1 Rounds Analyzed: {len(econ.rounds)}")
+```
+
+---
+
+## API Overview & Reference
+
+| Module | Key Methods | Description | Official Docs |
+|:---|:---|:---|:---|
+| **[Matches](https://vlrdevapi.pages.dev/docs/reference/matches/)** | `upcoming()`, `live()`, `completed()` | Live scores, upcoming schedules, and paginated match history | [Docs →](https://vlrdevapi.pages.dev/docs/reference/matches/) |
+| **[Series](https://vlrdevapi.pages.dev/docs/reference/series/)** | `info()`, `replay()`, `economy()`, `players()`, `rounds()`, `vods()`, `performance()` | Deep map analytics, kill-feed timeline, buy matrices, player stats, and streams | [Docs →](https://vlrdevapi.pages.dev/docs/reference/series/) |
+| **[Players](https://vlrdevapi.pages.dev/docs/reference/player/)** | `info()`, `profile()`, `agents()`, `teams()`, `matches()`, `placements()` | Historical ratings (ACS, K/D, ADR, KAST), agent pools, career history, and placements | [Docs →](https://vlrdevapi.pages.dev/docs/reference/player/) |
+| **[Teams](https://vlrdevapi.pages.dev/docs/reference/team/)** | `info()`, `roster()`, `placements()`, `transactions()`, `completed_matches()`, `upcoming_matches()` | Active rosters, staff, roster transfers, historical match records, and tournament earnings | [Docs →](https://vlrdevapi.pages.dev/docs/reference/team/) |
+| **[Events](https://vlrdevapi.pages.dev/docs/reference/events/)** | `info()`, `stages()`, `matches()`, `standings()`, `teams()`, `list()` | Tournament brackets, group/playoff stages, standings, prize pools, and participating teams | [Docs →](https://vlrdevapi.pages.dev/docs/reference/events/) |
+| **[News](https://vlrdevapi.pages.dev/docs/reference/news/)** | `list()`, `article()` | VLR.gg editorial articles, breaking roster news, author details, and full Markdown content | [Docs →](https://vlrdevapi.pages.dev/docs/reference/news/) |
+
+---
+
+## Code Examples
+
+### 1. Spatial Replay Timeline & Round Loadouts
+
+Inspect round-by-round kill events with 2D minimap locations, viewing angles, distances, and player equipment:
+
+```python
+import vlrdevapi
+
+# Fetch replay timeline for Game 3 of a series (Sunset)
+replay = vlrdevapi.series.replay(series_id=754737, game_id=283288)
+round_1 = replay.round(1)
+
+if round_1:
+    print(f"Round 1 Attacking Side: {round_1.attacking}")
+
+    # Check buy-phase loadout for a player
+    loadout = round_1.loadout_for("Derke")
+    if loadout:
+        print(f"Derke: Weapon={loadout.weapon}, Armor={loadout.armor}, Spent=${loadout.spent}")
+
+    # Iterate through kill events
+    for event in round_1.events:
+        if event.type.value == "kill":
+            killer = event.actor.name if event.actor else "World"
+            victim = event.victim.name if event.victim else "Unknown"
+            dist = f"{event.distance_units:.1f}u" if event.distance_units else "N/A"
+            print(f"  [{event.clock}] {killer} killed {victim} with {event.cause} (dist: {dist})")
+            if event.pos_x is not None:
+                print(f"    Victim pos: ({event.pos_x}, {event.pos_y}) | Killer pos: ({event.from_x}, {event.from_y})")
+```
+
+Learn more in the [Series Replay Documentation](https://vlrdevapi.pages.dev/docs/reference/series/replay/).
+
+---
+
+### 2. Round Economy & Team Buy Matrices
+
+Analyze team spending, bank reserves, and buy types across rounds:
+
+```python
+import vlrdevapi
+
+economy = vlrdevapi.series.economy(series_id=754737, game_id=283288)
+
+for r in economy.rounds[:5]:
+    winner_name = r.winner.name if r.winner else "Unknown"
+    print(f"Round {r.round_number}: Winner = {winner_name}")
+    print(f"  {economy.team1}: {r.buy_type_team1} (Spent: ${r.spent_team1:,}, Bank: ${r.bank_team1:,})")
+    print(f"  {economy.team2}: {r.buy_type_team2} (Spent: ${r.spent_team2:,}, Bank: ${r.bank_team2:,})")
+```
+
+Learn more in the [Series Economy Documentation](https://vlrdevapi.pages.dev/docs/reference/series/economy/).
+
+---
+
+### 3. Player Career Statistics & Agent Pools
+
+Extract ACS, K/D, KAST, and ADR broken down by agent:
+
+```python
+import vlrdevapi
+
+# Query player agent stats over the last 60 days
+agent_stats = vlrdevapi.player.agents(player_id=11225, timespan="60d")
+
+for a in agent_stats.agents[:4]:
+    print(f"{a.agent:<10} | Pick Rate: {a.use} | Rating: {a.rating} | ACS: {a.acs} | K/D: {a.kd}")
+```
+
+Learn more in the [Player Reference Documentation](https://vlrdevapi.pages.dev/docs/reference/player/).
+
+---
+
+### 4. Tournament Brackets & Standings
+
+Fetch event stages, match schedules, and final prize distributions:
+
+```python
+import vlrdevapi
+
+event_id = 2863  # e.g., Champions 2026
+event = vlrdevapi.event(event_id)
+
+# Event stages (Group Stage, Playoffs, etc.)
+for stage in event.stages():
+    print(f"Stage: {stage.name} (ID: {stage.id})")
+
+# Final event standings & prize earnings
+standings = event.standings()
+for stage in standings.stages[:1]:
+    print(f"--- {stage.stage_name} ---")
+    for row in stage.standings[:3]:
+        team_name = row.team.name if row.team else "TBD"
+        prize = f"{row.prize_currency}{row.prize_money:,}" if row.prize_money else "N/A"
+        print(f"  #{row.place}: {team_name} - Prize: {prize}")
+```
+
+Learn more in the [Events Reference Documentation](https://vlrdevapi.pages.dev/docs/reference/events/).
+
+---
+
+### 5. News Articles with Full Markdown
+
+Read VLR.gg editorial content formatted in clean GitHub-flavored Markdown:
+
+```python
+import vlrdevapi
+
+# Get latest articles
+feed = vlrdevapi.news(page=1)
+latest = feed.news[0]
+
+# Retrieve full article body
+article = vlrdevapi.news.article(latest.id)
+print(f"Title:  {article.title}")
+print(f"Author: {article.author} ({article.date})")
+print(f"Length: {len(article.content_md):,} characters")
+```
+
+Learn more in the [News Reference Documentation](https://vlrdevapi.pages.dev/docs/reference/news/).
+
+---
+
+## Configuration & Error Handling
+
+### Rate Limiting & Concurrency
+
+`vlrdevapi` includes sensible defaults (`4.0` requests per second) to respect VLR.gg servers. When using `VLRClient`, you can customize client settings:
+
+```python
+from zoneinfo import ZoneInfo
+from vlrdevapi import VLRClient
+
+client = VLRClient(
+    timeout=20,                     # Timeout per request (seconds)
+    requests_per_second=6,          # Max rate limit
+    max_retries=4,                  # Exponential backoff retries
+    source_tz=ZoneInfo("America/New_York"),  # Target timezone for schedules
+)
+```
+
+### Typed Exceptions
+
+Catch errors with specific, typed exception classes from `vlrdevapi.exceptions`:
+
+```python
+import vlrdevapi
+from vlrdevapi.exceptions import (
+    NotFoundError,
+    RateLimitError,
+    RequestError,
+    ValidationError,
+)
+
+try:
+    player = vlrdevapi.player.info(player_id=99999999)
+except NotFoundError:
+    print("Player not found on VLR.gg (404).")
+except RateLimitError:
+    print("Exceeded VLR.gg rate limits. Please slow down requests.")
+except ValidationError as e:
+    print(f"Invalid parameter passed: {e}")
+except RequestError as e:
+    print(f"Network error occurred: {e}")
+```
+
+---
+
+## Documentation & Guides
+
+Comprehensive documentation, tutorials, and deep-dives are available on the official documentation portal:
+
+- **[Documentation Home](https://vlrdevapi.pages.dev/docs/)** — Complete getting-started guide and architectural overview.
+- **[Quickstart Guide](https://vlrdevapi.pages.dev/docs/quickstart/)** — First queries in under two minutes.
+- **[Series Replay Guide](https://vlrdevapi.pages.dev/docs/reference/series/replay/)** — Mapping 2D replay coordinates, viewing angles, and equipment.
+- **[Series Economy Guide](https://vlrdevapi.pages.dev/docs/reference/series/economy/)** — Round spending and buy matrix mechanics.
+- **[Guides & Tutorials](https://vlrdevapi.pages.dev/guides/)** — Real-world guides for Discord bots, Pandas analysis, and Polars pipelines.
+- **[Frequently Asked Questions](https://vlrdevapi.pages.dev/faq/)** — Common questions on rate limits, IDs, and data structures.
+- **[Changelog](https://vlrdevapi.pages.dev/changelog/)** — Version history and release notes.
+
+---
+
+## Development
+
+Contributions and bug reports are welcome! This repository uses `uv` for package management and testing:
+
+```bash
+# 1. Clone the repository
+git clone https://github.com/Vanshbordia/vlrdevapi.git
+cd vlrdevapi
+
+# 2. Install dependencies with uv
+uv sync --group dev
+
+# 3. Run the unit test suite
+uv run pytest tests/ -v
+
+# 4. Run static type checking and linter
+uv run ruff check src/ tests/
+```
+
+Please read our [Contributing Guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) before submitting pull requests.
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENCE).
+
+---
+
+## Disclaimer
+
+`vlrdevapi` is an independent open-source library. It is not affiliated with, maintained, authorized, or endorsed by [VLR.gg](https://www.vlr.gg/) or [Riot Games](https://www.riotgames.com/). Valorant and all associated properties are trademarks or registered trademarks of Riot Games, Inc. Please use responsibly and respect VLR.gg's bandwidth and server infrastructure.