FastF1 Compatibility Layer
Thefastf1_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
TheCache 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 (
memory_cache_max_items, default 1024 items) - Telemetry-Specific Cache: Dedicated in-memory cache for telemetry data (
memory_telemetry_cache_max_items, default 2048 items) - SQLite Persistence: WAL-mode SQLite database (
cache.sqlite) for durable storage with optimized concurrency
Cache.enable_cache
Parameters
Returns
tif1.cache.Cache: The configured global tif1 cache instance (the same object thattif1.get_cache()returns)
Behavior Details
Whenenable_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_dirparameter - The directory of an earlier
enable_cache()call in the same process TIF1_CACHE_DIRenvironment variable- Configuration file setting (
~/.tif1rc) - Platform-specific default:
- Windows:
%LOCALAPPDATA%/Temp/tif1 - macOS:
~/Library/Caches/tif1 - Linux/other POSIX:
~/.cache/tif1(or~/.tif1if~/.cachedoes not exist)
- Windows:
Examples
Basic usage with default location:Migration from fastf1
The call is the same, so migration needs few changes:cache_dir is required and ignore_version defaults to False. In tif1, cache_dir is optional and ignore_version defaults to True (it has no effect).
Performance Considerations
- First call overhead: Creating a new SQLite database and its tables takes about 10-50ms on a local disk
- Subsequent calls: Reusing an existing cache directory is nearly instant
- Disk usage:
cache.sqlitegrows with each loaded session.Cache.get_cache_info()returns the directory and its size in bytes
Thread Safety
enable_cache() closes the global cache instance and creates a new one. Call it once during application start-up, before other threads fetch data.
Cache.configure
Cache.configure() keywords, mapped onto enable_cache(). All arguments are keyword-only.
cache_dir: The cache directory. tif1 creates it when it does not exist (fastf1 requires an existing directory). Without it, tif1 uses the configured directoryforce_renew: Clear the cache after enabling itignore_version,use_requests_cache: Accepted for compatibility. tif1 keeps every payload in its SQLite tiers and has no separate HTTP cache
Cache.clear_cache
Parameters
Behavior Details
The clearing process works as follows:- Active Cache Detection: If
cache_dirisNone, uses the active cache instance (and creates it if needed) - Directory Validation: If
cache_diris given, verifies that it exists and is a directory - SQLite Clearing: Executes
DELETEstatements on all cache tables - Memory Cache Flush: Clears in-memory LRU caches
- Legacy Cleanup (if
deep=Trueandcache_diris given): Removes FastF1 HTTP cache files for users migrating from fastf1
cache_dir that is not the active directory gets a temporary cache instance, which is closed after the clear.
Cache Tables Cleared
cachetable: Fetched JSON payloads (lap times, drivers, race control messages, weather data), as text or compressedtelemetry_cachetable: Telemetry data indexed by (year, GP, session, driver, lap)telemetry_framesandtelemetry_frames_pltables: Built telemetry frames for the pandas and polars backendslaps_framesandlaps_frames_pltables: Built laps tables for the pandas and polars backendsmissing_payloadstable: Records of files that no CDN has- In-memory caches: All four in-memory LRU tiers
Examples
Clear the active cache:Migration from fastf1
The signature is the same as in fastf1 (cache_dir=None, deep=False):
Error Handling
NotADirectoryError: Raised if the specifiedcache_dirdoes not exist or is not a directoryOSErrorwhile a legacy file is removed: logged as a warning, not raised
Performance Impact
- Clearing time: Grows with the number of cached rows
- Disk usage:
DELETEdoes not makecache.sqlitesmaller. SQLite keeps the free pages for new data - 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() holds the cache locks while it deletes the rows. Do not call it while other threads load data: a load in progress can write its rows again after the clear.
Other Cache Methods
Logging Functions
set_log_level
tif1.set_log_level is tif1.logger.set_log_level. tif1.fastf1_compat.set_log_level is a separate wrapper that imports tif1.logger on its first call and passes level to it, so all three have the same effect.
Parameters:
level: Python logging level (for example,logging.DEBUG,logging.INFO,logging.WARNING) or its name in any case ("DEBUG","info"). An unknown name raisesValueError
tif1 logger and its console handler both move to level.
Example:
tif1.logger
The fastf1 fastf1.logger module, with tif1 logger names. Every logger is tif1 or a tif1.<name> child, never fastf1. Importing the module adds a console handler with the fastf1 line format to the tif1 logger and sets that logger to INFO.
tif1.legacy
inject_driver_ahead
fastf1.legacy.inject_driver_ahead() function. It returns a dict keyed by driver number (the labels of session.drivers). Each value is the session-long session.pos_data telemetry of the driver. tif1 telemetry already carries DriverAhead and DistanceToDriverAhead, so the function only collects the frames. It reads the telemetry of every driver, which is slow on a cold cache. When no driver has telemetry, it raises ValueError, as fastf1 does.
Complete migration example
This complete example shows a fastf1 script migrated to tif1. The fastf1 original is the same script withfastf1 in place of tif1; only the import and the module prefix change.
Migrated tif1 code (minimal changes):
API Differences
While tif1 maintains API compatibility, there are some differences to be aware of:Supported Features
Ignored Parameters
Some fastf1 parameters are ignored in tif1 because they are handled automatically:Cache.enable_cache(ignore_version)andCache.configure(ignore_version=...): tif1 handles versioning automaticallyCache.enable_cache(use_requests_cache)andCache.configure(use_requests_cache=...): tif1 uses SQLite cache
Cache.enable_cache(force_renew=True) is not ignored: it clears the cache after enabling it.
Performance Improvements
tif1 provides significant performance improvements while maintaining API compatibility:- Async loading:
session.laps_async()for parallel data fetching - Ultra-cold start: the
ultra_cold_startoption (on by default) 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 fastf1withimport tif1 - Update
Cache.enable_cache()calls (same call) - Update
set_log_level()calls (same call) - 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)
Ergast data
tif1.ergast is a drop-in for fastf1.ergast. from tif1.ergast import Ergast keeps the thirteen endpoint methods, their keyword arguments, the flattened column names, the response classes and the legacy fetch_season/fetch_day/fetch_results helpers. The data comes from the TracingInsights Stats repository first and from the Jolpica API only for what that repository cannot answer. The 500-requests-per-hour ceiling therefore stays out of the way for season-wide queries. Session.results carries the official classification (grid, points, status, race time, qualifying segments) and get_session, get_event and get_event_schedule accept fastf1’s backend= keyword. Refer to Ergast.
Known Limitations
The following fastf1 features are not supported in tif1:- Live timing: tif1 focuses on historical data.
session.load(livedata=...)raisesNotImplementedErrorfor any value other thanNone - F1 account sign-in:
set_auth_method()andF1AuthErrordo not exist, because tif1 needs no account - Internal modules:
fastf1.livetiming,fastf1.req,fastf1.api, andfastf1.internalshave no tif1 equivalent - Custom data sources: the
cdnssetting can point at a mirror, but the mirror must use the same file layout as the TracingInsights repositories
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