vlrdevapi 1.6.2__tar.gz → 2.0.0__tar.gz

vlrdevapi-2.0.0/.gitattributes

@@ -0,0 +1,7 @@
+# Exclude documentation from language stats
+official-docs/** linguist-vendored
+docs-py/** linguist-vendored
+
+# Exclude test fixtures
+tests/test_html/** linguist-vendored
+tests/test_html/** linguist-detectable=false

vlrdevapi-2.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,33 @@
+---
+name: Bug Report
+about: Report a problem with vlrdevapi
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Description
+
+A clear description of the bug.
+
+## Reproduction
+
+```python
+import vlrdevapi
+
+# Minimal code to reproduce
+```
+
+## Expected
+
+What you expected to happen.
+
+## Actual
+
+What actually happened (include full traceback).
+
+## Environment
+
+- Python version:
+- vlrdevapi version:
+- OS:

vlrdevapi-2.0.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,19 @@
+---
+name: Feature Request
+about: Suggest an idea for vlrdevapi
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What problem would this feature solve?
+
+## Proposed Solution
+
+How would you like this to work?
+
+## Alternatives
+
+What alternatives have you considered?

vlrdevapi-2.0.0/.github/workflows/docs-check.yml

@@ -0,0 +1,29 @@
+name: Docs Check
+
+on:
+  pull_request:
+    paths:
+      - 'official-docs/**'
+      - 'docs-py/**'
+  push:
+    branches: [main]
+    paths:
+      - 'official-docs/**'
+      - 'docs-py/**'
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+
+        with:
+          python-version: '3.12'
+
+      - name: Install package
+        run: uv sync --group dev
+
+      - name: Run MDX examples check
+        run: uv run scripts/check_mdx_examples.py

vlrdevapi-2.0.0/.github/workflows/publish.yml

@@ -0,0 +1,77 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Download fixtures
+        run: uv run python scripts/download_fixtures.py
+
+      - name: Run tests
+        run: uv run pytest
+
+  release-build:
+    name: Build release distributions
+    runs-on: ubuntu-latest
+    needs:
+      - test
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          python-version: "3.12"
+
+      - name: Build package
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+  pypi-publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs:
+      - release-build
+
+    permissions:
+      id-token: write
+
+    environment:
+      name: pypi
+      url: https://pypi.org/project/vlrdevapi/
+
+    steps:
+      - name: Retrieve release distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

vlrdevapi-2.0.0/.github/workflows/test.yml

@@ -0,0 +1,39 @@
+name: Test
+
+on:
+  pull_request:
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'scripts/download_fixtures.py'
+      - '.github/workflows/test.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'src/**'
+      - 'tests/**'
+      - 'scripts/download_fixtures.py'
+      - '.github/workflows/test.yml'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --group dev
+
+      - name: Download fixtures
+        run: uv run python scripts/download_fixtures.py
+
+      - name: Run tests
+        run: uv run pytest

vlrdevapi-2.0.0/.gitignore

@@ -0,0 +1,31 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+tests/test_html/
+
+nul
+.pytest_cache/
+.ruff_cache
+.kilo
+
+# Sphinx build output
+docs-py/_build/
+
+# Zensical build output
+docs-py/site/
+
+# Debug script
+main.py
+
+# Official docs dependencies
+official-docs/node_modules/
+
+# Zensical cache
+docs-py/.cache/

vlrdevapi-2.0.0/.python-version

@@ -0,0 +1 @@
+3.12

vlrdevapi-2.0.0/.readthedocs.yaml

@@ -0,0 +1,15 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: latest
+  jobs:
+    install:
+      - pip install zensical mkdocstrings mkdocstrings-python
+    build:
+      html:
+        - cd docs-py && zensical build
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp --recursive docs-py/site/* $READTHEDOCS_OUTPUT/html/

vlrdevapi-2.0.0/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+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/).
+
+## [2.0.0] - 2026-07-07
+
+### Major Rewrite
+
+Complete rewrite of the library. v2.0.0 replaces the asynchronous
+aiohttp-based v1.x with a synchronous httpx-based architecture.
+The API surface, module structure, and type system are all new.
+
+### Added
+
+- **Sync-first client** - `VLRClient` with context manager support and
+  thread-safe parallel enrichment for bulk operations.
+- **Curried access pattern** - bind a player/team/series/event ID once,
+  then chain sub-methods without re-passing the ID.
+- **Event namespace** - list with pagination and filtering (tier, region,
+  status), plus info, matches, stages, standings, and teams.
+- **Match listing namespace** - live, upcoming (paginated), and completed
+  (paginated) match feeds with team enrichment.
+- **Player namespace** - info, teams (current/past), agent stats
+  (30d/60d/90d/all), match history (paginated), and consolidated profile.
+- **Series namespace** - info (veto, games, scores), player stats per game,
+  round-by-round data, performance (kill matrices, advanced stats),
+  economy (buy types, spend analysis), and VOD links.
+- **Team namespace** - info, roster, stats (per-map with optional agent
+  composition), placements, transactions, completed and upcoming matches.
+- **Pydantic v2 models** - fully typed with Google-style docstrings and
+  field descriptions.
+- **Built-in resilience** - configurable retry with exponential/linear/
+  constant backoff, jitter, and token-bucket rate limiting.
+- **Thread-safe LRU cache** - bounded `LRUCache` for team data to avoid
+  redundant HTTP requests during enrichment.
+- **Input validation** - `@sanitize_and_validate` decorator with positive-ID
+  checks and Pydantic type coercion.
+- **Custom exceptions** - typed hierarchy (`NotFoundError`, `RateLimitError`,
+  `ParsingError`, `ValidationError`, etc.) for clean error handling.
+- **Documentation** - Zensical/MkDocs site via `docs-py/` (ReadTheDocs)
+  with auto-generated API reference from docstrings.
+- **Official website** - Next.js + Fumadocs site via `official-docs/`
+  (Cloudflare Pages) with interactive code examples.
+- **Doc validation** - `scripts/check_mdx_examples.py` validates syntax,
+  imports, and live execution of all code examples in docs.
+
+### Changed
+
+- **Architecture** - migrated from async aiohttp to synchronous httpx.
+  No more `await` or `async with` required.
+- **No explicit session management** - `VLRClient` handles connection
+  pooling, retries, and rate limiting internally.
+- **Type system** - replaced raw dict returns with Pydantic v2 models
+  for all endpoints.
+- **Build system** - moved from setuptools to hatchling with `uv` for
+  dependency management.
+- **Python requirement** - raised minimum to 3.11.
+
+### Removed
+
+- All v1.x async endpoints (`get_event`, `get_team`, `get_player`, etc.)
+  are removed. See the new module-level or client-based API.
+- `aiohttp` and `asyncio` dependencies.
+- v1.x match/event/team parsing modules.
+
+[2.0.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v1.6.2...v2.0.0

vlrdevapi-2.0.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,19 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+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
+will be reviewed and investigated.

vlrdevapi-2.0.0/CONTRIBUTING.md

@@ -0,0 +1,41 @@
+# Contributing to vlrdevapi
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+1. Clone the repo: `git clone https://github.com/Vanshbordia/vlrdevapi`
+2. Install dependencies: `uv sync --group dev`
+3. Run pre-checks: `ruff check src/` and `ty check src/vlrdevapi/`
+
+## Pull Request Guidelines
+
+- Keep PRs focused on a single concern.
+- Add or update tests for any changed behavior.
+- Run `ruff check src/ tests/` and `ty check src/vlrdevapi/` before pushing.
+- Update the CHANGELOG.md under the next version header.
+- If changing documentation (.mdx files), run `uv run scripts/check_mdx_examples.py` and ensure all checks pass.
+
+## Code Style
+
+- Follow PEP 8 with `ruff` defaults (120-char lines, double quotes).
+- Use Google-style docstrings on all public methods.
+- Annotate all function signatures with type hints.
+- Use `Literal` over `Union[Literal, str]` — validation is handled at runtime.
+
+## Project Structure
+
+```
+src/vlrdevapi/
+  _base.py          # SyncNamespace base class
+  _cache.py         # LRUCache
+  client.py         # VLRClient
+  commons/          # Shared utilities (mappings, datetime, countries)
+  event/            # Event/tournament endpoints
+  matches/          # Match listing endpoints (live / upcoming / completed)
+  player/           # Player endpoints (info / teams / agents / matches / profile)
+  series/           # Series (match detail) endpoints
+  team/             # Team endpoints (info / roster / placements / etc.)
+  validators.py     # Input sanitization / validation
+  fetcher.py        # HTTP fetching with retries and rate limiting
+```

vlrdevapi-1.6.2/LICENSE → vlrdevapi-2.0.0/LICENCE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Vansh Bordia
+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
@@ -18,4 +18,4 @@ 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.
+SOFTWARE.

vlrdevapi-2.0.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: vlrdevapi
+Version: 2.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
+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.12.5
+Requires-Dist: selectolax>=0.4.7
+Provides-Extra: test
+Requires-Dist: pytest-cov>=7.1.0; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Requires-Dist: respx>=0.23.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="official-docs/public/logo.svg" width="120" alt="vlrdevapi logo">
+
+# vlrdevapi
+
+**Python library for VLR.gg Valorant esports data**
+
+[![Python Version](https://img.shields.io/pypi/pyversions/vlrdevapi.svg)](https://pypi.org/project/vlrdevapi/)
+[![PyPI](https://img.shields.io/pypi/v/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://vlrdevapi.pages.dev/docs) · [ReadTheDocs](https://vlrdevapi.readthedocs.io/) · [PyPI](https://pypi.org/project/vlrdevapi/) · [GitHub](https://github.com/Vanshbordia/vlrdevapi)
+
+</div>
+
+---
+
+Access Valorant esports data from VLR.gg with a clean, type-safe Python API. Get tournament info, match schedules, player stats, team data, and series/match-level details.
+
+## Features
+
+- **Complete Data Access** - Events, matches, players, teams, and series
+- **Type-Safe** - Pydantic models with rich type hints and field descriptions
+- **Production-Ready** - Retry logic, rate limiting, and LRU-cached enrichment
+- **Curried Access** - Bind a player/team/series ID once, then call sub-methods without re-passing
+- **Managed with [uv](https://docs.astral.sh/uv/)** - Fast dependency resolution and virtual environment management
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add vlrdevapi
+
+# Using pip
+pip install vlrdevapi
+```
+
+Requires Python 3.11+
+
+## Quick Start
+
+### Module-level (no client needed)
+
+```python
+import vlrdevapi
+
+# Single-shot fetches via module-level access
+info = vlrdevapi.player.info(player_id=11225)
+print(f"{info.name} - {info.country}")
+
+series = vlrdevapi.series.info(series_id=542272)
+print(f"{series.team1.name} vs {series.team2.name}")
+
+event = vlrdevapi.event.info(event_id=2863)
+print(f"{event.name} - {event.subtitle}")
+```
+
+### Sync client
+
+```python
+from vlrdevapi import VLRClient
+
+with VLRClient() as client:
+    # Curried access - bind a player once
+    player = client.player(11225)
+    print(player.info().name)
+    print(player.teams().current_teams)
+    print(player.agents(timespan="all").agents[:3])
+
+    # Team data
+    team = client.team(1034)
+    roster = team.roster()
+    placements = team.placements()
+
+    # Event data
+    event = client.event(2863)
+    stages = event.stages()
+    matches = event.matches()
+```
+
+## API Modules
+
+### Matches
+
+```python
+matches = client.matches.upcoming(page=1)
+live = client.matches.live()
+completed = client.matches.completed(page=1)
+```
+
+### Players
+
+```python
+p = client.player(11225)
+info = p.info()                           # Basic info
+teams = p.teams()                         # Current / past teams
+agents = p.agents(timespan="60d")         # Agent stats
+matches = p.matches(limit=20)             # Match history
+profile = p.profile()                     # Consolidated profile
+```
+
+### Teams
+
+```python
+t = client.team(1034)
+info = t.info()                           # Name, tag, socials
+roster = t.roster()                       # Players + staff
+placements = t.placements()               # Event placements + winnings
+transactions = t.transactions()            # Join / leave history
+completed = t.completed_matches()          # Completed match results
+upcoming = t.upcoming_matches()            # Upcoming match schedule
+```
+
+### Events
+
+```python
+e = client.event(2863)
+info = e.info()                          # Event details
+matches = e.matches()                    # Match list
+standings = e.standings()                # Standings / prize distribution
+```
+
+### Series
+
+```python
+s = client.series(542272)
+info = s.info()                          # Series overview
+vods = s.vods()                          # VOD links
+players = s.players(game_id=1)           # Per-game player stats
+rounds = s.rounds(game_id=1)             # Round-by-round data
+performance = s.performance()            # Advanced performance stats
+economy = s.economy(game_id=1)           # Economy data
+```
+
+## Documentation
+
+- **Official Docs** - [vlrdevapi.pages.dev/docs](https://vlrdevapi.pages.dev/docs)
+- **ReadTheDocs** - [vlrdevapi.readthedocs.io](https://vlrdevapi.readthedocs.io/)
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+# Clone and set up
+git clone https://github.com/Vanshbordia/vlrdevapi
+cd vlrdevapi
+uv sync --group dev
+
+# Lint & type check
+ruff check src/ tests/
+ty check src/vlrdevapi/
+
+# Run tests
+uv run pytest tests/ -v
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution guide.
+
+## License
+
+MIT License - see the [LICENCE](LICENCE) file.
+
+---
+
+**Disclaimer:** Not affiliated with VLR.gg or Riot Games. Use responsibly.