Python API Reference

Auto-generated from source code docstrings. For usage examples and guides, see the Usage Guide.

Manager

class f1_replay.managers.race_manager.Manager(cache_dir: str | None = None, timezone: str | None = None)

Bases: object

Top-level coordinator for F1 data and race viewer.

Manages seasons catalog, loads race/session data, and launches Flask viewer app.

Usage:

manager = Manager() # Uses global config

# Access season catalog seasons = manager.seasons # {year: [EventInfo, …]} manager.seasons[2024] # List of rounds for 2024

# Load race data weekend = manager.load_weekend(2024, 24) session = manager.load_race(2024, 24)

# Launch viewer (direct Flask app) manager.race(2024, 24) # By round number manager.race(2024, “abu dhabi”) # By event name

__init__(cache_dir: str | None = None, timezone: str | None = None)

Initialize Manager.

Parameters:

  • cache_dir – Directory for data caching (default: from global config)

  • timezone – Timezone for display (e.g., “Europe/Oslo”, “America/New_York”) Default: None (shows UTC times)

get_seasons(force_update: bool = False) → Dict[int, List[EventInfo]] | None

Load F1 seasons catalog (caches in memory).

Parameters:

force_update – Force rebuild from FastF1

Returns:

[EventInfo]} or None

Return type:

