vlrdevapi

https://vlrdevapi.readthedocs.io/en/latest/
Admin
A comprehensive Python library for accessing Valorant esports data from VLR.gg with type-safe...
Tokens:253,116
Snippets:2,335
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Quickstart Examples for vlrdevapi

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/index.rst.txt

Demonstrates searching for data, retrieving upcoming matches, and fetching player profiles using the vlrdevapi library.

```python
import vlrdevapi as vlr

# Search for anything
results = vlr.search.search("nrg")
print(f"Found {results.total_results} results")

# Get upcoming matches
matches = vlr.matches.upcoming(limit=5)
for match in matches:
    print(f"{match.team1.name} vs {match.team2.name}")

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

--------------------------------

### Quick Example: Search, Upcoming Matches, and Player Profile

Source: https://vlrdevapi.readthedocs.io/en/latest/index.html

Demonstrates basic usage for searching, fetching upcoming matches, and retrieving player profiles. Ensure the vlrdevapi library is installed.

```python
import vlrdevapi as vlr

# Search for anything
results = vlr.search.search("nrg")
print(f"Found {results.total_results} results")

# Get upcoming matches
matches = vlr.matches.upcoming(limit=5)
for match in matches:
    print(f"{match.team1.name} vs {match.team2.name}")

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

```

--------------------------------

### Install Valorant.py

Source: https://vlrdevapi.readthedocs.io/en/latest/installation.html

Install the Valorant.py library using pip.

```APIDOC
## Install Valorant.py

### Description
Install the Valorant.py library using pip.

### Method
pip install

### Endpoint
valorant.py

### Request Example
```bash
pip install valorant.py
```

### Response Example
```
Successfully installed valorant.py-x.x.x
```
```

--------------------------------

### Install lxml using pre-built wheel on Windows

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/installation.rst.txt

If you encounter issues installing lxml on Windows, try using this command to install a pre-built binary wheel.

```bash
pip install --only-binary :all: lxml
```

--------------------------------

### Install Development Dependencies

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/contributing.rst.txt

Clone the repository and install the library in editable mode with development dependencies.

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

--------------------------------

### Install lxml development packages on Linux

Source: https://vlrdevapi.readthedocs.io/en/latest/installation.html

On Debian/Ubuntu or Fedora/RHEL systems, install the necessary development packages before installing lxml.

```bash
# Debian/Ubuntu
sudo apt-get install libxml2-dev libxslt-dev python3-dev

# Fedora/RHEL
sudo dnf install libxml2-devel libxslt-devel python3-devel
```

--------------------------------

### Install lxml development packages on Fedora/RHEL

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/installation.rst.txt

On Fedora or RHEL-based Linux systems, install the required development packages before installing lxml.

```bash
# Fedora/RHEL
sudo dnf install libxml2-devel libxslt-devel python3-devel
```

--------------------------------

### Search Series Example

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/search/search.html

Provides an example of how to search for series by name and print the series name. Make sure to import vlrdevapi.

```python
import vlrdevapi as vlr
series = vlr.search.search_series("vct")
for s in series:
    print(f"{s.name}")
```

--------------------------------

### Install lxml development packages on Debian/Ubuntu

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/installation.rst.txt

On Debian-based Linux systems, install the necessary development packages before attempting to install lxml.

```bash
# Debian/Ubuntu
sudo apt-get install libxml2-dev libxslt-dev python3-dev
```

--------------------------------

### Install vlrdevapi

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/index.rst.txt

Install the library using pip. Requires Python 3.11 or higher.

```bash
pip install vlrdevapi
```

--------------------------------

### Verify vlrdevapi Installation

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/installation.rst.txt

After installation, run this Python code to confirm that the vlrdevapi library is installed correctly and to check its version.

```python
import vlrdevapi as vlr
print(vlr.__version__)
```

--------------------------------

### Async Fetching Example

Source: https://vlrdevapi.readthedocs.io/en/latest/quickstart.html

Utilize asynchronous helper functions from `vlrdevapi.fetcher` for use within async applications. This example shows how to fetch HTML content asynchronously.

```python
import asyncio
from vlrdevapi import fetcher

async def load_match_async(match_url: str) -> str:
    html = await fetcher.fetch_html_async(match_url)
    return html

