Skip to main content

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:
  1. In-Memory LRU Cache: Lock-free reads for frequently accessed data (memory_cache_max_items, default 1024 items)
  2. Telemetry-Specific Cache: Dedicated in-memory cache for telemetry data (memory_telemetry_cache_max_items, default 2048 items)
  3. SQLite Persistence: WAL-mode SQLite database (cache.sqlite) for durable storage with optimized concurrency
Two smaller in-memory LRU tiers (128 and 256 items) keep parsed payloads, so repeated reads skip JSON parsing. This multi-layer approach ensures that hot data is served from memory while maintaining persistence across sessions.

Cache.enable_cache

Enable caching with fastf1-compatible API. This method initializes tif1’s caching system and configures the cache directory. After this call, tif1 caches all fetched data for faster access.

Parameters

Returns

  • tif1.cache.Cache: The configured global tif1 cache instance (the same object that tif1.get_cache() returns)

Behavior Details

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

Cache Directory Resolution

The cache directory is resolved in the following order of precedence:
  1. Explicit cache_dir parameter
  2. The directory of an earlier enable_cache() call in the same process
  3. TIF1_CACHE_DIR environment variable
  4. Configuration file setting (~/.tif1rc)
  5. 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:
Custom cache directory:
Enable cache and clear existing data:
Environment variable configuration:

Migration from fastf1

The call is the same, so migration needs few changes:
Two defaults differ. In fastf1, 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.sqlite grows 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

The fastf1 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 directory
  • force_renew: Clear the cache after enabling it
  • ignore_version, use_requests_cache: Accepted for compatibility. tif1 keeps every payload in its SQLite tiers and has no separate HTTP cache

Cache.clear_cache

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

Behavior Details

The clearing process works as follows:
  1. Active Cache Detection: If cache_dir is None, uses the active cache instance (and creates it if needed)
  2. Directory Validation: If cache_dir is given, verifies that it exists and is a directory
  3. SQLite Clearing: Executes DELETE statements on all cache tables
  4. Memory Cache Flush: Clears in-memory LRU caches
  5. Legacy Cleanup (if deep=True and cache_dir is given): Removes FastF1 HTTP cache files for users migrating from fastf1
A cache_dir that is not the active directory gets a temporary cache instance, which is closed after the clear.

Cache Tables Cleared

  • cache table: Fetched JSON payloads (lap times, drivers, race control messages, weather data), as text or compressed
  • telemetry_cache table: Telemetry data indexed by (year, GP, session, driver, lap)
  • telemetry_frames and telemetry_frames_pl tables: Built telemetry frames for the pandas and polars backends
  • laps_frames and laps_frames_pl tables: Built laps tables for the pandas and polars backends
  • missing_payloads table: Records of files that no CDN has
  • In-memory caches: All four in-memory LRU tiers

Examples

Clear the active cache:
Clear a specific cache directory:
Deep clean (remove legacy FastF1 files):
Clear cache before important race weekend:

Migration from fastf1

The signature is the same as in fastf1 (cache_dir=None, deep=False):

Error Handling

  • NotADirectoryError: Raised if the specified cache_dir does not exist or is not a directory
  • OSError while a legacy file is removed: logged as a warning, not raised

Performance Impact

  • Clearing time: Grows with the number of cached rows
  • Disk usage: DELETE does not make cache.sqlite smaller. 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

Set the logging level for tif1 logger. 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 raises ValueError
The tif1 logger and its console handler both move to level. Example:
Migration from fastf1:

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

The fastf1 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 with fastf1 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) and Cache.configure(ignore_version=...): tif1 handles versioning automatically
  • Cache.enable_cache(use_requests_cache) and Cache.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_start option (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 fastf1 with import 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=...) raises NotImplementedError for any value other than None
  • F1 account sign-in: set_auth_method() and F1AuthError do not exist, because tif1 needs no account
  • Internal modules: fastf1.livetiming, fastf1.req, fastf1.api, and fastf1.internals have no tif1 equivalent
  • Custom data sources: the cdns setting can point at a mirror, but the mirror must use the same file layout as the TracingInsights repositories
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:
  1. Check the Migration Guide for detailed instructions
  2. Review the FAQ for common questions
  3. Open an issue on GitHub
Last modified on October 30, 2026