Skip to main content

​
Overview

The tif1 library uses a high-performance SQLite-backed cache with in-memory LRU caching to minimize network requests and dramatically improve data access speed. Caching is enabled by default and requires no configuration.

​
How Caching Works

The cache system uses a two-tier architecture:
  1. In-Memory LRU Cache: Fast access to recently used data
    • Laps and session data: 1,024 items (configurable)
    • Telemetry data: 2,048 items (configurable)
  2. SQLite Persistent Cache: Disk-based storage for all fetched data
    • Uses WAL (Write-Ahead Logging) mode for better concurrency
    • Automatically compresses data with gzip
    • Stores data at ~/.cache/tif1/ (Linux), ~/Library/Caches/tif1/ (macOS), or %LOCALAPPDATA%/Temp/tif1 (Windows)

​
Cache Location

Get the cache directory location: 
import tif1

cache = tif1.get_cache()
print(f"Cache location: {cache.cache_dir}")

# Example output:
# Cache location: /home/user/.cache/tif1

​
Cache Benefits

Caching provides significant performance improvements: 
import tif1
import time

cache = tif1.get_cache()
cache.clear()  # Start with empty cache

# First load (cold cache)
start = time.time()
session = tif1.get_session(2025, "Abu Dhabi Grand Prix", "Practice 1")
laps = session.laps
first_load_time = time.time() - start
print(f"First load (cold cache): {first_load_time:.2f}s")

# Second load (warm cache)
start = time.time()
session2 = tif1.get_session(2025, "Abu Dhabi Grand Prix", "Practice 1")
laps2 = session2.laps
cached_load_time = time.time() - start
print(f"Second load (warm cache): {cached_load_time:.2f}s")

speedup = first_load_time / cached_load_time
print(f"Speedup: {speedup:.1f}x faster from cache")

# Typical output:
# First load (cold cache): 2.45s
# Second load (warm cache): 0.12s
# Speedup: 20.4x faster from cache

​
Checking Cache Status

Inspect cache size and contents: 
import tif1
from pathlib import Path

cache = tif1.get_cache()

# Count cached files
cache_files = list(cache.cache_dir.glob("*.json.gz"))
print(f"Cached files: {len(cache_files)}")

if cache_files:
    # Calculate total size
    total_size = sum(f.stat().st_size for f in cache_files)
    print(f"Total size: {total_size / 1024 / 1024:.2f} MB")
    print(f"Average file size: {total_size / len(cache_files) / 1024:.2f} KB")
else:
    print("Cache is empty")

# Check SQLite database
db_path = cache.cache_dir / "cache.sqlite"
if db_path.exists():
    db_size = db_path.stat().st_size
    print(f"SQLite database size: {db_size / 1024 / 1024:.2f} MB")

​
Disabling Cache

Disable caching for specific sessions: 
import tif1

# Load session without cache
session = tif1.get_session(
    2025, 
    "Abu Dhabi Grand Prix", 
    "Practice 1",
    enable_cache=False
)

laps = session.laps  # Fetched directly, not cached
Disable caching globally via environment variable: 
export TIF1_ENABLE_CACHE=false
python your_script.py
Or via configuration file: 
{
  "enable_cache": false
}

​
Clearing Cache

Clear all cached data: 
import tif1

cache = tif1.get_cache()
cache.clear()
print("Cache cleared!")

# Verify cache is empty
cache_files = list(cache.cache_dir.glob("*.json.gz"))
print(f"Cached files after clear: {len(cache_files)}")
Clear cache from command line: 
tif1 cache clear

​
Cache Management Best Practices

​
When to Clear Cache

  1. Testing new features: Clear cache to ensure fresh data
  2. Data updates: If you know F1 data has been updated
  3. Disk space: Free up storage when needed
  4. Debugging: Eliminate cache as a variable

​
When to Disable Cache

  1. One-time queries: For scripts that run once and exit
  2. Testing: When you want to ensure fresh data every time
  3. Limited disk space: When persistent storage isn’t available
  4. CI/CD pipelines: Depending on your caching strategy

​
Optimal Cache Usage

import tif1