asyncio.run(load_match_async("https://www.vlr.gg"))

```

--------------------------------

### Example of Rate Limiting in Action

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/rate-limiting.rst.txt

Demonstrates how the library automatically throttles requests when a custom rate limit is set. This example makes 5 requests, which will take approximately 2.5 seconds when the limit is 2 requests per second.

```python
import time
import vlrdevapi as vlr

# Set a conservative rate limit
vlr.configure_rate_limit(requests_per_second=2.0, enabled=True)  # 2 requests/second

start = time.time()

# Make 5 requests - will automatically throttle
for i in range(5):
    info = vlr.series.info(match_id=12345 + i)
    print(f"Request {i+1} completed")

elapsed = time.time() - start
print(f"Total time: {elapsed:.1f}s")
# Expected: ~2.5 seconds for 5 requests at 2 req/s
```

--------------------------------

### Comprehensive Team Analysis with VLR.dev API

Source: https://vlrdevapi.readthedocs.io/en/latest/examples.html

A multi-step example to perform end-to-end analysis of a team, starting with fetching basic team information and roster details. Requires the team ID.

```python
import vlrdevapi as vlr

# Comprehensive team analysis
team_id = 799  # Velocity Gaming

# Get team info
info = vlr.teams.info(team_id=team_id)
print(f"Team: {info.name} ({info.tag})")
print(f"Region: {info.country}")

# Get roster
roster = vlr.teams.roster(team_id=team_id)
print(f"\nRoster: {len(roster)} players")

```

--------------------------------

### Get Series Matches

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/series/matches.html

Retrieves a list of all matches within a given series. This is the primary function to start exploring match data.

```APIDOC
## matches()

### Description
Retrieves a list of all matches within a given series.

### Method
`matches()`

### Parameters
None

### Response
Returns a list of match objects. Each match object contains detailed information about the games played in the series.
```

--------------------------------

### Get Event Teams - Python

Source: https://vlrdevapi.readthedocs.io/en/latest/api/events.html

Fetches the list of teams participating in a given event. The example iterates through the returned teams to display their name, ID, and type.

```python
>>> import vlrdevapi as vlr
>>> teams = vlr.events.teams(event_id=123)
>>> for team in teams:
...     print(f"{team.name} (ID: {team.id}) - Type: {team.type}")
```

--------------------------------

### Basic Usage

Source: https://vlrdevapi.readthedocs.io/en/latest/installation.html

A simple example of how to use the Valorant.py library to fetch player data.

```APIDOC
## Basic Usage

### Description
A simple example of how to use the Valorant.py library to fetch player data.

### Method
Python

### Endpoint
valorant.py

### Request Example
```python
import valorant

client = valorant.Client("YOUR_API_KEY")

player_data = client.get_player_profile("playername#tag")
print(player_data)
```

### Response Example
```json
{
  "puuid": "...",
  "gameName": "playername",
  "tagLine": "tag",
  "profileIcon": "...",
  "level": 100,
  "rank": "Immortal",
  "rankIcon": "...",
  "score": 1000,
  "lastPlayed": "..."
}
```
```

--------------------------------

### Search Teams Example

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/search/search.html

Shows how to search for teams by name and print their name and active status. Ensure vlrdevapi is imported.

```python
import vlrdevapi as vlr
teams = vlr.search.search_teams("sentinels")
for team in teams:
    print(f"{team.name} - Active: {not team.is_inactive}")
```

--------------------------------

### Search Players Example

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/search/search.html

Demonstrates how to search for players using their in-game name and print their IGN and real name. Requires importing the vlrdevapi library.

```python
import vlrdevapi as vlr
players = vlr.search.search_players("tenz")
for player in players:
    print(f"{player.ign} - {player.real_name}")
```

--------------------------------

### Checking and Adjusting Rate Limits

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/rate-limiting.rst.txt

Monitor the current rate limit setting and cautiously increase it if requests are too slow. This example first prints the current limit and then attempts to increase it to 15 requests per second.

```python
# docs-validate: skip
# Check current setting
print(vlr.get_rate_limit())

# Increase cautiously
vlr.configure_rate_limit(requests_per_second=15.0, enabled=True)
```

--------------------------------

### Get Match Information

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/search/search.html

Retrieves a list of matches. This is a high-level function to get basic match data.

```APIDOC
## GET /matches

