Metadata-Version: 2.4
Name: vlrdevapi
Version: 1.0.0
Summary: The comprehensive Python library for VLR.gg Valorant esports data scraping - tournaments, matches, players, and statistics
Author: Vansh
License: MIT License
        
        Copyright (c) 2025 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.
        
Project-URL: Homepage, https://github.com/vanshbordia/vlrdevapi
Project-URL: Documentation, https://vlrdevapi.readthedocs.io
Project-URL: Source, https://github.com/vanshbordia/vlrdevapi
Project-URL: Issues, https://github.com/vanshbordia/vlrdevapi/issues
Keywords: valorant,esports,vlr,vlr.gg,scraper,api,gaming,competitive,tournament,statistics,data,vct,web-scraping
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: lxml>=5.0
Requires-Dist: pydantic>=2.0
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Dynamic: license-file

# vlrdevapi

**The Python library for VLR.gg Valorant esports data scraping and API access.**

vlrdevapi is a comprehensive, type-safe Python client library designed specifically for scraping and accessing Valorant esports data from VLR.gg. As there is no official VLR.gg API, this library provides a standardized, reliable, and efficient way to programmatically access tournament information, match data, player statistics, and more.

## Why vlrdevapi?

vlrdevapi is the fastest and most complete solution for Valorant esports data extraction:

- **Comprehensive Coverage**: Events, matches, players, series, teams, and statistics
- **Type-Safe**: Full Pydantic models with automatic validation
- **Production-Ready**: Built-in retry logic, error handling, and rate limit protection
- **Developer-Friendly**: Intuitive API design with extensive documentation
- **Well-Maintained**: Active development with regular updates
- **Open Source**: MIT licensed, community-driven development

## Key Features

### Data Access

| Feature | Description |
|---------|-------------|
| **Events API** | List, filter, and access tournament/event data including schedules, prize pools, and standings |
| **Matches API** | Get upcoming, live, and completed match information with real-time scores |
| **Players API** | Access player profiles, statistics, match history, and agent performance data |
| **Series API** | Detailed match analytics including map picks/bans, player stats, and round results |

### Technical Features

- **Type Safety**: Complete Pydantic model coverage with automatic validation
- **Error Handling**: Built-in retry logic with exponential backoff
- **Rate Limiting**: Automatic rate limit detection and handling
- **Caching**: Intelligent response caching to reduce API calls
- **Fast Parsing**: lxml-based HTML parsing for optimal performance
- **Connection Pooling**: Persistent HTTP connections for reduced latency

## Installation

Requires Python 3.11 or higher.

```bash
pip install vlrdevapi
```

### Development Installation

```bash
git clone https://github.com/vanshbordia/vlrdevapi.git
cd vlrdevapi
pip install -e .[dev]
```

## Quick Start

```python
import vlrdevapi as vlr

# List VCT events
events = vlr.events.list_events(tier="vct", status="ongoing")
for event in events:
    print(f"{event.name} - {event.status}")

# Get upcoming matches
matches = vlr.matches.upcoming(limit=5)
for match in matches:
    print(f"{match.teams[0]} vs {match.teams[1]} - {match.event}")

# Player profile and stats
profile = vlr.players.profile(player_id=4164)
print(f"{profile.handle} ({profile.real_name}) - {profile.country}")

agent_stats = vlr.players.agent_stats(player_id=4164, timespan="60d")
for stat in agent_stats:
    print(f"{stat.agent}: {stat.rating} rating, {stat.acs} ACS")

# Series information
info = vlr.series.info(match_id=530935)
print(f"{info.teams[0].name} vs {info.teams[1].name}")
print(f"Score: {info.score[0]}-{info.score[1]}")
```

## Complete API Reference

### Events Module - Tournament and Competition Data

```python
import vlrdevapi as vlr

# List events with filters
events = vlr.events.list_events(
    tier="vct",           # "all", "vct", "vcl", "t3", "gc", "cg", "offseason"
    region="na",          # Optional region filter
    status="ongoing",     # "all", "upcoming", "ongoing", "completed"
    page=1
)

# Get event details
info = vlr.events.info(event_id=2498)

# Get event matches
matches = vlr.events.matches(event_id=2498)

# Get event standings
standings = vlr.events.standings(event_id=2498)
```

### Matches Module - Match Schedules and Results

```python
import vlrdevapi as vlr

# Upcoming matches
upcoming = vlr.matches.upcoming(limit=10)

# Live matches
live = vlr.matches.live()

# Completed matches
completed = vlr.matches.completed(limit=10, page=1)
```

### Players Module - Player Information and Statistics

```python
import vlrdevapi as vlr

# Player profile
profile = vlr.players.profile(player_id=4164)

# Player match history
matches = vlr.players.matches(player_id=4164, limit=20)

# Agent statistics
stats = vlr.players.agent_stats(
    player_id=4164,
    timespan="60d"  # "30d", "60d", "90d", "all"
)
```

### Series Module - Detailed Match Analytics

```python
import vlrdevapi as vlr

# Series/match information
info = vlr.series.info(match_id=530935)

# Detailed map statistics
maps = vlr.series.matches(series_id=530935)
for map_data in maps:
    print(f"Map: {map_data.map_name}")
    for player in map_data.players:
        print(f"  {player.name}: {player.k}/{player.d}/{player.a}")
```

## Data Models and Type Safety

All API responses are returned as immutable Pydantic models with complete type hints:

