Configuration

The vlrdevapi library provides a global configuration system that allows you to customize timeouts, retries, backoff, base URL, default User-Agent, and rate limiting behavior at runtime.

This page describes how to configure the client and what options are available.

Overview

Configuration is exposed via two top-level helpers:

  • vlr.configure(...): Update one or more global settings.

  • vlr.reset_config(): Reset all settings back to library defaults.

These settings are consumed across the package by modules such as fetcher, events, series, matches, players, teams, and search. The defaults are applied lazily at call time, so changes take effect immediately without re-importing modules.

Available Options

You can set any of the following options via vlr.configure:

  • vlr_base The base URL for VLR.gg. Defaults to "https://www.vlr.gg".

  • default_timeout Default timeout in seconds for HTTP requests. Defaults to 5.0.

  • default_user_agent Default User-Agent header used for requests. Defaults to a Chrome-like UA string.

  • max_retries Maximum number of retries for failed requests in the fetcher. Defaults to 3.

  • backoff_factor Exponential backoff multiplier used by the fetcher. Defaults to 1.0.

  • default_rate_limit The default requests-per-second limit for built-in rate limiting. Defaults to 10.

  • default_rate_limit_enabled Whether rate limiting is enabled by default. Defaults to True.

Quick Examples

Increase HTTP timeout and retries

import vlrdevapi as vlr

# Increase default timeout and retry behavior
vlr.configure(default_timeout=10.0, max_retries=5, backoff_factor=2.0)

# Calls now use the new defaults without code changes
events = vlr.events.list_events(limit=5)

Customize User-Agent

import vlrdevapi as vlr

# Set a custom User-Agent string for all outbound requests
vlr.configure(default_user_agent="MyApp/1.0 (+https://example.com)")

Change Base URL (advanced)

import vlrdevapi as vlr

# Point to an alternate origin or proxy if needed
vlr.configure(vlr_base="https://my-proxy.example.com")

Rate Limiting

The library supports basic requests-per-second limiting using a lightweight token bucket. You can control whether it is enabled and what the default rate is via the configuration system.

To update global rate limiting behavior at runtime:

import vlrdevapi as vlr

# Disable rate limiting
vlr.configure(default_rate_limit_enabled=False)

# Enable and set to 20 requests per second
vlr.configure(default_rate_limit=20, default_rate_limit_enabled=True)

You can also adjust rate limiting during execution using the dedicated helpers in vlr.fetcher:

import vlrdevapi as vlr

# Reduce rate temporarily for a critical section
vlr.configure_rate_limit(requests_per_second=5, enabled=True)

# Reset to your configured defaults (reads from vlr.configure values)
vlr.reset_rate_limit()

Reset to Defaults

To restore all configuration values back to the package defaults:

import vlrdevapi as vlr

vlr.reset_config()

Interaction With fetcher

The fetcher module uses these configuration values when computing request headers, timeouts, retry counts, and backoff. You can override any of these per-call by passing parameters to the public functions:

from vlrdevapi.fetcher import fetch_html

# Override timeout and user agent just for this call
html = fetch_html(
    url="https://www.vlr.gg/matches",
    timeout=2.5,
)

Notes

  • Configuration takes effect immediately. There is no need to re-import modules.

  • If you set an option to None, the previous value is retained.