### Description
Retrieves a list of matches. This function provides a high-level overview of available matches.

### Method
GET

### Endpoint
/matches

### Parameters
None

### Response
#### Success Response (200)
- **matches** (list) - A list of match objects.

#### Response Example
{
  "matches": [
    {
      "id": "match_id_1",
      "date": "2023-10-27",
      "team1": "Team A",
      "team2": "Team B",
      "score": "2-1"
    },
    {
      "id": "match_id_2",
      "date": "2023-10-26",
      "team1": "Team C",
      "team2": "Team D",
      "score": "0-2"
    }
  ]
}
```

--------------------------------

### Get Match Information

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/events/matches.html

Fetches a list of recent matches. This is the primary function to get an overview of ongoing or completed matches.

```APIDOC
## matches()

### Description
Retrieves a list of recent Valorant matches.

### Method
GET

### Endpoint
/matches

### Parameters
None

### Response
#### Success Response (200)
- **matches** (list) - A list of match objects, each containing summary information.

### Response Example
{
  "matches": [
    {
      "id": "match_id_1",
      "event": "VCT 2023 - Americas League",
      "date": "2023-05-15",
      "team1": {"name": "Team A", "score": 1, "short": "TA"},
      "team2": {"name": "Team B", "score": 2, "short": "TB"}
    },
    {
      "id": "match_id_2",
      "event": "VCT 2023 - EMEA League",
      "date": "2023-05-14",
      "team1": {"name": "Team C", "score": 0, "short": "TC"},
      "team2": {"name": "Team D", "score": 2, "short": "TD"}
    }
  ]
}
```

--------------------------------

### Search Events Example

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/search/search.html

Illustrates searching for events by name and printing the event name and date range. The vlrdevapi library must be imported.

```python
import vlrdevapi as vlr
events = vlr.search.search_events("champions")
for event in events:
    print(f"{event.name} - {event.date_range}")
```

--------------------------------

### Get Event Information

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/events/info.html

Retrieve details about a specific event using its ID. This function allows you to get comprehensive information about a Valorant event.

```APIDOC
## GET /v1/events/{event_id}

### Description
Retrieves detailed information about a specific Valorant event.

### Method
GET

### Endpoint
/v1/events/{event_id}

### Parameters
#### Path Parameters
- **event_id** (string) - Required - The unique identifier of the event to retrieve.
```

--------------------------------

### Get Event Information

Source: https://vlrdevapi.readthedocs.io/en/latest/quickstart.html

List ongoing events filtered by tier, or get detailed information and match lists for a specific event using its ID.

```python
import vlrdevapi as vlr
# List events
events = vlr.events.list_events(tier="vct", status="ongoing")

# Get event details
info = vlr.events.info(event_id=2498)
print(f"{info.name} - {info.prize}")

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


```

--------------------------------

### Example of Rate Limiting in Action

Source: https://vlrdevapi.readthedocs.io/en/latest/rate-limiting.html

Demonstrates how setting a low rate limit (2 requests/second) affects the execution time of multiple requests. The loop will automatically pause to adhere to the configured limit.

```python
import time
import vlrdevapi as vlr

# Set a conservative rate limit
vlr.configure_rate_limit(requests_per_second=2.0, enabled=True)  # 2 requests/second

start = time.time()

# Make 5 requests - will automatically throttle
for i in range(5):
    info = vlr.series.info(match_id=12345 + i)
    print(f"Request {i+1} completed")

elapsed = time.time() - start
print(f"Total time: {elapsed:.1f}s")
# Expected: ~2.5 seconds for 5 requests at 2 req/s

```

--------------------------------

### Library Caching Example

Source: https://vlrdevapi.readthedocs.io/en/latest/api/exceptions.html

Demonstrates the use of the library's built-in caching mechanism, where the first call fetches data from the network and subsequent calls retrieve data from the cache.

```python
import vlrdevapi as vlr

# First call fetches from network
events1 = vlr.events.list_events()

# Second call uses cache (no network request)
events2 = vlr.events.list_events()

```

--------------------------------

### Get Event Info

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/events/info.html

Retrieves the header and basic information for a given event ID. This function is useful for quickly getting event names, prizes, and other key details without fetching all match data.

```APIDOC
## GET /event/{event_id}