# Good: Enable cache for repeated analyses
def analyze_multiple_sessions():
    sessions = [
        (2025, "Monaco Grand Prix", "Qualifying"),
        (2025, "Monaco Grand Prix", "Race"),
        (2025, "British Grand Prix", "Qualifying"),
    ]
    
    for year, event, session_type in sessions:
        session = tif1.get_session(year, event, session_type)
        # Analysis code here
        # Subsequent runs will be much faster!

# Good: Disable cache for one-off scripts
def quick_check():
    session = tif1.get_session(
        2025, 
        "Monaco Grand Prix", 
        "Race",
        enable_cache=False  # Won't pollute cache
    )
    print(f"Laps: {len(session.laps)}")

​
Custom Cache Directory

Change cache location via environment variable: 
export TIF1_CACHE_DIR="/custom/path/to/cache"
python your_script.py
Or via configuration file: 
{
  "cache_dir": "/custom/path/to/cache"
}
Or at runtime: 
from tif1.config import get_config

config = get_config()
config.set("cache_dir", "/custom/path/to/cache")

# New cache instance will use custom directory
import tif1
cache = tif1.get_cache()
print(f"Cache location: {cache.cache_dir}")

​
Cache Configuration

Configure cache behavior via .tif1rc file: 
{
  "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
}
Configuration options:
  • cache_dir: Cache directory path
  • enable_cache: Enable/disable caching globally
  • cache_commit_interval: SQLite commit frequency (number of writes)
  • sqlite_timeout: SQLite lock timeout in seconds
  • memory_cache_max_items: Max items in memory cache for laps/sessions
  • memory_telemetry_cache_max_items: Max items in memory cache for telemetry

​
Cache Performance Tuning

For advanced users, tune cache performance: 
# Increase memory cache size for large analyses
export TIF1_MEMORY_CACHE_MAX_ITEMS=4096
export TIF1_MEMORY_TELEMETRY_CACHE_MAX_ITEMS=8192

# Adjust commit interval for write-heavy workloads
export TIF1_CACHE_COMMIT_INTERVAL=50

# Increase timeout for slow disk I/O
export TIF1_SQLITE_TIMEOUT=60.0

​
Offline Mode

Use cached data exclusively without network requests: 
from tif1.config import get_config

# Enable offline mode
config = get_config()
config.set("offline_mode", True)

import tif1

# Only cached data will be accessible
# New data requests will fail
session = tif1.get_session(2025, "Monaco Grand Prix", "Race")
Or via environment variable: 
export TIF1_OFFLINE_MODE=true
python your_script.py

​
Complete Cache Management Example

import tif1
import time
from pathlib import Path

print("CACHE MANAGEMENT DEMO")
print("=" * 60)

# 1. Get cache instance
cache = tif1.get_cache()
print(f"\nCache location: {cache.cache_dir}")

# 2. Check initial cache status
cache_files = list(cache.cache_dir.glob("*.json.gz"))
print(f"\nCached files (before): {len(cache_files)}")

# 3. Load data (will be cached)
print("\nLoading session...")
start = time.time()
session = tif1.get_session(2025, "Abu Dhabi Grand Prix", "Practice 1")
laps = session.laps
first_time = time.time() - start
print(f"First load: {first_time:.2f}s ({len(laps)} laps)")

# 4. Load again (from cache)
start = time.time()
session2 = tif1.get_session(2025, "Abu Dhabi Grand Prix", "Practice 1")
laps2 = session2.laps
cached_time = time.time() - start
print(f"Cached load: {cached_time:.2f}s")
print(f"Speedup: {first_time / cached_time:.1f}x")

# 5. Check cache size
cache_files = list(cache.cache_dir.glob("*.json.gz"))
total_size = sum(f.stat().st_size for f in cache_files)
print(f"\nCached files (after): {len(cache_files)}")
print(f"Total size: {total_size / 1024 / 1024:.2f} MB")

# 6. Clear cache
print("\nClearing cache...")
cache.clear()
cache_files = list(cache.cache_dir.glob("*.json.gz"))
print(f"Cached files (after clear): {len(cache_files)}")

​
Next Steps