Data Models

All data returned by vlrdevapi is structured using standard Python frozen dataclasses with full type hints.

Model Features

All models are:

Immutable: Models are frozen (frozen=True) and cannot be modified after creation
Type-safe: Full type hints for all fields (including str | None unions)
Serializable: Easily converted to dict/JSON using dataclasses.asdict

Common Patterns

Accessing Model Data

import vlrdevapi as vlr

# Get a model instance
profile = vlr.players.profile(player_id=4164)

# Access fields directly
print(profile.handle)
print(profile.real_name)
print(profile.country)

# Models are immutable
# profile.handle = "new_name"  # This will raise an error

Converting to Dictionary

import json
from dataclasses import asdict
import vlrdevapi as vlr

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

# Convert to dict
data = asdict(profile)
print(data)

# Convert to JSON
# Note: use default=str to serialize datetime/date objects
json_str = json.dumps(data, default=str)

Optional Fields

Many fields are optional and may be None:

import vlrdevapi as vlr

match = vlr.matches.upcoming()[0]

# Check if optional field exists
if match.date:
    print(f"Date: {match.date.isoformat()}")
else:
    print("Date not available")

Date fields on event info are also optional:

import vlrdevapi as vlr

# Get event info with parsed dates
event = vlr.events.info(event_id=2283)

if event.start_date and event.end_date:
    duration = (event.end_date - event.start_date).days
    print(f"Event duration: {duration} days")
    print(f"From {event.start_date} to {event.end_date}")

Lists and Nested Objects

Some fields contain lists or nested objects:

import vlrdevapi as vlr

# Team objects in matches
match = vlr.matches.upcoming()[0]
print(f"{match.team1.name} vs {match.team2.name}")
print(f"Countries: {match.team1.country} vs {match.team2.country}")

# List of variable length
profile = vlr.players.profile(player_id=4164)
for team in profile.current_teams:
    print(team.name)

Events Models

See Events API for detailed documentation of:

ListEvent
Info
MatchTeam
Match
StageMatches
MatchSummary
StandingEntry
Standings
Team

Matches Models

See Matches API for detailed documentation of:

Team (team information with name, country, score)
Match (match information with team1, team2, event details)

Players Models

See Players API for detailed documentation of:

SocialLink (social media links)
Team (team membership with role and dates)
Profile (player profile with teams and socials)
MatchTeam (team info in player matches)
Match (player match with stage, phase, result)
AgentStats (agent performance statistics)

Series Models

See Series API for detailed documentation of:

TeamInfo
MapAction
Info
PlayerStats
MapTeamScore
RoundResult
MapPlayers

Field Types

Common field types used across models:

Primitive Types

int: Integer values (IDs, scores, counts)
float: Decimal values (ratings, percentages)
str: Text values (names, URLs)
bool: Boolean flags (is_winner, etc.)

Date and Time

datetime.date: Date values (match dates, join dates)
datetime.time: Time values (match times)

Collections

List[T]: Variable-length lists
Tuple[T, T]: Fixed-length tuples (usually 2 teams)
Optional[T]: Values that may be None

Literals

Literal[“a”, “b”]: String values restricted to specific options

Example: status field can only be “upcoming”, “live”, or “completed”

Runtime Validation

Models are plain dataclasses and do not perform runtime validation. They rely on the library’s HTML parsing logic and Python type hints.

Tips:

# Prefer using type checkers (pyright/mypy) during development
# and validate inputs/outputs in your own code where necessary.

Best Practices

Type Hints

Use type hints when working with models:

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)

None Checks

Always check optional fields before use:

import vlrdevapi as vlr

match = vlr.matches.upcoming()[0]

# Safe access
if match.date:
    print(f"Date: {match.date.isoformat()}")

# Or use default value
date_str = match.date.isoformat() if match.date else "TBD"

Iteration

Iterate over lists safely:

import vlrdevapi as vlr

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

# Check if list has items
if profile.current_teams:
    for team in profile.current_teams:
        print(team.name)
else:
    print("No current teams")