Documentation Index
Fetch the complete documentation index at: https://mintlify.com/TracingInsights/tif1/llms.txt
Use this file to discover all available pages before exploring further.
Overview
tif1 uses a singleton configuration system that supports:
- Default configuration values
- JSON configuration files (
.tif1rc)
- Environment variable overrides
Configuration is loaded in this priority order:
- Default values
- Configuration file (
.tif1rc)
- Environment variables (highest priority)
Functions
get_config()
def get_config() -> Config
Config: Global configuration manager instance
Example:
import tif1
config = tif1.get_config()
print(config.get('cache_dir'))
Config Class
Constructor
class Config:
"""Configuration manager with file support."""
get_config() instead of instantiating directly.
Methods
get()
def get(key: str, default: Any = None) -> Any
key (str): Configuration key to retrievedefault (Any, optional): Default value if key not found
Returns:
Any: Configuration value (validated) or default
Example:
config = tif1.get_config()
timeout = config.get('timeout', 30)
max_retries = config.get('max_retries', 3)
set()
def set(key: str, value: Any) -> None
key (str): Configuration key to setvalue (Any): Value to set
Example:
config = tif1.get_config()
config.set('timeout', 60)
config.set('max_retries', 5)
save()
def save(path: Path | None = None) -> None
path (Path, optional): File path to save to. Defaults to ~/.tif1rc
Example:
from pathlib import Path
config = tif1.get_config()
config.set('timeout', 60)
config.save() # Saves to ~/.tif1rc
# Or save to custom location:
config.save(Path('~/my-project/.tif1rc'))
Configuration Options
Cache Settings
| Option | Type | Default | Description |
|---|
cache_dir | str | ~/.tif1/cache | Directory for cache storage |
enable_cache | bool | True | Enable/disable caching |
cache_commit_interval | int | 25 | Number of writes before SQLite commit |
sqlite_timeout | float | 30.0 | SQLite connection timeout in seconds |
memory_cache_max_items | int | 1024 | Max items in memory cache |
memory_telemetry_cache_max_items | int | 2048 | Max telemetry items in memory cache |
Logging
| Option | Type | Default | Description |
|---|
log_level | str | "WARNING" | Logging level (DEBUG, INFO, WARNING, ERROR) |
HTTP/Network Settings
| Option | Type | Default | Description |
|---|
timeout | int | 30 | HTTP request timeout in seconds |
max_retries | int | 3 | Maximum number of retry attempts |
retry_backoff_factor | float | 2.0 | Exponential backoff factor for retries |
retry_jitter | bool | True | Add random jitter to retry delays |
retry_jitter_max | float | 0.0 | Maximum jitter value in seconds |
max_retry_delay | float | 60.0 | Maximum retry delay in seconds |
http2_max_connections | int | 10 | Max HTTP/2 connections |
http2_max_pool_size | int | 20 | Max HTTP/2 connection pool size |
max_concurrent_requests | int | 20 | Max concurrent HTTP requests |
keepalive_timeout | int | 120 | Keep-alive timeout in seconds |
keepalive_max_requests | int | 1000 | Max requests per keep-alive connection |
http_multiplexed | bool | True | Enable HTTP/2 multiplexing |
http_disable_http3 | bool | False | Disable HTTP/3 support |
http_resolvers | list[str] | ["standard", "doh://cloudflare", "doh://google"] | DNS resolver list |
Circuit Breaker
| Option | Type | Default | Description |
|---|
circuit_breaker_threshold | int | 5 | Failures before opening circuit |
circuit_breaker_timeout | int | 60 | Circuit breaker timeout in seconds |
| Option | Type | Default | Description |
|---|
max_workers | int | 20 | Max worker threads |
json_parse_workers | int | 0 | Workers for JSON parsing (0=disabled) |
pool_exhaustion_backoff_base | float | 0.01 | Base backoff for pool exhaustion |
pool_exhaustion_backoff_max | float | 0.5 | Max backoff for pool exhaustion |
pool_exhaustion_backoff_jitter | float | 0.01 | Jitter for pool exhaustion backoff |
Data Library Settings
| Option | Type | Default | Description |
|---|
lib | str | "pandas" | Data library backend: “pandas” or “polars” |
polars_lap_categorical | bool | False | Use categorical types for laps in polars |
CDN Settings
| Option | Type | Default | Description |
|---|
cdns | list[str] | ["https://cdn.jsdelivr.net/gh/TracingInsights"] | CDN URLs for data |
cdn_use_minification | bool | False | Use minified CDN data |
user_agent | str | "tif1/0.1.0" | HTTP User-Agent header |
Validation
| Option | Type | Default | Description |
|---|
validate_data | bool | False | Enable data validation |
validate_lap_times | bool | False | Validate lap time data |
validate_telemetry | bool | False | Validate telemetry data |
Special Modes
| Option | Type | Default | Description |
|---|
offline_mode | bool | False | Work offline using only cached data |
ci_mode | bool | False | CI/CD mode optimizations |
ultra_cold_start | bool | True | Optimize for cold start performance |
ultra_cold_background_cache_fill | bool | False | Fill cache in background on cold start |
ultra_cold_skip_retries | bool | True | Skip retries during ultra cold start |
Prefetching
| Option | Type | Default | Description |
|---|
prefetch_driver_laps_on_get_driver | bool | True | Prefetch laps when getting driver |
prefetch_all_telemetry_on_first_lap_request | bool | False | Prefetch all telemetry on first lap |
prefetch_all_telemetry_after_laps_load | bool | False | Prefetch all telemetry after loading laps |
telemetry_prefetch_max_concurrent_requests | int | 32 | Max concurrent telemetry prefetch requests |
Configuration File
File Locations
Configuration is loaded from .tif1rc files in this order:
- Explicit path: Set via
TIF1_CONFIG_FILE environment variable
- Current directory:
./tif1rc (requires TIF1_TRUST_CWD_CONFIG=true)
- Home directory:
~/.tif1rc (default)
The .tif1rc file uses JSON format:
{
"cache_dir": "~/my-project/.cache",
"timeout": 60,
"max_retries": 5,
"log_level": "INFO",
"lib": "polars",
"enable_cache": true
}
Environment Variables
All configuration options can be overridden with environment variables using the TIF1_ prefix:
| Environment Variable | Config Key |
|---|
TIF1_CACHE_DIR | cache_dir |
TIF1_LOG_LEVEL | log_level |
TIF1_TIMEOUT | timeout |
TIF1_MAX_RETRIES | max_retries |
TIF1_ENABLE_CACHE | enable_cache |
TIF1_OFFLINE_MODE | offline_mode |
TIF1_CI_MODE | ci_mode |
TIF1_LIB | lib |
TIF1_HTTP_MULTIPLEXED | http_multiplexed |
config.py:136-199).
Example:
export TIF1_CACHE_DIR="~/my-cache"
export TIF1_TIMEOUT=60
export TIF1_LOG_LEVEL="DEBUG"
python my_script.py
Examples
Basic Configuration
import tif1
# Get configuration
config = tif1.get_config()
# Read values
print(f"Cache dir: {config.get('cache_dir')}")
print(f"Timeout: {config.get('timeout')}")
print(f"Backend: {config.get('lib')}")
Modify Configuration
import tif1
config = tif1.get_config()
# Change settings at runtime
config.set('timeout', 120)
config.set('max_retries', 10)
config.set('lib', 'polars')
# Save to file
config.save() # Saves to ~/.tif1rc
Use Custom Cache Directory
import tif1
config = tif1.get_config()
config.set('cache_dir', '~/my-project/.tif1-cache')
# Or via environment variable:
# export TIF1_CACHE_DIR="~/my-project/.tif1-cache"
Switch to Polars Backend
import tif1
config = tif1.get_config()
config.set('lib', 'polars')
# Now all data operations will use polars DataFrames
session = tif1.get_session(2024, 'Monaco', 'R')
session.load()
print(type(session.laps)) # polars DataFrame
Disable Caching
import tif1
config = tif1.get_config()
config.set('enable_cache', False)
# All requests will bypass cache
Offline Mode
import tif1
config = tif1.get_config()
config.set('offline_mode', True)
# Only cached data will be used, no network requests
Source Code
For the complete implementation, see config.py:25-312 in the source code.