Types - tif1

The tif1.types module provides comprehensive type definitions for all data structures used in the library, including TypedDicts for DataFrame schemas and Literal types for enumerations.

DataFrame Union Type

DataFrame

DataFrame = Union[pd.DataFrame, pl.DataFrame]

Union type that supports both pandas and polars DataFrames. Falls back to pd.DataFrame if polars is not installed.

TypedDict Definitions

LapDataDict

class LapDataDict(TypedDict):
    """Type definition for lap data dictionary."""

Defines the structure of lap data returned by Session.laps and related methods.

Required Fields

Field	Type	Description
`Driver`	`str`	Driver identifier (3-letter code)
`DriverNumber`	`str`	Driver racing number
`Team`	`str`	Team name
`Time`	`datetime.timedelta`	Session time from session start

Optional Fields - Lap Timing

Field	Type	Description
`LapTime`	`timedelta \| None`	Total lap time
`LapNumber`	`float \| None`	Lap number
`Stint`	`float \| None`	Stint number
`PitOutTime`	`timedelta \| None`	Time when driver exited pit
`PitInTime`	`timedelta \| None`	Time when driver entered pit
`Sector1Time`	`timedelta \| None`	Sector 1 time
`Sector2Time`	`timedelta \| None`	Sector 2 time
`Sector3Time`	`timedelta \| None`	Sector 3 time
`Sector1SessionTime`	`timedelta \| None`	Session time at sector 1
`Sector2SessionTime`	`timedelta \| None`	Session time at sector 2
`Sector3SessionTime`	`timedelta \| None`	Session time at sector 3
`LapStartTime`	`timedelta \| None`	Lap start time (from session start)
`LapStartDate`	`datetime \| None`	Absolute lap start datetime
`LapTimeSeconds`	`float \| None`	Lap time in seconds (derived)

Optional Fields - Speed Traps

Field	Type	Description
`SpeedI1`	`float \| None`	Speed at intermediate 1 (km/h)
`SpeedI2`	`float \| None`	Speed at intermediate 2 (km/h)
`SpeedFL`	`float \| None`	Speed at finish line (km/h)
`SpeedST`	`float \| None`	Speed at speed trap (km/h)

Optional Fields - Tyre Information

Field	Type	Description
`Compound`	`str \| None`	Tyre compound name
`TyreLife`	`float \| None`	Laps on current tyres
`FreshTyre`	`bool`	Whether tyres are fresh

Optional Fields - Session Metadata

Field	Type	Description
`TrackStatus`	`str \| None`	Track status code
`Position`	`float \| None`	Position in race/session
`IsPersonalBest`	`bool`	Whether lap is driver’s personal best
`Deleted`	`bool \| None`	Whether lap was deleted
`DeletedReason`	`str \| None`	Reason for lap deletion
`FastF1Generated`	`bool`	Whether lap is generated by FastF1
`IsAccurate`	`bool`	Whether lap data is accurate

Optional Fields - Weather Data

Field	Type	Description
`WeatherTime`	`timedelta \| None`	Weather data timestamp
`AirTemp`	`float \| None`	Air temperature (°C)
`Humidity`	`float \| None`	Humidity (%)
`Pressure`	`float \| None`	Air pressure (mbar)
`Rainfall`	`bool`	Whether it’s raining
`TrackTemp`	`float \| None`	Track temperature (°C)
`WindDirection`	`int \| None`	Wind direction (degrees)
`WindSpeed`	`float \| None`	Wind speed (km/h)

TelemetryDataDict

class TelemetryDataDict(TypedDict):
    """Type definition for telemetry data dictionary."""

Defines the structure of telemetry data returned by Lap.telemetry and Driver.telemetry.

Required Fields

Field	Type	Description
`Time`	`float`	Timestamp in seconds

Optional Fields

Field	Type	Description
`RPM`	`int \| None`	Engine RPM
`Speed`	`float \| None`	Speed (km/h)
`nGear`	`int \| None`	Gear number
`Throttle`	`float \| None`	Throttle position (0-100)
`Brake`	`int \| None`	Brake status (0 or 1)
`DRS`	`int \| None`	DRS status (0-14)
`Distance`	`float \| None`	Distance travelled (meters)
`RelativeDistance`	`float \| None`	Relative distance on track
`DriverAhead`	`str \| None`	Driver ahead identifier
`DistanceToDriverAhead`	`float \| None`	Distance to driver ahead (meters)
`X`	`float \| None`	X coordinate position
`Y`	`float \| None`	Y coordinate position
`Z`	`float \| None`	Z coordinate position
`AccelerationX`	`float \| None`	X-axis acceleration (g)
`AccelerationY`	`float \| None`	Y-axis acceleration (g)
`AccelerationZ`	`float \| None`	Z-axis acceleration (g)
`DataKey`	`str \| None`	Data source key

DriverInfoDict

class DriverInfoDict(TypedDict):
    """Type definition for driver info dictionary."""

Defines the structure of driver information data.

Field	Type	Description
`driver`	`str`	Driver identifier (3-letter code)
`team`	`str`	Team name
`dn`	`str`	Driver number
`fn`	`str`	First name
`ln`	`str`	Last name
`tc`	`str`	Team color code
`url`	`str`	Driver profile URL

RaceControlDataDict

class RaceControlDataDict(TypedDict):
    """Type definition for race control data dictionary."""

Defines the structure of race control messages.

Required Fields

Field	Type	Description
`Time`	`float`	Message timestamp in seconds

Optional Fields