### Description
Retrieves the header and basic information for a given event ID.

### Method
GET

### Endpoint
`/event/{event_id}`

### Parameters
#### Path Parameters
- **event_id** (int) - Required - The unique identifier for the event.

#### Query Parameters
- **timeout** (float) - Optional - The request timeout in seconds. Defaults to the global configuration timeout.

### Request Example
```python
import vlrdevapi as vlr

event_info = vlr.events.info(event_id=123)
if event_info:
    print(f"{event_info.name} - {event_info.prize}")
```

### Response
#### Success Response (200)
- **Info** (object) - An object containing event details such as name, prize, etc. Returns None if the event is not found or an error occurs.

#### Response Example
```json
{
  "name": "VCT 2024: Masters Shanghai",
  "prize": "$500,000 USD",
  "date_start": "2024-05-23",
  "date_end": "2024-06-02"
}
```
```

--------------------------------

### Reset Configuration to Defaults

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/config.rst.txt

Restore all configuration values to their original library defaults.

```python
import vlrdevapi as vlr

vlr.reset_config()
```

--------------------------------

### Get Team Transactions

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/teams/transactions.html

Retrieves the complete transaction history for a team from VLR.gg. Use this to get a list of player joins, leaves, and status changes for a specific team. Returns an empty list if the team is not found or has no transactions.

```python
def transactions(team_id: int, timeout: float | None = None) -> list[PlayerTransaction]:
    """
    Get all team transactions (joins, leaves, inactive status changes, etc.).
    
    Retrieves the complete transaction history for a team from the VLR.gg transactions page.
    Each transaction includes the date, action type, player information, position, and reference URL.
    
    Args:
        team_id: Team ID from VLR.gg (e.g., 1034 for NRG)
        timeout: Request timeout in seconds (default: 5.0)
    
    Returns:
        List of PlayerTransaction objects, ordered by date (most recent first).
        Returns empty list if team not found or has no transactions.
    
    Raises:
        NetworkError: If the request fails after retries
    
    Example:
        >>> import vlrdevapi as vlr
        >>> 
        >>> # Get all transactions for NRG
        >>> txns = vlr.teams.transactions(team_id=1034)
        >>> 
        >>> # Display recent transactions
        >>> for txn in txns[:5]:
        ...     if txn.date:
        ...         print(f"{txn.date.strftime('%Y/%m/%d')}: {txn.ign} - {txn.action} ({txn.position})")
        ...     else:
        ...         print(f"Unknown: {txn.ign} - {txn.action} ({txn.position})")
        2025/10/02: FiNESSE - leave (Player)
        2025/05/09: skuba - join (Player)
        
        >>> # Filter by action type
        >>> joins = [t for t in txns if t.action == "join"]
        >>> leaves = [t for t in txns if t.action == "leave"]
    
    Note:
        Transaction actions include: 'join', 'leave', 'inactive', and others.
        All text fields are cleaned of extra whitespace, tabs, and newlines.
    """
    url = f"{_config.vlr_base}/team/transactions/{team_id}"
    effective_timeout = timeout if timeout is not None else _config.default_timeout
    try:
        html = fetch_html(url, effective_timeout)
    except NetworkError:
        return []
    
    soup = BeautifulSoup(html, "lxml")
    
    # Find the transactions table
    table = soup.select_one("table.wf-faux-table")
    if not table:
        return []
    
    tbody = table.select_one("tbody")
    if not tbody:
        return []
    
    transactions_list: list[PlayerTransaction] = []
    
    # Process each transaction row
    for row in tbody.select("tr.txn-item"):
        # Extract date
        date_td = row.select_one("td:nth-of-type(1)")
        date_str = normalize_whitespace(extract_text(date_td)) if date_td else None
        if date_str == "":
            date_str = None
        
        # Parse date
        transaction_date = _parse_transaction_date(date_str)
        
        # Extract action
        action_td = row.select_one("td.txn-item-action")
        action = normalize_whitespace(extract_text(action_td)) if action_td else None
        if action == "":
            action = None
        
        # Extract country from flag using utility function
        flag_td = row.select_one("td:nth-of-type(3)")
        country_code = extract_country_code(flag_td)
        country = map_country_code(country_code) if country_code else None
        
        # Extract player info
        player_td = row.select_one("td:nth-of-type(4)")
        player_id = None
        ign = None
        real_name = None
        
        if player_td:
            # Get player link
            player_link = player_td.select_one("a[href]")
            if player_link:
                href_val = player_link.get("href")
                href = href_val if isinstance(href_val, str) else None
                player_id = extract_id_from_url(href, "player")
                ign = normalize_whitespace(extract_text(player_link))
                if ign == "":
                    ign = None