| Model | Purpose | Key Fields |
|-------|---------|------------|
| `ListEvent` | Event list entries | id, name, status, dates, prize |
| `Info` | Detailed event data | name, prize, location, regions |
| `Match` | Match information | teams, score, event, status |
| `Profile` | Player profiles | handle, real_name, country, teams |
| `AgentStats` | Agent performance | agent, rating, acs, kd, kast |
| `MapPlayers` | Map statistics | map_name, players, teams, rounds |

### Model Features

- **Immutable**: All models are frozen after creation
- **Validated**: Automatic data validation using Pydantic
- **Serializable**: Easy conversion to dict/JSON
- **Type-Hinted**: Full IDE autocomplete support

```python
# Access model fields
profile = vlr.players.profile(player_id=4164)
print(profile.handle)  # IDE autocomplete works

# Convert to dictionary
data = profile.model_dump()

# Serialize to JSON
json_str = profile.model_dump_json()
```

## Use Cases

vlrdevapi is perfect for:

- **Data Analysis**: Build analytics dashboards and statistics trackers
- **Betting Tools**: Create prediction models and odds calculators  
- **Tournament Tracking**: Monitor ongoing events and match results
- **Player Scouting**: Analyze player performance across agents and maps
- **Content Creation**: Generate automated match reports and summaries
- **Discord Bots**: Real-time match notifications and statistics
- **Research**: Academic studies on esports performance and trends

## Advanced Usage

### Pagination

Many functions support pagination for large datasets:

```python
import vlrdevapi as vlr

# Get specific page
events = vlr.events.list_events(tier="vct", page=2)

# Limit results
matches = vlr.matches.upcoming(limit=20)

# Combine pagination with limits
results = vlr.matches.completed(limit=50, page=1)
```

### Filtering

Filter data by multiple criteria:

```python
# Filter events by tier and status
vct_events = vlr.events.list_events(
    tier="vct",
    region="na",
    status="ongoing"
)

# Filter player stats by timespan
recent_stats = vlr.players.agent_stats(
    player_id=4164,
    timespan="30d"  # Options: "30d", "60d", "90d", "all"
)
```

### Cache Management

```python
import vlrdevapi as vlr

# Clear cache for fresh data
vlr.fetcher.clear_cache()

# Close connections on shutdown
vlr.fetcher.close_connections()
```

## Error Handling

The library raises specific exceptions for different error cases:

```python
from vlrdevapi.exceptions import NetworkError, RateLimitError

try:
    events = vlr.events.list_events()
except RateLimitError:
    print("Rate limited by VLR.gg")
except NetworkError as e:
    print(f"Network error: {e}")
```

## Testing

The library includes comprehensive tests with real HTML fixtures:

```bash
# Run all tests
pytest tests/lib/

# Run with coverage
pytest tests/lib/ --cov=vlrdevapi

# Run specific test module
pytest tests/lib/test_events.py -v
```

## Documentation and Resources

### Official Documentation

- **[Complete API Reference](https://vlrdevapi.readthedocs.io/)** - Full function and model documentation
- **[Usage Examples](https://vlrdevapi.readthedocs.io/en/latest/examples.html)** - Practical code examples
- **[Data Models](https://vlrdevapi.readthedocs.io/en/latest/models.html)** - Model schemas and validation
- **[Installation Guide](https://vlrdevapi.readthedocs.io/en/latest/installation.html)** - Setup and troubleshooting

### Community and Support

- **GitHub**: [github.com/vanshbordia/vlrdevapi](https://github.com/vanshbordia/vlrdevapi)
- **Issues**: [Report bugs or request features](https://github.com/vanshbordia/vlrdevapi/issues)
- **Discussions**: [Community Q&A](https://github.com/vanshbordia/vlrdevapi/discussions)

## Frequently Asked Questions

### Is this an official VLR.gg API?

No. VLR.gg does not provide an official API. vlrdevapi is a community-maintained web scraping library that provides programmatic access to publicly available data on VLR.gg.

### Is web scraping legal?

vlrdevapi only accesses publicly available data and respects VLR.gg's servers with built-in rate limiting, caching, and retry logic. Always use the library responsibly.

### What Python versions are supported?

Python 3.11 and higher. The library uses modern Python features including type hints and pattern matching.

### How do I get player/event IDs?

IDs can be found in VLR.gg URLs. For example, in `https://www.vlr.gg/player/4164/aspas`, the player ID is `4164`.

### Does it support other games?

No. vlrdevapi is specifically designed for Valorant esports data from VLR.gg.

## Project Structure

```
vlrdevapi/
├── src/vlrdevapi/          # Source code
│   ├── events.py           # Events API
│   ├── matches.py          # Matches API
│   ├── players.py          # Players API
│   ├── series.py           # Series API
│   ├── fetcher.py          # HTTP client
│   ├── utils.py            # Parsing utilities
│   ├── exceptions.py       # Custom exceptions
│   └── constants.py        # Configuration
├── tests/                  # Test suite
│   ├── lib/                # Library tests
│   └── html_sources/       # HTML fixtures
├── docs/                   # Documentation
└── pyproject.toml          # Package configuration
```

## Contributing

Contributions are welcome! Please ensure:

1. All tests pass: `pytest tests/lib/`
2. Code follows project style
3. New features include tests and documentation

## License

Released under the MIT License. See LICENSE for details.


## Disclaimer

This library scrapes data from VLR.gg. Please use responsibly and respect their terms of service. The library includes rate limiting protection and caching to minimize server load. vlrdevapi is not affiliated with or endorsed by VLR.gg or Riot Games.

## Version

Current version: **1.0.0**
