Configuration

Configure tif1 using .tif1rc files, environment variables, or runtime settings

Overview

The tif1 library provides flexible configuration through three mechanisms:

1. Configuration file (.tif1rc)
2. Environment variables (TIF1_*)
3. Runtime configuration (programmatic)

Configuration sources are loaded in this priority order (highest to lowest):

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

Configuration File

Create a .tif1rc file in your home directory:

{
  "cache_dir": "~/.tif1/cache",
  "enable_cache": true,
  "log_level": "INFO",
  "timeout": 30,
  "max_retries": 3,
  "lib": "pandas"
}

File Locations

The library searches for .tif1rc in this order:

1. Path specified in TIF1_CONFIG_FILE environment variable
2. Current working directory (only if TIF1_TRUST_CWD_CONFIG=true)
3. Home directory (~/.tif1rc)

# Use custom config file location
export TIF1_CONFIG_FILE="/path/to/custom/.tif1rc"

# Trust config file in current directory (security consideration)
export TIF1_TRUST_CWD_CONFIG=true

Environment Variables

All configuration options can be set via environment variables:

# Cache settings
export TIF1_CACHE_DIR="/custom/cache/path"
export TIF1_ENABLE_CACHE=true

# Network settings
export TIF1_TIMEOUT=30
export TIF1_MAX_RETRIES=3
export TIF1_MAX_CONCURRENT_REQUESTS=20

# Backend selection
export TIF1_LIB=polars

# Logging
export TIF1_LOG_LEVEL=INFO

Runtime Configuration

Modify configuration programmatically:

from tif1.config import get_config

config = get_config()

# Set values
config.set("cache_dir", "/custom/path")
config.set("lib", "polars")
config.set("timeout", 60)

# Get values
cache_dir = config.get("cache_dir")
print(f"Cache directory: {cache_dir}")

# Save configuration to file
from pathlib import Path
config.save(Path("~/.tif1rc"))

Configuration Options

Cache Settings

Option	Type	Default	Description
cache_dir	string	~/.cache/tif1	Cache directory path
enable_cache	boolean	true	Enable/disable caching
cache_commit_interval	integer	25	SQLite commit frequency
sqlite_timeout	float	30.0	SQLite lock timeout (seconds)
memory_cache_max_items	integer	1024	Max memory cache items (laps/sessions)
memory_telemetry_cache_max_items	integer	2048	Max memory cache items (telemetry)

{
  "cache_dir": "~/.tif1/cache",
  "enable_cache": true,
  "cache_commit_interval": 25,
  "sqlite_timeout": 30.0,
  "memory_cache_max_items": 1024,
  "memory_telemetry_cache_max_items": 2048
}

Network Settings

Option	Type	Default	Description
timeout	integer	30	HTTP request timeout (seconds)
max_retries	integer	3	Maximum retry attempts
retry_backoff_factor	float	2.0	Exponential backoff factor
retry_jitter	boolean	true	Add jitter to retries
max_retry_delay	float	60.0	Maximum retry delay (seconds)
max_concurrent_requests	integer	20	Max parallel requests
http2_max_connections	integer	10	Max HTTP/2 connections
http2_max_pool_size	integer	20	HTTP/2 connection pool size
http_multiplexed	boolean	true	Enable HTTP/2 multiplexing
http_disable_http3	boolean	false	Disable HTTP/3

{
  "timeout": 30,
  "max_retries": 3,
  "retry_backoff_factor": 2.0,
  "max_concurrent_requests": 20
}

Circuit Breaker Settings

Option	Type	Default	Description
circuit_breaker_threshold	integer	5	Failures before opening circuit
circuit_breaker_timeout	integer	60	Circuit reset timeout (seconds)

{
  "circuit_breaker_threshold": 5,
  "circuit_breaker_timeout": 60
}

Backend Settings

Option	Type	Default	Description
lib	string	"pandas"	Backend library (pandas or polars)
polars_lap_categorical	boolean	false	Use categorical types in Polars

{
  "lib": "polars",
  "polars_lap_categorical": false
}

Logging Settings

Option	Type	Default	Description
log_level	string	"WARNING"	Log level (DEBUG, INFO, WARNING, ERROR)

{
  "log_level": "INFO"
}

Validation Settings