```

--------------------------------

### Comprehensive Team Analysis Example

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/examples.rst.txt

Performs a multi-step analysis of a team, including fetching general info, roster, recent matches, and tournament placements. Requires the vlrdevapi library.

```python
import vlrdevapi as vlr

# Comprehensive team analysis
team_id = 799  # Velocity Gaming

# Get team info
info = vlr.teams.info(team_id=team_id)
print(f"Team: {info.name} ({info.tag})")
print(f"Region: {info.country}")

# Get roster
roster = vlr.teams.roster(team_id=team_id)
print(f"\nRoster: {len(roster)} players")

# Get recent matches
recent = vlr.teams.completed_matches(team_id=team_id, limit=5)
print(f"\nLast 5 matches:")
for match in recent:
    result = f"{match.team1.score}-{match.team2.score}"
    print(f"  {match.team1.name} vs {match.team2.name}: {result}")
    if match.match_datetime:
        print(f"    Date: {match.match_datetime.strftime('%B %d, %Y')}")

# Get placements
placements = vlr.teams.placements(team_id=team_id)
print(f"\nTotal events participated: {len(placements)}")

# Show top 3 recent placements
for placement in placements[:3]:
    print(f"\n{placement.event_name} ({placement.year})")
    for detail in placement.placements:

```

--------------------------------

### Get Detailed Map Statistics

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/api/series.rst.txt

Use `vlr.series.matches` with a `series_id` to get per-map statistics. This includes team scores for each map, the map winner, and detailed player statistics like K/D/A, Rating, ACS, ADR, and KAST.

```python
import vlrdevapi as vlr

# Get per-map statistics
maps = vlr.series.matches(series_id=530935)

for i, map_data in enumerate(maps, 1):
    print(f"\nMap {i}: {map_data.map_name}")
    
    # Team scores
    if map_data.teams:
        team1, team2 = map_data.teams
        print(f"{team1.name} {team1.score} - {team2.score} {team2.name}")
        winner = team1.name if team1.is_winner else team2.name
        print(f"Winner: {winner}")
    
    # Player statistics
    print("\nPlayer Stats:")
    for player in map_data.players:
        print(f"  {player.name} ({player.team_short})")
        print(f"    K/D/A: {player.k}/{player.d}/{player.a}")
        print(f"    Rating: {player.r}, ACS: {player.acs}")
        print(f"    ADR: {player.adr}, KAST: {player.kast}")
```

--------------------------------

### Import vlrdevapi Library

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/quickstart.rst.txt

Import the library to start using its functionalities.

```python
import vlrdevapi as vlr
```

--------------------------------

### Live Matches

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/players/matches.html

Retrieves a list of currently live matches. Ideal for real-time monitoring of ongoing Valorant games.

```APIDOC
## live()

### Description
Fetches a list of currently live matches.

### Method
APICall

### Endpoint
/matches/live

### Parameters
None

### Response
#### Success Response (200)
- **matches** (list of Match objects) - A list containing Match objects for live matches.

### Response Example
{
  "matches": [
    {
      "match_id": "67890",
      "team1": {
        "name": "Team C",
        "id": "team_c_id",
        "country": "KR",
        "score": 10
      },
      "team2": {
        "name": "Team D",
        "id": "team_d_id",
        "country": "JP",
        "score": 8
      },
      "event_phase": "Finals",
      "event": {
        "event_id": "event_xyz",
        "name": "VCT Pacific League",
        "date_range": "2024-04-01 to 2024-04-30",
        "prize": "150000 USD",
        "image_url": "http://example.com/event2.png"
      },
      "time": "2024-04-10T20:00:00Z",
      "status": "Live",
      "date": "2024-04-10"
    }
  ]
}
```

--------------------------------

### Get Team Information

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/teams/info.html

Retrieves detailed information for a given team ID. Handles network requests and parsing of team data from VLR.gg. Use this function to get a TeamInfo object containing name, tag, country, social links, and more.

```python
import vlrdevapi as vlr



