Features

This page covers ValoPy’s core features and how to use them effectively.

Key Features

🚀 Async/Await - Built on asyncio for non-blocking operations
📦 Auto-parsing - Automatic JSON parsing into typed dataclass models
🔄 Error Handling - Built-in exception classes for API errors
📚 Type Hints - Full type annotations for IDE support and static analysis

Using the Client

The Client class is the main entry point for all API interactions.

Context Manager (Recommended)

The recommended way to use the client is as an async context manager, which automatically handles session cleanup:

from valopy import Client

async def main():
    async with Client(api_key="your-api-key") as client:
        account = await client.get_account_v1("Name", "Tag")
        # Session is automatically closed when exiting the block

Manual Session Management

For more control, you can manage the session manually:

from valopy import Client

async def main():
    client = Client(api_key="your-api-key")
    try:
        account = await client.get_account_v1("Name", "Tag")
    finally:
        await client.close()  # Always close the session

Client Options

The client accepts these parameters:

client = Client(
    api_key="your-api-key",  # Required: Your API key
    redact_header=True,      # Optional: Redact API key in logs (default: True)
)

Available Methods

The client currently provides these methods:

Account Methods

Method	Description
`get_account_v1()`	Get account information by name and tag (V1)
`get_account_v2()`	Get account information by name and tag (V2) with additional fields like title and platforms

Content Methods

Method	Description
`get_content()`	Get game content including characters, maps, skins, sprays, and acts

Version Methods

Method	Description
`get_version()`	Get current game version information for a specific region

Method Parameters

Most methods support these common parameters:

force_update (bool) - Force fresh data instead of cached (default: False)
locale (Locale) - Language/region for localized content
region (Region) - Server region (EU, NA, LATAM, BR, AP, KR)

Example usage:

from valopy import Client, Locale, Region

async with Client(api_key="your-api-key") as client:
    # Get content in Spanish
    content = await client.get_content(locale=Locale.ES_ES)

    # Get version for North America region
    version = await client.get_version(region=Region.NA)

    # Force update account data
    account = await client.get_account_v1("Name", "Tag", force_update=True)

For a complete list of all API endpoints (implemented and planned), see Supported Endpoints.

Error Handling

ValoPy provides specific exception classes for different error scenarios:

from valopy import (
    Client,
    ValoPyHTTPError,
    ValoPyNotFoundError,
    ValoPyPermissionError,
    ValoPyRateLimitError,
)

async with Client(api_key="your-api-key") as client:
    try:
        account = await client.get_account_v1("Name", "Tag")
    except ValoPyNotFoundError:
        print("Account not found")
    except ValoPyPermissionError:
        print("Invalid API key")
    except ValoPyRateLimitError as e:
        print(f"Rate limited, retry after {e.rate_reset}s")
    except ValoPyHTTPError as e:
        print(f"HTTP error: {e.status_code}")

See Exceptions for the complete exception hierarchy.