Field	Type	Description
`Category`	`str \| None`	Message category
`Message`	`str \| None`	Message text
`Status`	`str \| None`	Session status
`Flag`	`str \| None`	Flag type
`Scope`	`str \| None`	Message scope
`Sector`	`int \| str \| None`	Affected sector
`RacingNumber`	`str \| None`	Affected driver number
`Lap`	`int \| None`	Lap number

WeatherDataDict

class WeatherDataDict(TypedDict):
    """Type definition for weather data dictionary."""

Defines the structure of weather data returned by Session.weather.

Required Fields

Field	Type	Description
`Time`	`timedelta`	Timestamp from session start

Optional Fields

Field	Type	Description
`AirTemp`	`float \| None`	Air temperature (°C)
`Humidity`	`float \| None`	Humidity (%)
`Pressure`	`float \| None`	Air pressure (mbar)
`Rainfall`	`bool \| None`	Whether it’s raining
`TrackTemp`	`float \| None`	Track temperature (°C)
`WindDirection`	`int \| None`	Wind direction (degrees)
`WindSpeed`	`float \| None`	Wind speed (km/h)

Literal Types

SessionType

SessionType = Literal[
    "Practice 1",
    "Practice 2",
    "Practice 3",
    "Qualifying",
    "Sprint",
    "Sprint Qualifying",
    "Sprint Shootout",
    "Race",
]

Valid session type identifiers for F1 sessions. Values:

"Practice 1" - First practice session
"Practice 2" - Second practice session
"Practice 3" - Third practice session
"Qualifying" - Qualifying session
"Sprint" - Sprint race
"Sprint Qualifying" - Sprint qualifying session
"Sprint Shootout" - Sprint shootout session
"Race" - Main race

BackendType

BackendType = Literal["pandas", "polars"]

Available DataFrame backend types. Values:

"pandas" - Use pandas DataFrames (default)
"polars" - Use polars DataFrames (requires polars installation)

CompoundType

CompoundType = Literal[
    "SOFT",
    "MEDIUM",
    "HARD",
    "INTERMEDIATE",
    "WET",
    "UNKNOWN",
    "TEST_UNKNOWN",
]

Tyre compound identifiers. Values:

"SOFT" - Soft compound (red)
"MEDIUM" - Medium compound (yellow)
"HARD" - Hard compound (white)
"INTERMEDIATE" - Intermediate wet weather tyre (green)
"WET" - Full wet weather tyre (blue)
"UNKNOWN" - Unknown compound
"TEST_UNKNOWN" - Unknown test compound

TrackStatusType

TrackStatusType = Literal["1", "2", "4", "5", "6", "7"]

Track status codes used in F1. Values:

"1" - Track clear (green flag)
"2" - Yellow flag
"4" - Safety car
"5" - Red flag
"6" - Virtual safety car
"7" - VSC ending

Protocol Types

DataFrameProtocol

class DataFrameProtocol(Protocol):
    """Protocol for DataFrame-like objects."""

A protocol defining the minimum interface for DataFrame-like objects. Used for type checking compatibility with both pandas and polars DataFrames. Required Attributes:

shape: tuple[int, int] - DataFrame dimensions (rows, columns)
columns: list[str] - Column names

Required Methods:

head(n: int = 5) - Return first n rows
__len__() - Return number of rows
__getitem__(key) - Support indexing and slicing

Usage Examples

Type Hints with LapDataDict

from tif1.types import LapDataDict
import tif1

session = tif1.get_session(2024, "Monaco", "Race")
session.load()

# Access lap data with proper type hints
lap: LapDataDict = session.laps.iloc[0].to_dict()  # type: ignore
print(f"Driver: {lap['Driver']}")
print(f"Lap Time: {lap.get('LapTime')}")

Backend Type Selection

from tif1.types import BackendType
import tif1

backend: BackendType = "polars"
tif1.set_backend(backend)

Session Type Validation

from tif1.types import SessionType

def get_qualifying_data(year: int, event: str) -> None:
    session_type: SessionType = "Qualifying"
    session = tif1.get_session(year, event, session_type)
    session.load()

​DataFrame Union Type

​DataFrame

​TypedDict Definitions

​LapDataDict

​Required Fields

​Optional Fields - Lap Timing

​Optional Fields - Speed Traps

​Optional Fields - Tyre Information

​Optional Fields - Session Metadata

​Optional Fields - Weather Data

​TelemetryDataDict

​Required Fields

​Optional Fields

​DriverInfoDict

​RaceControlDataDict

​Required Fields

​Optional Fields

​WeatherDataDict

​Required Fields

​Optional Fields

​Literal Types

​SessionType

​BackendType

​CompoundType

​TrackStatusType

​Protocol Types

​DataFrameProtocol

​Usage Examples

​Type Hints with LapDataDict

​Backend Type Selection

​Session Type Validation

DataFrame Union Type

DataFrame

TypedDict Definitions

LapDataDict

Required Fields

Optional Fields - Lap Timing

Optional Fields - Speed Traps

Optional Fields - Tyre Information

Optional Fields - Session Metadata

Optional Fields - Weather Data

TelemetryDataDict

Required Fields

Optional Fields

DriverInfoDict

RaceControlDataDict

Required Fields

Optional Fields

WeatherDataDict

Required Fields

Optional Fields

Literal Types

SessionType

BackendType

CompoundType

TrackStatusType

Protocol Types

DataFrameProtocol

Usage Examples

Type Hints with LapDataDict

Backend Type Selection

Session Type Validation