def info(team_id: int, timeout: float | None = None) -> TeamInfo | None:
    """
    Get team information.

    Args:
        team_id: Team ID
        timeout: Request timeout in seconds

    Returns:
        Team information or None if not found

    Example:
        >>> import vlrdevapi as vlr
        >>> team = vlr.teams.info(team_id=1034)
        >>> print(f"{team.name} ({team.tag}) - {team.country}")
    """
    url = f"{_config.vlr_base}/team/{team_id}"
    effective_timeout = timeout if timeout is not None else _config.default_timeout
    
    # Fetch page with light mode (dm=0)
    try:
        html_light = fetch_html(url, effective_timeout, cookies={"dm": "0"})
    except NetworkError:
        return None

    # Fetch page with dark mode (dm=1)
    try:
        html_dark = fetch_html(url, effective_timeout, cookies={"dm": "1"})
    except NetworkError:
        html_dark = html_light  # Fallback to light mode if dark mode fails

    soup_light = BeautifulSoup(html_light, "lxml")
    soup_dark = BeautifulSoup(html_dark, "lxml")
    
    header_light = soup_light.select_one(".team-header")
    header_dark = soup_dark.select_one(".team-header")

    if not header_light:
        return None

    # Extract team name
    name_el = header_light.select_one("h1.wf-title")
    name = extract_text(name_el) if name_el else None

    # Extract team tag
    tag_el = header_light.select_one("h2.team-header-tag")
    tag = extract_text(tag_el) if tag_el else None

    # Extract logo URL for light mode
    logo_url_light: str | None = None
    logo_img_light = header_light.select_one(".team-header-logo img")
    if logo_img_light:
        src_val = logo_img_light.get("src")
        src = src_val if isinstance(src_val, str) else None
        if src:
            logo_url_light = absolute_url(src)

    # Extract logo URL for dark mode
    logo_url_dark: str | None = None
    logo_img_dark = header_dark.select_one(".team-header-logo img")
    if logo_img_dark:
        src_val = logo_img_dark.get("src")
        src = src_val if isinstance(src_val, str) else None
        if src:
            logo_url_dark = absolute_url(src)

    # Use light mode logo as the default logo_url for backward compatibility
    logo_url = logo_url_light

    # Check if team is active
    is_active = True
    status_el = header_light.select_one(".team-header-status")
    if status_el:
        status_text = extract_text(status_el).lower()
        if "inactive" in status_text:
            is_active = False

    # Extract country
    country: str | None = None
    country_el = header_light.select_one(".team-header-country")
    if country_el:
        flag = country_el.select_one(".flag")
        if flag:
            classes_val = flag.get("class")
            classes: list[str] = [c for c in classes_val if isinstance(c, str)] if isinstance(classes_val, (list, tuple)) else []
            for cls in classes:
                if cls.startswith("mod-") and cls != "mod-dark":
                    code = cls.removeprefix("mod-")
                    country = map_country_code(code)
                    break

    # Extract social links
    socials: list[SocialLink] = []
    links_container = header_light.select_one(".team-header-links")
    if links_container:
        for anchor in links_container.select("a[href]"):
            href_val = anchor.get("href")
            href = (href_val if isinstance(href_val, str) else "").strip()
            label = extract_text(anchor).strip()
            # Skip empty links
            if href and label and href != "":
                full_url = absolute_url(href) or href
                socials.append(SocialLink(label=label, url=full_url))

    # Extract previous and current team information
    previous_team: PreviousTeam | None = None
    current_team: SuccessorTeam | None = None
    successor_el = header_light.select_one(".team-header-name-successor")
    if successor_el:
        successor_text = extract_text(successor_el).lower()
        link = successor_el.select_one("a[href]")
        if link:
            href_val = link.get("href")
            href = href_val if isinstance(href_val, str) else None
            linked_team_id = extract_id_from_url(href, "team")
            linked_name = extract_text(link)
            if linked_name:
                if "previously" in successor_text:
                    previous_team = PreviousTeam(team_id=linked_team_id, name=linked_name)
                if "currently" in successor_text:
                    current_team = SuccessorTeam(team_id=linked_team_id, name=linked_name)

    return TeamInfo(
        team_id=team_id,
        name=name,
        tag=tag,
        country=country,
        logo_url=logo_url,
        is_active=is_active,
        social_links=socials,
        previous_team=previous_team,
        successor_team=current_team,
    )

