FastF1 Compatibility Layer

The fastf1_compat module provides a compatibility layer for applications migrating from fastf1 to tif1. This module maintains API compatibility while using tif1 performance optimizations, including async data fetching, HTTP/2 multiplexing, and caching strategies.

For new projects: Use the native tif1 API directly for the best experience. This compatibility layer is specifically designed to ease migration from existing fastf1 codebases with minimal code changes.

Performance benefit: While maintaining API compatibility, tif1 delivers significant performance improvements:

Faster cold starts (first-time data loads) through lazy, file-level fetching
Fast warm starts (cached data) through the memory and SQLite cache tiers
Async-first architecture for parallel data fetching
HTTP/2 multiplexing for efficient network usage
SQLite-backed caching with in-memory LRU layer

Cache Management

The Cache class provides fastf1-compatible cache management with improved performance through a multi-layer caching strategy. tif1 uses a caching system that combines in-memory LRU caches with SQLite persistence. This structure gives faster data access than the fastf1 HTTP cache approach.

Architecture Overview

tif1’s caching system consists of three layers:

In-Memory LRU Cache: Lock-free reads for frequently accessed data (configurable size, default 1024 items)
Telemetry-Specific Cache: Dedicated in-memory cache for telemetry data (default 2048 items)
SQLite Persistence: WAL-mode SQLite database for durable storage with optimized concurrency

This multi-layer approach ensures that hot data is served from memory while maintaining persistence across sessions.

`Cache.enable_cache`

@staticmethod
def enable_cache(
    cache_dir: str | Path | None = None,
    ignore_version: bool = True,
    force_renew: bool = False,
    use_requests_cache: bool = True
) -> Cache

Enable caching with fastf1-compatible API. This method initializes tif1’s caching system and configures the cache directory. Once enabled, all data fetched through tif1 will be automatically cached for faster subsequent access.

Parameters

Parameter	Type	Default	Description
`cache_dir`	`str \| Path \| None`	`None`	Directory path for cache storage. If `None`, uses the configured cache directory (default: Windows `%LOCALAPPDATA%/Temp/tif1`; macOS `~/Library/Caches/tif1`; Linux/other POSIX `~/.cache/tif1` when `~/.cache` exists, otherwise `~/.tif1`)
`ignore_version`	`bool`	`True`	Compatibility parameter - Ignored by tif1. tif1 handles cache versioning automatically through content-based keys
`force_renew`	`bool`	`False`	If `True`, clears all existing cache data after enabling. Use `Cache.clear_cache()` for more control
`use_requests_cache`	`bool`	`True`	Compatibility parameter - Ignored by tif1. tif1 uses SQLite-backed caching instead of requests-cache

Returns

Cache: The configured global tif1 cache instance

Behavior Details

When enable_cache() is called:

Directory Creation: Creates the cache directory if it does not exist, with restricted permissions (0o700 on Unix-like systems)
SQLite Initialization: Sets up the SQLite database with WAL (Write-Ahead Logging) mode for better concurrency
Configuration Update: Updates the global tif1 configuration to enable caching
Instance Reset: Closes any existing cache instance and creates a fresh one
Optional Clear: If force_renew=True, clears all cached data

Cache Directory Resolution

The cache directory is resolved in the following order of precedence:

Explicit cache_dir parameter
TIF1_CACHE_DIR environment variable
Configuration file setting (~/.tif1rc)
Platform-specific default:
- Windows: %LOCALAPPDATA%/Temp/tif1
- macOS: ~/Library/Caches/tif1
- Linux/other POSIX: ~/.cache/tif1 (or ~/.tif1 if ~/.cache does not exist)

Examples

Basic usage with default location:

import tif1

# Enable cache with platform-specific default directory
tif1.Cache.enable_cache()

# Now all data fetching will be cached
session = tif1.get_session(2024, "Monaco", "Q")
session.load()  # Data is fetched and cached

Custom cache directory:

import tif1
from pathlib import Path

# Use a project-specific cache directory
cache_path = Path("./project_cache")
tif1.Cache.enable_cache(cache_dir=cache_path)

# Cache will be stored in ./project_cache/cache.sqlite

Enable cache and clear existing data:

import tif1

# Start fresh - clear any existing cached data
tif1.Cache.enable_cache(cache_dir="./cache", force_renew=True)

Environment variable configuration:

# Set cache directory via environment variable
export TIF1_CACHE_DIR="/mnt/fast-ssd/f1-cache"

import tif1

# Will use /mnt/fast-ssd/f1-cache automatically
tif1.Cache.enable_cache()

Migration from fastf1

The API is identical, so migration needs few changes:

# fastf1 code
import fastf1
fastf1.Cache.enable_cache("./cache")

# tif1 equivalent (identical call)
import tif1
tif1.Cache.enable_cache("./cache")

