Configuration

Configuration management for tif1 with file and environment variable support

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:

1. Default values
2. Configuration file (.tif1rc)
3. Environment variables (highest priority)

Functions

get_config()

def get_config() -> Config

Returns the global configuration instance (singleton pattern).

Returns:

• 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."""

The Config class is a singleton. Always use get_config() instead of instantiating directly.

Methods

get()

def get(key: str, default: Any = None) -> Any

Get configuration value with validation.

Parameters:

• key (str): Configuration key to retrieve
• default (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

Set configuration value at runtime.

Parameters:

• key (str): Configuration key to set
• value (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

Save current configuration to a JSON file.

Parameters:

• 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

Performance Settings

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:

1. Explicit path: Set via TIF1_CONFIG_FILE environment variable
2. Current directory: ./tif1rc (requires TIF1_TRUST_CWD_CONFIG=true)
3. Home directory: ~/.tif1rc (default)

File Format

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

See the full list in the source code (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.