```

--------------------------------

### Get Roster

Source: https://vlrdevapi.readthedocs.io/en/latest/search.html

Retrieves a general roster list.

```APIDOC
## GET /roster

### Description
Retrieves a general list of team rosters.

### Method
GET

### Endpoint
/roster
```

--------------------------------

### Specific Exception Handling for RateLimitError and NetworkError

Source: https://vlrdevapi.readthedocs.io/en/latest/api/exceptions.html

Demonstrates best practice by catching specific exceptions like RateLimitError and NetworkError separately to implement tailored error handling.

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

try:
    data = vlr.events.list_events()
except RateLimitError:
    # Handle rate limiting specifically
    pass
except NetworkError:
    # Handle other network errors
    pass

```

--------------------------------

### Get Transactions

Source: https://vlrdevapi.readthedocs.io/en/latest/search.html

Retrieves a list of player transactions.

```APIDOC
## GET /transactions

### Description
Retrieves a general list of player transactions.

### Method
GET

### Endpoint
/transactions
```

--------------------------------

### Handle Rate Limiting Errors in Python

Source: https://vlrdevapi.readthedocs.io/en/latest/_sources/api/exceptions.rst.txt

This example demonstrates how to catch `RateLimitError` (HTTP 429) and implement a retry mechanism with a delay.

```python
import vlrdevapi as vlr
from vlrdevapi.exceptions import RateLimitError
import time

try:
    matches = vlr.matches.upcoming()
except RateLimitError:
    print("Rate limited. Waiting before retry...")
    time.sleep(60)
    matches = vlr.matches.upcoming()
```

--------------------------------

### Type Hinting with Models

Source: https://vlrdevapi.readthedocs.io/en/latest/api/models.html

Shows how to use type hints with vlrdevapi models for better code clarity and maintainability. This example defines a function that accepts a `Profile` object and uses its type-hinted attributes.

```python
import vlrdevapi as vlr
from vlrdevapi.players import Profile

def print_player_info(profile: Profile) -> None:
    print(f"{profile.handle} from {profile.country}")

profile = vlr.players.profile(player_id=4164)
print_player_info(profile)


```

--------------------------------

### Get Placements

Source: https://vlrdevapi.readthedocs.io/en/latest/search.html

Retrieves placement information for events.

```APIDOC
## GET /placements

### Description
Retrieves placement data for various events.

### Method
GET

### Endpoint
/placements
```

--------------------------------

### Get Live Matches

Source: https://vlrdevapi.readthedocs.io/en/latest/api/matches.html

Fetches a list of currently live matches. The number of results can be limited.

```python
import vlrdevapi as vlr
matches = vlr.matches.live()
for match in matches:
    print(f"LIVE: {match.team1.name} vs {match.team2.name}")
```

--------------------------------

### Get Event Match Summary

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/events/match_summary.html

Fetches and parses the match summary for a specific event ID. Handles network errors and returns a structured MatchSummary object or None if the event is not found or an error occurs. Use this to get an overview of matches within an event.

```python
import vlrdevapi as vlr


try:
    summary = vlr.events.match_summary(event_id=123)
    if summary:
        print(f"Total Matches: {summary.total_matches}")
        print(f"Completed Matches: {summary.completed}")
        print(f"Upcoming Matches: {summary.upcoming}")
        print(f"Ongoing Matches: {summary.ongoing}")
        for stage in summary.stages:
            print(f"Stage: {stage.name}")
            print(f"  Matches: {stage.match_count}")
            print(f"  Completed: {stage.completed}")
            print(f"  Upcoming: {stage.upcoming}")
            print(f"  Ongoing: {stage.ongoing}")
            print(f"  Start Date: {stage.start_date}")
            print(f"  End Date: {stage.end_date}")
    else:
        print("Match summary not found or an error occurred.")
except Exception as e:
    print(f"An error occurred: {e}")
```

--------------------------------

### Get Previous Players

Source: https://vlrdevapi.readthedocs.io/en/latest/search.html