Performance Considerations

First call overhead: The first enable_cache() call creates the SQLite database and initializes tables (~10-50ms)
Subsequent calls: Reusing an existing cache directory is nearly instant
Memory usage: In-memory caches use approximately 50-100 bytes per cached item
Disk usage: SQLite database grows with cached data; typical session data is 1-5 MB

Thread Safety

enable_cache() is thread-safe and can be called from multiple threads. However, it is recommended to call it once during application initialization to avoid unnecessary overhead.

`Cache.clear_cache`

@staticmethod
def clear_cache(
    cache_dir: str | Path | None = None,
    deep: bool = False
) -> None

Clear cached data from the specified cache directory. This method removes all cached session data, lap times, telemetry, and other stored information. Use this method to force fresh data fetches or to troubleshoot cache-related issues.

Parameters

Parameter	Type	Default	Description
`cache_dir`	`str \| Path \| None`	`None`	Optional cache directory path. If `None`, clears the currently active cache directory
`deep`	`bool`	`False`	If `True`, also removes legacy FastF1 HTTP cache database files (`fastf1_http_cache.sqlite*`) for complete cleanup

Behavior Details

The clearing process works as follows:

Active Cache Detection: If cache_dir is None, uses the now active cache instance
Directory Validation: Verifies the cache directory exists and is a valid directory
SQLite Clearing: Executes DELETE statements on all cache tables
Memory Cache Flush: Clears in-memory LRU caches
Legacy Cleanup (if deep=True): Removes FastF1 HTTP cache files for users migrating from fastf1

Cache Tables Cleared

cache table: General session data, lap times, race control messages, weather data
telemetry_cache table: Telemetry data indexed by (year, GP, session, driver, lap)
In-memory caches: Both general and telemetry-specific LRU caches

Examples

Clear the active cache:

import tif1

# Enable cache
tif1.Cache.enable_cache("./cache")

# ... use tif1 to fetch data ...

# Clear all cached data
tif1.Cache.clear_cache()

# Next data fetch will retrieve fresh data from CDN

Clear a specific cache directory:

import tif1

# Clear cache in a specific directory without activating it
tif1.Cache.clear_cache(cache_dir="./old_cache")

Deep clean (remove legacy FastF1 files):

import tif1

# Migrating from fastf1? Remove old HTTP cache files too
tif1.Cache.clear_cache(cache_dir="./cache", deep=True)

Clear cache before important race weekend:

import tif1

# Ensure fresh data for the latest race
tif1.Cache.enable_cache()
tif1.Cache.clear_cache()

# Fetch latest data
session = tif1.get_session(2024, "Abu Dhabi", "R")
session.load()

Migration from fastf1

The basic API is identical:

# fastf1 code
import fastf1
fastf1.Cache.clear_cache()

# tif1 equivalent (identical)
import tif1
tif1.Cache.clear_cache()

Error Handling

NotADirectoryError: Raised if the specified cache_dir exists but is not a directory
OSError: May be raised if file permissions prevent deletion (logged as warning for legacy files)

Performance Impact

Clearing time: Typically 10-100ms depending on cache size
Disk I/O: Minimal - SQLite DELETE operations are fast with WAL mode
Memory: In-memory caches are cleared instantly

When to Clear Cache

Consider clearing the cache in these scenarios:

Data corruption: When cached data is suspect or invalid
Schema changes: After updating tif1 to a version with data format changes
Disk space: When cache directory grows too large
Testing: To ensure tests fetch fresh data
Season updates: At the start of a new F1 season to remove old data

Thread Safety

clear_cache() is thread-safe but should not be called concurrently with data fetching operations, as this may lead to inconsistent cache states.

Logging Functions

`set_log_level`

def set_log_level(level: int = logging.WARNING) -> None

Set the logging level for tif1 logger. Parameters:

level: Python logging level (for example, logging.DEBUG, logging.INFO, logging.WARNING)

Example:

import logging
import tif1

# Enable debug logging
tif1.set_log_level(logging.DEBUG)

# Disable most logging
tif1.set_log_level(logging.ERROR)

Migration from fastf1:

# fastf1 code
import fastf1
import logging
fastf1.set_log_level(logging.DEBUG)

# tif1 equivalent (identical)
import tif1
import logging
tif1.set_log_level(logging.DEBUG)

Complete migration example

Here’s a complete example showing how to migrate a fastf1 script to tif1: Original fastf1 code:

import fastf1
import logging

# Setup
fastf1.Cache.enable_cache("./cache")
fastf1.set_log_level(logging.INFO)

# Load session
session = fastf1.get_session(2024, "Monaco", "Q")
session.load()

# Get driver
ver = session.get_driver("VER")
fastest = ver.pick_fastest()

# Get telemetry
tel = fastest.get_telemetry()
print(f"Max speed: {tel['Speed'].max()}")

