VLRdevAPI

Changelog

Track every release, feature, and fix in VLRdevAPI.

vUnreleased

Uses a sentinel year for events-list dates that omit the year and removes date-parsing deprecation warnings.

Changed

  • `event.list()` dates are rendered on vlr.gg without a year (e.g. "Jul 9 – Aug 23"). These now use a sentinel year of `2019` instead of the current year. Any parsed date with `year < 2020` means the source omitted the year, so guard with `event.start_date.year < 2020` before relying on it.

Fixed

  • `datetime.strptime` emits a `DeprecationWarning` when parsing a day-of-month without a year (and will change behavior in Python 3.15). All such parses now supply an explicit year derived from context (reference date, page-header year, or the sentinel above).
View on GitHubInstall from PyPI
v2.1.0

Adds player rosters to event teams, exposing each player's name and id on every team.

Added

  • `event.teams()` now includes a `players` list on each `Team`, containing each player's `name` and `id` parsed from the event page.
  • New `TeamPlayer` model exposed from the `_event.teams` submodule.
  • The `players` field is always present and defaults to `[]` when roster data is unavailable.

Changed

  • Event teams reference docs updated with the new `players` field, a `TeamPlayer` fields table, and a roster iteration example.
View on GitHubInstall from PyPI
v2.0.1

Maintenance release removing deprecated agent stat fields removed by vlr.gg and updating CSS selectors for the latest site markup.

Removed

  • `fkpr` and `fdpr` fields from `AgentStats` — vlr.gg consolidated the separate "First Kills Per Round" and "First Deaths Per Round" columns into a single "FK:FD" ratio. Use the existing `first_kills` and `first_deaths` total fields instead.
View on GitHubInstall from PyPI
v2.0.0

Initial release of VLRdevAPI. A type-safe Python SDK for Valorant esports data from VLR.gg.

Features

  • Match listings: live matches, upcoming with pagination (`matches.upcoming(page=2, return_all=True)`), completed with date filtering.
  • Team data: info (name, tag, socials), roster with roles/captain/sub status, map stats with agent composition breakdowns, completed and upcoming matches, roster transactions, event placement history with prize winnings.
  • Player profiles: basic info, current and past teams, agent usage stats (`30d`, `60d`, `90d`, `all`), match history with configurable limit, consolidated profile with top agents.
  • Event/tournament coverage: list with tier/region/status filters, info (dates, prize pool, location), stages, teams, matches, standings.
  • Series/match detail: full match overview (teams, scores, map veto, per-game breakdowns), VOD links (YouTube/Twitch), per-player performance stats with ratings, round-by-round data, economy analysis, kill matrices, advanced stats (aces, clutches, multi-kills).

API

  • Synchronous VLRClient with context manager support and curried access pattern (`client.team(4568).roster()`).
  • Module-level convenience access via `import vlrdevapi` with a lazy-initialized default client.
  • Pydantic v2 models with full type hints, field descriptions, and validation across all endpoints.
  • Typed exception hierarchy: VLRdevError, NotFoundError, RequestError, RateLimitError, ParsingError, ValidationError.

Infrastructure

  • Automatic retry logic with configurable strategy (max retries, backoff factor, status codes).
  • Rate limiting with configurable max requests per minute per namespace.
  • LRU response caching with configurable TTL to reduce redundant requests.
  • URL enrichment that automatically resolves team IDs and series info on match listings.
  • Dependency management with uv for fast installs and reproducible builds.
  • Supports Python 3.11 and later.

Documentation

  • Official documentation site at https://vlrdevapi.pages.dev built with Next.js 16 and Fumadocs.
  • API reference covering every namespace, method, parameter, and return type.
  • Practical examples for events, matches, teams, players, and cross-namespace queries.
  • Getting started guide, quickstart tutorial, and development setup guide.
  • Doc validation scripts (check_mdx_examples.py) that verify syntax and live execution of code examples in CI.
  • GitHub Actions workflow for automatic doc validation on pull requests.
  • Comprehensive test suite with fixture-based offline tests and live integration tests.
View on GitHubInstall from PyPI