The
async_fetch module is the core of the tif1 data fetching infrastructure. It provides async HTTP capabilities with HTTP/2 multiplexing, retry logic, circuit breaker protection, and multi-CDN fallback.Overview
The async fetch system is built onniquests (a modern, actively-maintained fork of requests) and provides:
- HTTP/2 Multiplexing: Single TCP connection for multiple parallel requests, which reduces latency
- Connection Pooling: Connection reuse with configurable pool sizing and keep-alive
- Parallel JSON Parsing: Offloads JSON parsing to thread pools to avoid blocking the async event loop
- Rate Limiting: Semaphore-based concurrency control to prevent CDN overload
- Automatic Retries: Exponential backoff with jitter and circuit breaker protection
- Multi-CDN Fallback: Automatic failover across multiple CDN sources (jsDelivr, Hugging Face buckets, StaticDelivr, custom CDNs)
- Smart Caching: SQLite-backed cache with in-memory LRU layer for hot data
- Payload Validation: Optional pydantic-free fetch-path validation for data integrity
- Resource Management: Automatic cleanup of connections, thread pools, and process pools
Most users do not need to interact with this module directly. The
Session class handles async fetching automatically through methods like laps_async(), get_fastest_laps_tels_async(), and load(). This documentation is for advanced users who need fine-grained control over fetching behavior or want to understand the performance characteristics.Architecture
Data Flow
The async fetch system follows this execution path:- Cache Check: Query in-memory LRU cache, then SQLite cache (if enabled)
- Network Fetch: If cache miss, fetch from CDN with HTTP/2 multiplexing
- JSON Parsing: Offload parsing to thread pool (or process pool for non-telemetry data)
- Validation: Optional fetch-path validation based on payload type
- Cache Write: Persist to SQLite and in-memory cache (if enabled)
- Return: Deliver parsed dictionary to caller
Thread Safety
The shared resources use these protections:- The shared HTTP session is created under a lock
- Thread pool executor is lazily initialized with lock protection
- Circuit breaker uses reentrant locks for nested calls
- CDN manager failure counters are plain dictionary updates without a lock (see the CDN API)
Resource Lifecycle
Resources are managed automatically:- HTTP Session: Created on first use, reused across all requests, closed on shutdown
- Thread Pool: Created on first use, sized as the largest of
max_workers,max_concurrent_requests, andtelemetry_prefetch_max_concurrent_requests - Process Pool: Optional, created on first use if
json_parse_workers > 0 - Cleanup: All resources cleaned up via
atexithandlers or explicitcleanup_resources()call
Core Functions
fetch_json_async
Parameters
Season year (for example, 2025, 2024). Must be a valid F1 season year with available data.
Grand Prix name (for example, “Monaco Grand Prix”, “Bahrain Grand Prix”). Must match the exact event name in the schedule data. No fuzzy matching applies here:
"Monaco" raises DataNotFoundError. The cache key uses the string as given, so "Monaco Grand Prix" and the URL-encoded "Monaco%20Grand%20Prix" that Session passes are cached separately.Session name (for example, “Race”, “Qualifying”, “Practice 1”, “Sprint”). Must match the exact session name in the schedule data.
Path to JSON file relative to the session directory. Common paths:
"session_laptimes.json"- All laps of all drivers in the session"drivers.json"- Driver metadata (codes, numbers, names, teams)"weather.json"- Weather data throughout the session"rcm.json"- Race control messages (flags, safety car, etc.)"corners.json"- Corner markers and track rotation"VER/laptimes.json"- Lap times for one driver (for example, Verstappen)"VER/1_tel.json"- Telemetry for driver VER, lap 1
Total number of tries for each request, including the first. If
None, uses global config value (default: 3). Values below 1 still make one try.- Set to
1(or0) for one try with no retries, for the fastest cold-start fetch - Set to
3-5for production use (balance between reliability and latency) - Set to
10+for unreliable networks (maximum reliability)
ultra_cold_skip_retries is True (the default), the ultra-cold Session path calls this function with max_retries=1, so it makes one try.Request timeout in seconds. If
None, uses global config value (default: 30).- Set to
10-15for fast networks (minimize latency) - Set to
30-60for typical networks (balance between speed and reliability) - Set to
120+for slow networks (maximum reliability)
If
True, check cache (in-memory + SQLite) before making network requests. Set to False to force fresh data from CDN.If
True, persist successful network responses to the SQLite cache. Set to False for ephemeral data or testing.Note: Automatically disabled when ci_mode=True in config.If
True, run fetch-path validation on the fetched data before returning. The fetch
path is pydantic-free; public validate_* APIs remain for compatibility.
Validation rules depend on the payload type and on three config flags:rcm.json: Validate race control messages (strict=False, normalize=False) whenvalidate_dataisTrueweather.json: Validate weather data (strict=False) whenvalidate_dataisTruesession_laptimes.json/*/laptimes.json: Validate lap times whenvalidate_lap_timesisTrue*_tel.json: Validate telemetry data (strict=False, normalize=False) whenvalidate_telemetryisTrue
False, so a default fetch runs no validation. Set validate_payload=False to skip validation even when a flag is on.Returns
Parsed JSON data as a dictionary. Never returns
None - raises an exception on error instead.The structure depends on the requested path. Most payloads hold parallel arrays, one per column:session_laptimes.json,*/laptimes.json:{"time": [103.877, ...], "lap": [1, ...], "compound": ["SOFT", ...], "drv": ["VER", ...], ...}drivers.json:{"drivers": [{"driver": "VER", "dn": "1", "fn": "Max", "ln": "Verstappen", "team": "Red Bull Racing", ...}, ...]}weather.json:{"wT": [14.542, ...], "wAT": [27.9, ...], "wTT": [34.5, ...], ...}*_tel.json:{"tel": {"time": [0.0, ...], "rpm": [9992.8, ...], "speed": [0.0, ...], ...}}
Raises
Raised when network request fails after all retry attempts. Context includes:
url: The URL that failedstatus_code: HTTP status code (if available)
- Network connectivity issues
- CDN downtime (all CDN sources failed)
- Circuit breaker open (too many recent failures)
- Timeout exceeded
offline_modeis on and the payload is not cached
Raised when the requested data does not exist (HTTP 404). Context includes:
year: Season yearevent: Grand Prix namesession: Session name
- Invalid year/event/session combination
- Data not yet available for future events
- Typo in event or session name
missing_payloads_ttl_days (default: 7). Until the verdict expires, a call with use_cache=True raises DataNotFoundError without a network request.Raised when JSON parsing or validation fails. Context includes:
reason: Description of the validation failure
- Corrupted JSON data
- Unexpected data structure
- Validation schema mismatch
Examples
fetch_multiple_async
Parameters
List of Performance tip: Group related requests together for optimal HTTP/2 multiplexing.
(year, gp, session, path) tuples to fetch in parallel. Each tuple represents a single fetch operation.Example:If
True, check cache before making network requests for each item. When the batch is larger than max_concurrent_requests, cache reads also wait for a concurrency slot.If
True, persist successful network responses to cache. Automatically disabled when ci_mode=True.Total number of tries for each request, including the first. If
None, uses global config value (default: 3).Note: Each request retries independently. A failed request does not block other requests.Request timeout in seconds per request. If
None, uses global config value (default: 30).Maximum number of concurrent network requests. If
None, uses global config value (default: 22).Tuning guide:10-20: Conservative, good for shared networks or rate-limited CDNs20-50: Balanced, good for most use cases50-100: Aggressive, good for dedicated networks and high-throughput scenarios100+: Ultra-aggressive, only for specialized scenarios (for example, telemetry prefetching withtelemetry_prefetch_max_concurrent_requests)
If
True (and write_cache is True), the batch collects telemetry payloads during the fetch. A background writer thread then writes them to the cache in one serial flush after the batch returns. The writes then do not occupy concurrency slots. tif1 waits for the writer before the process exits.Returns
List of parsed JSON dictionaries or
None for failed requests, in the same order as the input requests list.Graceful degradation: Failed requests return None and are logged as warnings. A failed request never raises; the list always has the same length as the input. Cancellation (asyncio.CancelledError) still propagates.Special case: DataNotFoundError (404) is converted to None without logging a warning. Missing data is often expected (for example, driver did not participate in session).Error Handling
Unlikefetch_json_async, this function does not raise exceptions. All errors are handled gracefully:
- NetworkError: Logged as warning, returns
Nonefor that request - DataNotFoundError (404): Silently returns
None(expected for missing data) - InvalidDataError: Logged as warning, returns
Nonefor that request - Other exceptions: Logged as warning, returns
Nonefor that request
None values.
Examples
Concurrency and Memory
- Up to
max_concurrent_requestsrequests run at the same time. The others wait for a free slot - The function returns every payload in one list, so all fetched payloads stay in memory until the caller releases the list
- The best concurrency depends on network bandwidth and CDN rate limits
fetch_with_rate_limit
Parameters
Async function (coroutine function) to execute. Must be an
async def function, not a regular function.Optional semaphore for rate limiting. If
None, the call creates its own semaphore based on the max_concurrent_requests config (default: 22). Calls that each create their own semaphore do not limit each other.Use cases:- Pass a shared semaphore to coordinate concurrency across multiple operations
- Create a custom semaphore with specific limits for fine-grained control
Returns
Raises
Any exception raised by
coro_func is propagated to the caller. No exception handling is performed by this function.Examples
This is a utility function for custom concurrency control. Most users should use
fetch_multiple_async(), which handles rate limiting automatically. Use this function only for fine-grained concurrency control or custom async workflows.When to Use
- Custom async workflows: Building specialized data fetching pipelines
- Shared concurrency limits: Coordinating multiple async operations with a single semaphore
- Fine-grained control: Need precise control over concurrency beyond what
fetch_multiple_asyncprovides - Integration: Integrating tif1 fetching with other async operations in the application
When NOT to Use
- Standard bulk fetching: Use
fetch_multiple_async()instead - Single requests: Use
fetch_json_async()directly - Simple use cases: The higher-level functions handle rate limiting automatically
Resource Management
The async fetch system manages several types of resources that need proper cleanup:- HTTP Session: Persistent connection pool for network requests
- Thread Pool Executor: Worker threads for JSON parsing and blocking operations
- Process Pool Executor: Optional worker processes for CPU-intensive JSON parsing
atexit handlers when the Python process exits. For long-running applications, or for explicit control, use the functions below.
cleanup_resources
Behavior
- Closes the HTTP session that the async fetch layer holds (the shared session, once an async fetch has run) and releases its connections
- Shuts down the thread pool executor (waits for pending tasks to complete)
- Shuts down the process pool executor if enabled (waits for pending tasks)
- Handles cleanup errors gracefully - logs failures without raising exceptions
- Safe to call multiple times (idempotent)
- Thread-safe (uses locks to prevent concurrent cleanup)
When to Call
- Application shutdown: Call before the application exits
- Test teardown: Call in test cleanup to prevent resource leaks
- Long-running processes: Call periodically when many sessions are created and destroyed
- Resource constraints: Call to release connections or memory
Examples
close_session
tif1.http_session. When no async fetch has run yet, this function does nothing; tif1.http_session.close_session() closes the shared session in that case.
When to Use
- Explicit connection management: To force connection closure
- Network changes: After network configuration changes (for example, VPN connect/disconnect)
- Testing: To reset connection state between tests
- Resource constraints: To free up connection pool resources
This only closes the HTTP session. Thread pools and process pools remain active. Use
cleanup_resources() for complete cleanup.close_executor
When to Use
- Thread pool management: To control the thread pool lifecycle
- Resource constraints: To free up thread resources
- Testing: To reset executor state between tests
This only closes the thread pool executor. HTTP session and process pool remain active. Use
cleanup_resources() for complete cleanup.Performance Characteristics
The async fetch system is optimized for:- HTTP/2 multiplexing: Single connection for multiple requests
- Connection pooling: Reuses connections across requests
- Parallel JSON parsing: Offloads JSON parsing to thread pool
- Rate limiting: Prevents overwhelming CDN with concurrent requests
- Automatic retries: Exponential backoff with jitter
Configuration
Async fetch behavior is controlled by global configuration:When
json_parse_workers is above 0, tif1 parses non-telemetry payloads in worker processes. Put the script entry point under if __name__ == "__main__":. Without it, workers started with spawn or forkserver fail, and the fetch raises NetworkError. Windows, macOS, and Linux from Python 3.14 use these start methods.Error Handling
The async fetch system uses a hierarchy of exceptions:Advanced Usage
Custom concurrency limits
Disable caching for fresh data
Disable validation for performance
Implementation Details
HTTP/2 Multiplexing
HTTP/2 Multiplexing
The async fetch system uses niquests with HTTP/2 support, allowing multiple requests to share a single TCP connection. This reduces latency for parallel requests.
JSON Parsing Strategy
JSON Parsing Strategy
JSON parsing is offloaded to a thread pool executor to avoid blocking the async event loop. A process pool is optional for non-telemetry data. The system uses
orjson for parsing and can parse multiple responses in parallel. Telemetry payloads always use thread-based parsing to avoid cross-process IPC overhead.Rate Limiting
Rate Limiting
A semaphore-based rate limiter ensures no more than
max_concurrent_requests requests are in flight simultaneously. This prevents overwhelming the CDN and triggering rate limits. The default is 22 concurrent requests, configurable via global config.Retry Logic
Retry Logic
Failed requests are retried with exponential backoff and optional jitter. The delay is
min(backoff_factor^attempt, max_delay) + random(0, jitter_max) seconds, where defaults are backoff_factor=2.0, jitter_max=0.0, and max_delay=60.0. The retry_jitter flag (default: True) switches the jitter term on. The system also includes circuit breaker logic to prevent cascading failures and special handling for connection pool exhaustion.