Migrated tif1 code (minimal changes):

import tif1
import logging

# Setup (identical API)
tif1.Cache.enable_cache("./cache")
tif1.set_log_level(logging.INFO)

# Load session (identical API)
session = tif1.get_session(2024, "Monaco", "Q")
session.load()

# Get driver (identical API)
ver = session.get_driver("VER")
fastest = ver.pick_fastest()

# Get telemetry (identical API)
tel = fastest.get_telemetry()
print(f"Max speed: {tel['Speed'].max()}")

API Differences

While tif1 maintains API compatibility, there are some differences to be aware of:

Supported Features

Feature	fastf1	tif1	Notes
`Cache.enable_cache()`	✅	✅	Identical API
`Cache.clear_cache()`	✅	✅	Identical API
`set_log_level()`	✅	✅	Identical API
`get_session()`	✅	✅	Identical API
`Session.load()`	✅	✅	Identical API
`Session.laps`	✅	✅	Identical API
`Session.get_driver()`	✅	✅	Identical API
`Driver.laps`	✅	✅	Identical API
`Lap.get_telemetry()`	✅	✅	Identical API

Ignored Parameters

Some fastf1 parameters are ignored in tif1 because they are handled automatically:

Cache.enable_cache(ignore_version): tif1 handles versioning automatically
Cache.enable_cache(force_renew): Use Cache.clear_cache() instead
Cache.enable_cache(use_requests_cache): tif1 uses SQLite cache

Performance Improvements

tif1 provides significant performance improvements while maintaining API compatibility:

Async loading: session.laps_async() for parallel data fetching
Ultra-cold start: Minimal latency for first-time loads
HTTP/2 multiplexing: Faster parallel requests
Optimized caching: SQLite-backed multi-layer cache

Compatibility Checklist

When migrating from fastf1 to tif1:

Replace import fastf1 with import tif1
Update Cache.enable_cache() calls (API is identical)
Update set_log_level() calls (API is identical)
Test that get_session() works with the year/GP/session combinations in use
Verify DataFrame column names match (tif1 uses fastf1 naming conventions)
Consider using async methods (laps_async(), get_fastest_laps_tels_async()) for better performance
Update any custom caching logic (tif1 handles caching automatically)

Known Limitations

The following fastf1 features are not yet supported in tif1:

Ergast API integration: tif1 uses TracingInsights CDN exclusively
Live timing: tif1 focuses on historical data
Custom data sources: tif1 uses a fixed CDN structure

When these features are needed, continue using fastf1 or open an issue on the tif1 GitHub repository.

Getting Help

When issues occur during migration from fastf1:

Check the Migration Guide for detailed instructions
Review the FAQ for common questions
Open an issue on GitHub

Getting Started

Core API

Data Pipeline

Configuration & Cache

Visualization & Tools

Utilities & Helpers

Compatibility & Errors

FastF1 Compatibility API

FastF1 Compatibility Layer

Cache Management

Architecture Overview

`Cache.enable_cache`

Parameters

Returns

Behavior Details

Cache Directory Resolution

Examples

Migration from fastf1

Performance Considerations

Thread Safety

`Cache.clear_cache`

Parameters

Behavior Details

Cache Tables Cleared

Examples

Migration from fastf1

Error Handling

Performance Impact

When to Clear Cache

Thread Safety

Logging Functions

`set_log_level`

Complete migration example

API Differences

Supported Features

Ignored Parameters

Performance Improvements

Compatibility Checklist

Known Limitations

Getting Help

​FastF1 Compatibility Layer

​Cache Management

​Architecture Overview

​Cache.enable_cache

​Parameters

​Returns

​Behavior Details

​Cache Directory Resolution

​Examples

​Migration from fastf1

​Performance Considerations

​Thread Safety

​Cache.clear_cache

​Parameters

​Behavior Details

​Cache Tables Cleared

​Examples

​Migration from fastf1

​Error Handling

​Performance Impact

​When to Clear Cache

​Thread Safety

​Logging Functions

​set_log_level

​Complete migration example

​API Differences

​Supported Features

​Ignored Parameters

​Performance Improvements

​Compatibility Checklist

​Known Limitations

​Getting Help

FastF1 Compatibility Layer

Cache Management

Architecture Overview

`Cache.enable_cache`

Parameters

Returns

Behavior Details

Cache Directory Resolution

Examples

Migration from fastf1

Performance Considerations

Thread Safety

`Cache.clear_cache`

Parameters

Behavior Details

Cache Tables Cleared

Examples

Migration from fastf1

Error Handling

Performance Impact

When to Clear Cache

Thread Safety

Logging Functions

`set_log_level`

Complete migration example

API Differences

Supported Features

Ignored Parameters

Performance Improvements

Compatibility Checklist

Known Limitations

Getting Help