Dict {year

get_season(year: int) → List[EventInfo] | None

Get season data for specific year.

Parameters:

year – Season year

Returns:

List of EventInfo or None if year not found

list_years() → List[int]

Get list of available years in catalog.

Returns:

Sorted list of year integers

property seasons: Dict[int, List[EventInfo]]

Get dict of available seasons (year -> [EventInfo]).

Usage:

manager.seasons[2024] # Get 2024 events manager.seasons[2024][0] # First EventInfo manager.seasons[2024][0].name # Event name

season_schedule(year: int, force_update: bool = False) → None

Print a formatted schedule for the season.

Parameters:

  • year – Season year

  • force_update – Force refresh from FastF1

weekend_schedule(year: int) → ScheduleList

Get all race weekends for a season (excludes testing events).

race_schedule(year: int) → ScheduleList

Get race session schedule for a season.

sprint_schedule(year: int) → ScheduleList

Get sprint race schedule for a season.

qualification_schedule(year: int) → ScheduleList

Get qualifying session schedule for a season.

sprintquali_schedule(year: int) → ScheduleList

Get sprint qualifying (shootout) schedule for a season.

practice_schedule(year: int) → ScheduleList

Get practice and testing session schedule for a season.

property weekend: RaceWeekend | None

Get currently loaded weekend.

property session: Session | None

Get currently loaded session.

load_weekend(year: int, round_num_or_name: int | str = None, force_update: bool = False, testing: bool | int | str = False, sessions: List[str] | None = None) → Manager

Load race weekend data (circuit geometry + metadata) into manager.

If track geometry is placeholder (not yet extracted), efficiently loads just the race results and winner’s telemetry to extract track/pit lane.

Access loaded data via manager.weekend property.

Parameters:

  • year – Season year

  • round_num_or_name – Round number or event name (required unless testing=True)

  • force_update – Force rebuild from FastF1 (default: False)

  • testing – Load pre-season testing instead of race weekend: - True or 1 or “T1” or “T01”: First testing event - 2 or “T2” or “T02”: Second testing event - etc.

  • sessions – List of sessions to load (e.g., [‘race’, ‘qualifying’] or [‘R’, ‘Q’])

Returns:

self (for method chaining)

load_session(year: int | None = None, round_num_or_name: int | str | None = None, session_type: str = 'R', force_update: bool = False) → Manager

Load session data (telemetry, events, results) into manager.

Uses already loaded weekend if available, otherwise loads it first. If year/round not specified, uses currently loaded weekend. Access loaded data via manager.session and manager.weekend properties.

Parameters:

  • year – Season year (optional if weekend already loaded)

  • round_num_or_name – Round number or event name (optional if weekend already loaded)

  • session_type – Session type (“R”, “Q”, “FP1”, “FP2”, “FP3”, “S”) (default: “R”)

  • force_update – Force rebuild from FastF1 (default: False)

Returns:

self (for method chaining)

load_race(year: int | None = None, round_num_or_name: int | str | None = None, force_update: bool = False) → Manager

Load race session (alias for load_session with session_type=’R’).

If year/round not specified, uses currently loaded weekend. Access loaded data via manager.session and manager.weekend properties.

Parameters:

  • year – Season year (optional if weekend already loaded)

  • round_num_or_name – Round number or event name (optional if weekend already loaded)

  • force_update – Force rebuild from FastF1 (default: False)

Returns:

self (for method chaining)

process_season(year: int, force_update: bool = False) → None

Process all races in a season, loading weekend and race data.

If force_update is True, all data will be reprocessed from FastF1 (not cached). Useful for bulk updating a season’s data or warming up the cache.

Parameters:

  • year – Season year to process

  • force_update – Force rebuild all races from FastF1 (default: False)

race(year: int | None = None, round_num_or_name: int | str | None = None, host: str = '0.0.0.0', port: int = 8080, debug: bool = True, force_update: bool = False) → None

Load race and launch interactive Flask viewer.

If year/round not specified, uses currently loaded race session.

Supports both round number and event name:

manager.race(2024, 24) # By round number manager.race(2024, “abu dhabi”) # By event name manager.race(2024, “monaco”) # Partial match manager.race(2024, 8, force_update=True) # Force rebuild from FastF1 manager.race() # Use already loaded session

Parameters:

  • year – Season year (optional if weekend with race already loaded)

  • round_num_or_name – Round number (int) or event name (str)

  • host – Host to bind Flask app (default: ‘0.0.0.0’)

  • port – Port to run Flask app (default: 8080)

  • debug – Enable Flask debug mode (default: True)

  • force_update – Force rebuild all data from FastF1 (default: False)

view(year: int, round_num_or_name: int | str, host: str = '0.0.0.0', port: int = 8080, debug: bool = True, force_update: bool = False) → None

Alias for race() - for future multi-session viewer support.

Parameters:

  • year – Season year

  • round_num_or_name – Round number (int) or event name (str)

  • host – Host to bind Flask app (default: ‘0.0.0.0’)

  • port – Port to run Flask app (default: 8080)

  • debug – Enable Flask debug mode (default: True)

  • force_update – Force rebuild all data from FastF1 (default: False)

DataLoader

class f1_replay.managers.dataloader.DataLoader(cache_dir: str = None)

Bases: object

Main data loader orchestrating 3-tier caching.

Usage:

loader = DataLoader() seasons = loader.load_seasons() # TIER 1 weekend = loader.load_weekend(2024, 1) # TIER 2 session = loader.load_session(2024, 1, “Race”) # TIER 3

__init__(cache_dir: str = None)

Initialize DataLoader.

Parameters:

cache_dir – Directory for caching. If None, uses system default (~/Documents/f1-replay on macOS/Windows, ~/.local/share/f1-replay on Linux).

load_seasons(years: list = None, force_update: bool = False) → Dict[int, List[EventInfo]] | None

Load F1 seasons catalog (TIER 1).

File: race_data/seasons.pkl

Automatically fetches current year if missing from cache.

Parameters:

  • years – List of years to fetch (default: current year + 5 previous years)

  • force_update – Force rebuild from FastF1

Returns:

Dict[int, List[EventInfo]] or None

load_weekend(year: int, round_num: int, event: EventInfo, force_reprocess: bool = False, force_update: bool = False) → F1Weekend | None

Load race weekend data (TIER 2): circuit + metadata.

File: race_data/year/round_location/Weekend.pkl

Parameters:

  • year – Season year

  • round_num – Round number

  • event – EventInfo from seasons catalog

  • force_reprocess – Force rebuild from FastF1

  • force_update – Alias for force_reprocess (for API consistency)

Returns:

F1Weekend object or None

load_session(year: int, round_num: int, session_type: str, event: EventInfo, circuit_length: float, weekend_track=None, force_reprocess: bool = False, force_update: bool = False) → LoadResult | None

Load session data (TIER 3): telemetry, events, results.

File: race_data/year/round_location/{SessionType}.pkl Example: race_data/2024/08_Monaco/Race.pkl

Parameters:

  • year – Season year

  • round_num – Round number

  • session_type – User-friendly names (“Race”, “Qualifying”, “Practice1”, etc.) or FastF1 codes (“R”, “Q”, “FP1”, etc.)

  • event – EventInfo from seasons catalog

  • circuit_length – Circuit length in meters (from weekend)

  • weekend_track – Optional TrackGeometry from Weekend (for adding track_distance to telemetry)

  • force_reprocess – Force rebuild from FastF1

  • force_update – Alias for force_reprocess (for API consistency)

Returns:

LoadResult with .data (SessionData) and .raw_session (FastF1 session or None) raw_session is only populated when freshly processed (not from cache)

load_race_results(year: int, round_num: int) → RaceResults | None

Load just race results (positions, winner) without full telemetry.

Returns:

RaceResults with winner and raw_session, or None

get_raw_session(year: int, round_num: int, session_type: str = 'R')

Get raw FastF1 session with telemetry loaded.

This is a pass-through to fastf1_client for Manager orchestration.

get_event(year: int, round_num: int) → EventInfo | None

Get EventInfo from seasons catalog.

get_cache_info() → dict

Get information about cached data.

clear_cache(year: int | None = None, round_num: int | None = None)

Clear cached data.

Parameters:

  • year – If specified, only clear that year

  • round_num – If specified with year, only clear that round

Session

class f1_replay.wrappers.session.Session(data: SessionData, weekend: RaceWeekend, raw_session: Any = None)

Bases: object

Base session wrapper - delegates to SessionData dataclass.

Stores the immutable SessionData and adds convenience methods.

property session_type: str
property year: int
property round_number: int
property event_name: str
property drivers: List[str]
property driver_numbers: Dict[str, int]
property driver_names: Dict[str, str]
property driver_teams: Dict[str, str]
property driver_colors: Dict[str, str]
property track_length: float
property total_laps: int
property dnf_drivers: List[str]
property start_time_local: str | None
property t0_utc: str | None
property t0_timezone: str
property lights_out_offset: float
property warmup_start_time: float | None

Session time when formation lap starts (seconds since t0).

property race_start_time: float | None

Session time when lights go out / race starts (seconds since t0).

property warm_up_offset: float | None

Alias for warmup_start_time (for backwards compatibility).

property telemetry: Dict[str, polars.DataFrame]
property track_status: polars.DataFrame
property race_control: polars.DataFrame
property weather: polars.DataFrame

Weather data (empty - weather is integrated into track_status as rain events).

property rain_events: polars.DataFrame

Extract rain events from track_status.

property fastest_laps: List
property position_history: List
property data: SessionData

Underlying SessionData dataclass.

property raw_session

Raw FastF1 session (only when freshly loaded, not from cache).

property weekend: RaceWeekend

Parent RaceWeekend.

property circuit_length: float

Circuit length from weekend.

property track: TrackGeometry

Track geometry from weekend.

property pit_lane: PitLane | None

Pit lane geometry from weekend.

property driver_info: Dict[str, Dict]

{number, name, team, color}}.