Retrieves a list of all previous players.

```APIDOC
## GET /previous_players

### Description
Retrieves a list of players who have previously competed or been associated with teams.

### Method
GET

### Endpoint
/previous_players
```

--------------------------------

### Implement Pagination

Source: https://vlrdevapi.readthedocs.io/en/latest/quickstart.html

Fetch specific pages of results for endpoints that support pagination, such as completed matches.

```python
import vlrdevapi as vlr
# Get specific page
page1 = vlr.matches.completed(page=1)
page2 = vlr.matches.completed(page=2)


```

--------------------------------

### Handle Rate Limiting

Source: https://vlrdevapi.readthedocs.io/en/latest/rate-limiting.html

Example of how to catch and handle `RateLimitError` specifically, implementing a retry mechanism with exponential backoff.

```APIDOC
## Handle Rate Limiting

### Description
This example demonstrates how to catch a `RateLimitError` and implement a retry strategy. It includes a simple exponential backoff mechanism.

### Method
```python
try:
    # Make an API call that might be rate limited
    response = vlrdevapi.some_function()
except vlrdevapi.RateLimitError as e:
    print(f"Rate limit exceeded: {e}")
    # Implement retry logic, e.g., exponential backoff
    retry_delay = 1  # Start with 1 second delay
    max_retries = 5
    for attempt in range(max_retries):
        print(f"Retrying in {retry_delay} seconds...")
        time.sleep(retry_delay)
        try:
            response = vlrdevapi.some_function()
            break  # Success, exit retry loop
        except vlrdevapi.RateLimitError as retry_e:
            print(f"Retry attempt {attempt + 1} failed: {retry_e}")
            retry_delay *= 2  # Double the delay for next retry
        except Exception as other_e:
            print(f"An unexpected error occurred during retry: {other_e}")
            break # Exit if it's not a rate limit error
    else: # This else block executes if the loop completes without a break
        print("Max retries reached. Could not complete the request.")
except vlrdevapi.VlrdevapiError as e:
    print(f"An API error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")
```

### Parameters
None for this example, as it focuses on exception handling.

### Request Example
N/A

### Response
N/A (focus is on error handling)
```

--------------------------------

### Get Upcoming Matches

Source: https://vlrdevapi.readthedocs.io/en/latest/search.html

Retrieves a list of upcoming matches.

```APIDOC
## GET /matches/upcoming

### Description
Retrieves a list of all upcoming matches across different events.

### Method
GET

### Endpoint
/matches/upcoming
```

--------------------------------

### List Live Events

Source: https://vlrdevapi.readthedocs.io/en/latest/_modules/vlrdevapi/events/info.html

Fetches a list of all currently live Valorant events. This is ideal for tracking ongoing tournaments.

```APIDOC
## GET /v1/events/live

### Description
Retrieves a list of all currently live Valorant events.

### Method
GET

### Endpoint
/v1/events/live
```

--------------------------------

### Get Matches

Source: https://vlrdevapi.readthedocs.io/en/latest/api/events.html

Retrieves a list of matches for a given event.

```APIDOC
## matches()

### Description
Retrieves a list of matches for a given event.

### Method
GET

### Endpoint
/events/matches

### Parameters
#### Query Parameters
- **event_id** (string) - Required - The ID of the event to retrieve matches for.

### Response
#### Success Response (200)
- **data** (list of Match) - A list of match objects.

### Response Example
{
  "data": [
    {
      "id": "match-123",
      "date": "2024-05-26",
      "time": "10:00:00",
      "stage": "Upper Bracket Round 1",
      "teams": [
        {
          "id": "team-a",
          "name": "Team Alpha",
          "short": "ALP",
          "score": 2
        },
        {
          "id": "team-b",
          "name": "Team Beta",
          "short": "BET",
          "score": 1
        }
      ],
      "map_results": [
        {
          "map": "Ascent",
          "scores": {
            "team-a": 13,
            "team-b": 9
          }
        },
        {
          "map": "Bind",
          "scores": {
            "team-a": 10,
            "team-b": 13
          }
        },
        {
          "map": "Haven",
          "scores": {
            "team-a": 13,
            "team-b": 7
          }
        }
      ]
    }
  ]
}
```
Tokens:
Raw