Option	Type	Default	Description
validate_data	boolean	false	Enable data validation
validate_lap_times	boolean	false	Enable lap time validation
validate_telemetry	boolean	false	Enable telemetry validation

{
  "validate_data": true,
  "validate_lap_times": true,
  "validate_telemetry": true
}

Performance Settings

Option	Type	Default	Description
max_workers	integer	20	Thread pool size
json_parse_workers	integer	0	Process pool for JSON parsing (0=disabled)
ultra_cold_start	boolean	true	Optimize for cold cache startup
prefetch_driver_laps_on_get_driver	boolean	true	Prefetch driver laps
telemetry_prefetch_max_concurrent_requests	integer	32	Max concurrent telemetry requests

{
  "max_workers": 20,
  "ultra_cold_start": true,
  "prefetch_driver_laps_on_get_driver": true
}

CDN Settings

Option	Type	Default	Description
cdns	array	["https://cdn.jsdelivr.net/gh/TracingInsights"]	CDN base URLs
cdn_use_minification	boolean	false	Use minified JSON

{
  "cdns": [
    "https://cdn.jsdelivr.net/gh/TracingInsights"
  ],
  "cdn_use_minification": false
}

Special Modes

Option	Type	Default	Description
offline_mode	boolean	false	Use cache only, no network
ci_mode	boolean	false	CI/CD optimizations

{
  "offline_mode": false,
  "ci_mode": false
}

Complete Configuration Example

Here’s a complete .tif1rc file with common settings:

{
  "cache_dir": "~/.tif1/cache",
  "enable_cache": true,
  "log_level": "INFO",
  "timeout": 30,
  "max_retries": 3,
  "retry_backoff_factor": 2.0,
  "max_concurrent_requests": 20,
  "lib": "pandas",
  "circuit_breaker_threshold": 5,
  "circuit_breaker_timeout": 60,
  "validate_data": false,
  "ultra_cold_start": true,
  "prefetch_driver_laps_on_get_driver": true
}

Environment Variables Example

#!/bin/bash

# Cache configuration
export TIF1_CACHE_DIR="~/.tif1/cache"
export TIF1_ENABLE_CACHE=true

# Network configuration
export TIF1_TIMEOUT=30
export TIF1_MAX_RETRIES=3
export TIF1_MAX_CONCURRENT_REQUESTS=20

# Backend configuration
export TIF1_LIB=polars

# Logging
export TIF1_LOG_LEVEL=INFO

# Performance
export TIF1_ULTRA_COLD_START=true
export TIF1_PREFETCH_DRIVER_LAPS_ON_GET_DRIVER=true

# Run your script
python your_analysis.py

Runtime Configuration Example

import tif1
from tif1.config import get_config

# Get configuration instance
config = get_config()

# View current settings
print(f"Cache dir: {config.get('cache_dir')}")
print(f"Backend: {config.get('lib')}")
print(f"Timeout: {config.get('timeout')}")

# Modify settings
config.set("lib", "polars")
config.set("max_concurrent_requests", 32)
config.set("log_level", "DEBUG")

# Enable validation for debugging
config.set("validate_data", True)
config.set("validate_lap_times", True)

# Use custom cache directory
config.set("cache_dir", "/mnt/fast-ssd/tif1-cache")

# Save to file for future use
from pathlib import Path
config.save(Path("~/.tif1rc").expanduser())
print("Configuration saved!")

# Now use tif1 with new settings
session = tif1.get_session(2025, "Monaco Grand Prix", "Race")

Configuration Best Practices

Development

{
  "log_level": "DEBUG",
  "validate_data": true,
  "validate_lap_times": true,
  "validate_telemetry": true,
  "enable_cache": true
}

Production

{
  "log_level": "WARNING",
  "validate_data": false,
  "enable_cache": true,
  "max_concurrent_requests": 32,
  "ultra_cold_start": true
}

CI/CD

{
  "ci_mode": true,
  "enable_cache": false,
  "timeout": 60,
  "max_retries": 5,
  "log_level": "INFO"
}

Offline Analysis

{
  "offline_mode": true,
  "enable_cache": true,
  "log_level": "INFO"
}

Next Steps

• Learn about caching to optimize performance
• Explore backends for choosing pandas vs polars
• Understand error handling for configuration errors