Type:

Get driver information as {driver

get_driver_telemetry(driver: str) → polars.DataFrame | None

Get telemetry for a specific driver.

is_raining(session_time: float) → bool

Check if it’s raining at a specific session time.

class f1_replay.wrappers.session.RaceSession(data: SessionData, weekend: RaceWeekend, raw_session: Any = None)

Bases: Session

Race session with position tracking methods.

property lights_out: float

Lights out time as offset in seconds from session start (t0).

property lights_out_idx: int | None

Row index in telemetry where the race starts (lights out).

get_order_at_time(session_time: float) → List[Tuple[int, str, float]]

Get driver standings at a specific time.

Parameters:

session_time – Time in seconds since session start

Returns:

List of (position, driver, race_distance) tuples sorted by position

get_order_at_lap(lap: int) → List[Tuple[int, str, float]]

Get driver standings when they completed a specific lap.

For drivers who completed the lap: order by who crossed first. For DNF drivers: order by their max race_distance.

Parameters:

lap – Lap number to check

Returns:

List of (position, driver, race_distance) tuples sorted by position

get_leader_at_time(session_time: float) → str | None

Get race leader at a specific time.

get_telemetry_every_lap(driver: str, offset: int = 0) → polars.DataFrame | None

Get one telemetry point per lap for a driver.

Parameters:

  • driver – Driver code (e.g., ‘LEC’)

  • offset – Which point within each lap to return: 0 = first point of each lap (default) -1 = last point of each lap n = nth point of each lap

Returns:

DataFrame with one row per lap, or None if driver not found

get_telemetry_every_minute(driver: str, interval: float = 1.0) → polars.DataFrame | None

Get telemetry at regular time intervals for a driver.

Parameters:

  • driver – Driver code (e.g., ‘LEC’)

  • interval – Time interval in minutes (default=1.0, so 0.5=30s, 2.0=120s)

Returns:

DataFrame with one row per interval, or None if driver not found

RaceWeekend

class f1_replay.wrappers.race_weekend.RaceWeekend(data: F1Weekend, display_timezone: str | None = None, session_loader: Callable[[str], Session | None] | None = None)

Bases: object

Race weekend with circuit geometry and loaded sessions.

Wraps F1Weekend (EventInfo + CircuitData) internally. Manages session loading/unloading for memory efficiency.

year

Season year

round_number

Race round number

name

e.g., ‘Monaco Grand Prix’

official_name

e.g., ‘FORMULA 1 CRYPTO.COM MONACO GRAND PRIX 2025’

circuit_name

e.g., ‘Monte Carlo’

country

e.g., ‘Monaco’

timezone_offset

e.g., ‘+02:00’

start_date

First session date (ISO)

end_date

Race date (ISO)

format

‘conventional’ or ‘sprint_qualifying’

session_schedule

{session_name: datetime}

circuit

CircuitData (track, pit_lane, length, corners, etc.)

__init__(data: F1Weekend, display_timezone: str | None = None, session_loader: Callable[[str], Session | None] | None = None)

Initialize from F1Weekend dataclass.

Parameters:

  • data – F1Weekend dataclass (EventInfo + CircuitData)

  • display_timezone – Timezone for display

  • session_loader – Optional callback to load sessions (year, round, type) -> Session

property event: EventInfo

Access underlying EventInfo.

property track: TrackGeometry

Direct access to track geometry.

property pit_lane: PitLane | None

Direct access to pit lane.

property circuit_length: float

Circuit length in meters.

property corners: int

Number of corners.

property rotation: float

Track rotation in degrees.

property marshal_sectors: List[MarshalSector]

Marshal sectors (yellow flag zones).

property direction_arrow: DirectionArrow | None

Direction arrow at start/finish (opposite pitlane).

get_track_coords() → Dict[str, list]

Get track coordinates as JSON-friendly lists.

get_pit_lane_coords() → Dict[str, list] | None

Get pit lane coordinates as JSON-friendly lists.

get_marshal_sectors() → List[MarshalSector]

Get marshal sectors.

set_session(session_type: str, session: Session) → None

Store a loaded session.

unload_session(session_type: str) → bool

Unload a session to free memory.

Parameters:

session_type – Session type (‘R’, ‘Q’, ‘FP1’, etc.)

Returns:

True if session was unloaded, False if not loaded

unload_all_sessions() → int

Unload all sessions to free memory.

Returns:

Number of sessions unloaded

clear_sessions() → None

Clear all loaded sessions. Alias for unload_all_sessions().

is_session_loaded(session_type: str) → bool

Check if a session is currently loaded.

property loaded_sessions: List[str]

List of loaded session types.

SESSION_ALIASES = {'fp1': 'FP1', 'fp2': 'FP2', 'fp3': 'FP3', 'practice 1': 'FP1', 'practice 2': 'FP2', 'practice 3': 'FP3', 'practice1': 'FP1', 'practice2': 'FP2', 'practice3': 'FP3', 'q': 'Q', 'quali': 'Q', 'qualifying': 'Q', 'r': 'R', 'race': 'R', 's': 'S', 'sprint': 'S', 'sprint qualifying': 'SQ', 'sprint shootout': 'SQ', 'sprint_qualifying': 'SQ', 'sprintquali': 'SQ', 'sq': 'SQ'}
load_session(session_type: str, force_update: bool = False) → Session | None

Load a session into this weekend.

Parameters:

  • session_type – Session type (‘race’, ‘R’, ‘qualifying’, ‘Q’, ‘FP1’, etc.)

  • force_update – Force reload from FastF1

Returns:

Loaded Session or None if loader not available

property race: Session

Race session (raises helpful error if not loaded).

property qualifying: Session

Qualifying session (raises helpful error if not loaded).

property sprint: Session

Sprint session (raises helpful error if not loaded).

property fp1: Session

FP1 session (raises helpful error if not loaded).

property fp2: Session

FP2 session (raises helpful error if not loaded).

property fp3: Session

FP3 session (raises helpful error if not loaded).

keys() → List[str]

List available data fields.

plot(figsize: tuple = (12, 10), color_mode: str = 'white', save_path: str = None, dpi: int = 150, track_width: float = 4)

Generate poster-style circuit map.

Parameters:

  • figsize – Figure size (width, height)

  • color_mode – Track coloring - ‘white’, ‘sectors’, ‘speed’, ‘throttle’, ‘height’

  • save_path – Save to file instead of displaying

  • dpi – Resolution for saved file

  • track_width – Line width for track (default 4)

Returns:

matplotlib Figure