tif1 can be configured via a .tif1rc file, environment variables, or programmatically using the Config object. Configuration is loaded in this order (later sources override earlier ones):
Default values
.tif1rc file in home directory (~/.tif1rc)Environment variables (prefixed with TIF1_)
Programmatic config.set() calls
get_configdef get_config () -> Config
Returns the global singleton configuration instance.
Returns: Example: import tif1 config = tif1.get_config() print ( f "Lib: { config.get( 'lib' ) } " ) print ( f "Cache enabled: { config.get( 'enable_cache' ) } " )
Config Methods get(key, default=None)Get the value for a configuration key.
def get (key: str , default: Any = None ) -> Any
Parameters:
key: Configuration key namedefault: Default value if key doesn’t exist
Returns:
Configuration value or default
Example: config = tif1.get_config() lib = config.get( "lib" ) # "pandas" timeout = config.get( "timeout" , 30 ) # 30 if not set custom = config.get( "custom_key" , "default" ) # "default"
set(key, value)Update a configuration value in memory for the current session.
def set (key: str , value: Any) -> None
Parameters:
key: Configuration key namevalue: New value to set
Example: config = tif1.get_config() # Change lib config.set( "lib" , "polars" ) # Disable cache config.set( "enable_cache" , False ) # Increase timeout config.set( "timeout" , 60 )
Changes made with set() only affect the current Python session. Use save() to persist changes to disk.
save(path=None)Save the current configuration to a JSON file.
def save (path: Path | None = None ) -> None
Parameters:
path: Path to save config file. If None, saves to ~/.tif1rc
Example: config = tif1.get_config() # Modify settings config.set( "lib" , "polars" ) config.set( "enable_cache" , True ) # Save to default location (~/.tif1rc) config.save() # Save to custom location config.save(Path( "./my-config.json" ))
Configuration Keys Core Settings Default DataFrame lib ("pandas" or "polars"). config.set( "lib" , "polars" )
Enable or disable the multi-layer caching system (memory + SQLite). config.set( "enable_cache" , False ) # Disable caching
cache_dir
str
default: "~/.tif1/cache"
Path where the SQLite cache database is stored. config.set( "cache_dir" , "/tmp/tif1-cache" )
Enable Pydantic validation of incoming JSON data. Validation adds overhead. Disabled by default for performance.
config.set( "validate_data" , True ) # Enable validation
Enable ultra-low latency mode for first-time loads. Skips loading full session data when only specific data is needed. config.set( "ultra_cold_start" , False ) # Disable for full data loading
Network Settings Network request timeout in seconds. config.set( "timeout" , 60 ) # 60 second timeout
Number of times to retry a failed CDN request. config.set( "max_retries" , 5 )
Maximum number of concurrent workers for parallel requests. config.set( "max_workers" , 50 )
Maximum number of concurrent HTTP requests. config.set( "max_concurrent_requests" , 50 )
HTTP Session Settings Enable HTTP/2 multiplexing for multiple requests over a single connection. config.set( "http_multiplexed" , False ) # Disable multiplexing
Disable HTTP/3 support. config.set( "http_disable_http3" , True )
Number of connection pools to maintain. If not set, automatically calculated as max(256, max_workers, max_concurrent_requests, telemetry_prefetch_max_concurrent_requests). Most users should rely on automatic sizing. Only set explicitly for specific performance tuning.
config.set( "pool_connections" , 512 ) # Override automatic sizing
Maximum connections per pool. If not set, automatically calculated as max(512, pool_connections * 4) to handle burst traffic. Automatically sized to 4x pool_connections with a minimum of 512. Only override for specific use cases.
config.set( "pool_maxsize" , 2048 ) # Override automatic sizing
Keep-alive timeout in seconds. config.set( "keepalive_timeout" , 300 )
Maximum requests per keep-alive connection. config.set( "keepalive_max_requests" , 5000 )
User-Agent header for HTTP requests. config.set( "user_agent" , "my-app/1.0.0" )
DNS resolvers with DoH fallback. config.set( "http_resolvers" , [ "doh://cloudflare" ])
Telemetry Settings telemetry_prefetch_max_concurrent_requests
Maximum concurrent requests for telemetry prefetching. config.set( "telemetry_prefetch_max_concurrent_requests" , 128 )
Logging Settings connection_stats_log_interval
Interval in seconds for logging connection pool statistics. config.set( "connection_stats_log_interval" , 120.0 )
Advanced Configuration These settings are for advanced users and performance tuning. Most users should use the defaults.
Number of cache operations before committing to SQLite. config.set( "cache_commit_interval" , 50 )
Maximum items in the in-memory cache layer. config.set( "memory_cache_max_items" , 2048 )
memory_telemetry_cache_max_items
Maximum telemetry items in the in-memory cache. config.set( "memory_telemetry_cache_max_items" , 4096 )
SQLite connection timeout in seconds. config.set( "sqlite_timeout" , 60.0 )
List of CDN URLs to use for data fetching. Must be HTTPS URLs. config.set( "cdns" , [ "https://cdn.jsdelivr.net/gh/TracingInsights" ])
Use minified CDN resources (reserved for future use). config.set( "cdn_use_minification" , False )
Exponential backoff multiplier for retries. Must be >= 1.0. config.set( "retry_backoff_factor" , 3.0 )
Add random jitter to retry delays to prevent thundering herd. config.set( "retry_jitter" , True )
Maximum jitter amount in seconds. Must be > 0 to have effect. config.set( "retry_jitter_max" , 1.0 )
Maximum delay between retries in seconds. config.set( "max_retry_delay" , 120.0 )
circuit_breaker_threshold
Number of consecutive failures before circuit breaker opens. config.set( "circuit_breaker_threshold" , 10 )
Seconds to wait before attempting to close circuit breaker. config.set( "circuit_breaker_timeout" , 120 )
Maximum HTTP/2 connections per host. config.set( "http2_max_connections" , 20 )
HTTP/2 connection pool size. config.set( "http2_max_pool_size" , 40 )
Connection Pool Exhaustion
pool_exhaustion_backoff_base
Base backoff delay when connection pool is exhausted (seconds). config.set( "pool_exhaustion_backoff_base" , 0.02 )
pool_exhaustion_backoff_max
Maximum backoff delay for pool exhaustion (seconds). config.set( "pool_exhaustion_backoff_max" , 1.0 )
pool_exhaustion_backoff_jitter
Jitter amount for pool exhaustion backoff (seconds). config.set( "pool_exhaustion_backoff_jitter" , 0.02 )
Enable validation of lap time data using Pydantic schemas. config.set( "validate_lap_times" , True )
Enable validation of telemetry data using Pydantic schemas. config.set( "validate_telemetry" , True )
Enabling validation adds overhead. Only enable for debugging or data quality checks.
prefetch_driver_laps_on_get_driver
Automatically prefetch lap data when accessing a driver. config.set( "prefetch_driver_laps_on_get_driver" , False )
prefetch_all_telemetry_on_first_lap_request
Prefetch all telemetry data on first lap telemetry request. config.set( "prefetch_all_telemetry_on_first_lap_request" , True )
prefetch_all_telemetry_after_laps_load
Prefetch all telemetry data immediately after loading laps. config.set( "prefetch_all_telemetry_after_laps_load" , True )
ultra_cold_background_cache_fill
Fill cache in background during ultra cold start mode. config.set( "ultra_cold_background_cache_fill" , True )
Skip retries in ultra cold start mode for faster initial load. config.set( "ultra_cold_skip_retries" , False )
Default logging level. Use setup_logging() to change at runtime. config.set( "log_level" , "DEBUG" )
Enable offline mode (cache-only, no network requests). config.set( "offline_mode" , True )
Enable CI mode (optimized for continuous integration environments). config.set( "ci_mode" , True )
Use categorical types for string columns in polars DataFrames. config.set( "polars_lap_categorical" , True )
Number of worker processes for parallel JSON parsing. 0 disables multiprocessing. Process-pool JSON parsing can hurt performance due to IPC overhead for telemetry-heavy workloads. Keep disabled unless you have specific use cases.
config.set( "json_parse_workers" , 4 )
The .tif1rc file is a JSON file with key-value pairs:
{ "lib" : "pandas" , "enable_cache" : true , "cache_dir" : "~/.tif1/cache" , "timeout" : 60 , "max_retries" : 5 , "validate_data" : false , "ultra_cold_start" : true , "max_workers" : 50 , "pool_connections" : 512 , "pool_maxsize" : 1024 , "http_multiplexed" : true , "http_disable_http3" : false , "keepalive_timeout" : 300 , "keepalive_max_requests" : 5000 , "user_agent" : "my-app/1.0.0" , "http_resolvers" : [ "standard" , "doh://cloudflare" , "doh://google" ] }
Location:
Default: ~/.tif1rc
Custom: Specify path with TIF1_CONFIG_PATH environment variable
Environment Variables All configuration keys can be set via environment variables with the TIF1_ prefix:
# Set lib export TIF1_LIB = polars # Disable cache export TIF1_ENABLE_CACHE = false # Set timeout export TIF1_TIMEOUT = 60 # Set cache directory export TIF1_CACHE_DIR = /tmp/tif1-cache # Set max workers export TIF1_MAX_WORKERS = 50 # Enable ultra cold start export TIF1_ULTRA_COLD_START = true # Configure HTTP export TIF1_HTTP_MULTIPLEXED = true export TIF1_POOL_CONNECTIONS = 512 export TIF1_POOL_MAXSIZE = 1024 # Configure DNS resolvers (comma-separated) export TIF1_HTTP_RESOLVERS = standard,doh://cloudflare
Configuration Precedence Configuration is loaded in this order (later overrides earlier):
Default values (hardcoded in library).tif1rc file~/.tif1rc or TIF1_CONFIG_PATH)Environment variables (TIF1_*)Programmatic calls (config.set())
Example: # Default: lib = "pandas" # .tif1rc: lib = "polars" # Environment: TIF1_LIB=pandas # Programmatic: config.set("lib", "polars") # Final value: "polars" (programmatic wins)
Common configuration patterns import tif1 config = tif1.get_config() # Use polars lib config.set( "lib" , "polars" ) # Increase concurrency config.set( "max_workers" , 100 ) config.set( "max_concurrent_requests" , 100 ) config.set( "telemetry_prefetch_max_concurrent_requests" , 128 ) # Optimize connection pooling (override automatic sizing) config.set( "pool_connections" , 512 ) config.set( "pool_maxsize" , 2048 ) # Longer keep-alive config.set( "keepalive_timeout" , 300 ) config.set( "keepalive_max_requests" , 10000 )
Low-Latency Setup import tif1 config = tif1.get_config() # Enable ultra cold start config.set( "ultra_cold_start" , True ) # Use DoH for faster DNS config.set( "http_resolvers" , [ "doh://cloudflare" , "doh://google" ]) # Aggressive connection pooling config.set( "pool_connections" , 256 ) config.set( "pool_maxsize" , 1024 ) # Shorter timeout config.set( "timeout" , 15 )
Development Setup import tif1 import logging config = tif1.get_config() # Disable cache for fresh data config.set( "enable_cache" , False ) # Enable validation config.set( "validate_data" , True ) # Verbose logging tif1.setup_logging(logging. DEBUG ) # Lower concurrency for debugging config.set( "max_workers" , 5 )
Production Setup import tif1 config = tif1.get_config() # Enable cache config.set( "enable_cache" , True ) config.set( "cache_dir" , "/var/cache/tif1" ) # Disable validation for performance config.set( "validate_data" , False ) # High concurrency config.set( "max_workers" , 100 ) config.set( "max_concurrent_requests" , 100 ) # Robust retry settings config.set( "max_retries" , 5 ) config.set( "timeout" , 60 ) # Save configuration config.save()
Setting Log Level While not part of the Config object, you can set the log level using setup_logging:
import tif1 import logging # Set log level tif1.setup_logging(logging. DEBUG ) # DEBUG, INFO, WARNING, ERROR
Or use the fastf1-compatible function:
import tif1 # Set log level (fastf1 compatibility) tif1.set_log_level(logging. DEBUG )
Best Practices
Use config files for persistent settings : Store common settings in ~/.tif1rcUse environment variables for deployment : Configure per-environment settingsUse programmatic API for runtime changes : Adjust settings based on workloadSave after making changes : Call config.save() to persist changesTest configuration changes : Verify performance impact before deployingMonitor connection stats : Track connection reuse rate to optimize poolingLet pool sizing auto-calculate : Only override pool_connections and pool_maxsize for specific tuning needsKeep validation disabled in production : Enable only for debugging or data quality checks
Summary The configuration system provides:
Multiple configuration sources (file, env, API)
Clear precedence rules
Runtime configuration changes
Persistent configuration storage
Comprehensive settings for all aspects of the library
Performance tuning capabilities
Use configuration to optimize tif1 for your specific use case and environment.
Related Pages Environment Variables Env var reference
Best Practices Configuration tips
