Data Objects#

Season#

The Season class represents a Formula 1 season, containing methods to load and manage the season’s meetings and sessions.

Example:

from livef1.models.season import Season

# Initialize a season for the year 2023
season_2023 = Season(year=2023, meetings=[])

# Load the season data
season_2023.load()

# Access the meetings
meetings = season_2023.meetings

Meeting#

The Meeting class represents a meeting in a specific season with relevant details and associated sessions.

Example:

from livef1.models.meeting import Meeting

# Initialize a meeting
meeting = Meeting(season=season_2023, year=2023, location="Monaco")

# Load the meeting data
meeting.load()

# Access the sessions
sessions = meeting.sessions

Session#

The Session class represents a Formula 1 session, containing methods to retrieve live timing data and process it.

Example:

from livef1.models.session import Session

# Initialize a session
session = Session(season=season_2023, meeting=meeting, name="Practice 1")

# Get topic names
topic_names = session.get_topic_names()

# Load data for a specific topic
data = session.load_data(dataName="Car_Data")

Generating Data#

The generate method in the Session class is used to generate and save processed data tables (silver and gold tables) for the session. This is useful for organizing and accessing detailed session data efficiently.

Example:

# Generate silver tables for the session
session.generate(silver=True, gold=False)

# Access the generated data
laps = session.laps
telemetry = session.carTelemetry
weather = session.get_weather()
timing = session.get_timing()

Why Run .generate#

Running the .generate method is important for the following reasons:

Data Organization: It organizes raw data into structured tables, making it easier to analyze and visualize.
Efficiency: Preprocessing and storing data in tables reduces the need for repeated data parsing and processing.
Accessibility: Generated tables can be accessed directly through the session object, simplifying data retrieval.

`models.Season`([year, meetings, season, ...])	Represents a Formula 1 season, containing methods to load and manage the season's meetings and sessions.
`models.Meeting`([season, year, code, key, ...])	Represents a meeting in a specific season with relevant details and associated sessions.
`models.Session`([season, year, meeting, key, ...])	Represents a Formula 1 session, containing methods to retrieve live timing data and process it.

livef1.configure(*, log_level=None, logging_stream_format=None, logging_stream_datefmt=None, logging_file_path=<object object>, logging_file_format=None, logging_file_datefmt=None, auth_save_token=None, auth_token_path=None, auth_env_path=None)[source]#

Configure LiveF1 package settings.

Call this before running LiveF1 code when you need non-default behaviour (for example logging in read-only environments such as AWS Lambda).

Parameters:

log_levelUnion[str, int], optional: Logging level as a string ('DEBUG', 'INFO', …) or an logging module constant.
logging_stream_formatstr, optional: Format string for the console (stream) handler.
logging_stream_datefmtstr, optional: Date/time format for the console handler.
logging_file_pathstr or pathlib.Path or None, optional: Path to the log file. Parent directories are created if needed. Pass None to disable file logging. Omit to leave unchanged. File logging is disabled by default.
logging_file_formatstr, optional: Format string for the file handler.
logging_file_datefmtstr, optional: Date/time format for the file handler.
auth_save_tokenbool, optional: Default for livef1.login(): save the F1 account token to disk. Set to False to keep it in memory only.
auth_token_pathstr or pathlib.Path, optional: Default for livef1.login(): where the token is saved. If not set, LIVEF1_TOKEN_PATH from the environment or the .env file is used, else ~/.livef1/f1tv_auth_token.json.
auth_env_pathstr or pathlib.Path, optional: Default for livef1.login(): the .env file the F1 account credentials are read from and saved to. If not set, the first .env in the working directory or one of its parents is used, else .env in the working directory.

Examples

>>> import livef1
>>> # Console only (default) — safe for Lambda / read-only filesystems
>>> livef1.configure(log_level="DEBUG")
>>> # Enable file logging at a writable path
>>> livef1.configure(logging_file_path="/tmp/livef1.log")
>>> # Custom formats
>>> livef1.configure(
...     logging_stream_format="%(levelname)s | %(message)s",
...     logging_file_path="logs/livef1.log",
...     logging_file_format="%(asctime)s %(levelname)s %(message)s",
... )
>>> # Keep the F1 account token in memory only
>>> livef1.configure(auth_save_token=False)

livef1.get_meeting(season: int, meeting_identifier: str = None, meeting_key: int = None, meeting_offname: str = None) → Meeting[source]#

Retrieve data for a specific meeting in a given season.

Parameters:

seasonint

The year of the season to retrieve the meeting from.

meeting_identifierstr

The identifier (e.g., circuit name, grand prix name) of the meeting. The identifier is going to be searched in the season’s meeting table columns: - “Meeting Official Name” - “Meeting Name” - “Circuit Short Name” Therefore, it is suggested to use keywords that is distinguishable among meetings.

Another suggestion is using circuit names for querying.

meeting_keyint

The key of the meeting to get the desired meeting whose key is matching.

Returns:

Meeting: A Meeting object containing sessions and metadata for the specified meeting.

Raises:

livef1Exception: If the meeting cannot be found based on the provided parameters.

livef1.get_season(season: int) → Season[source]#

Retrieve data for a specified Formula 1 season.

Parameters:

seasonint: The year of the season to retrieve.

Returns:

Season: A Season object containing all meetings and sessions for the specified year.

Raises:

livef1Exception: If no data is available for the specified season.

livef1.get_session(season: int, meeting_identifier: str = None, session_identifier: str = None, meeting_key: int = None, session_key: int = None) → Session[source]#

Retrieve data for a specific session within a meeting and season.

Parameters:

seasonint: The year of the season.
meeting_identifierstr: The identifier (e.g., circuit name, grand prix name) of the meeting. The identifier is going to be searched in the season’s meeting table columns: - “Meeting Official Name” - “Meeting Name” - “Circuit Short Name” Therefore, it is suggested to use keywords that is distinguishable among meetings. Another suggestion is using circuit names for querying.
meeting_keyint: The key of the meeting to get the desired meeting whose key is matching.
session_identifierstr: The identifier of the session (e.g., “Practice 1”, “Qualifying”). The identifier is going to be searched in the meeting’s sessions table.
session_keyint: The key of the session to get the desired session whose key is matching.

Returns:

Session: A Session object containing data about the specified session.

Raises:

livef1Exception: If the session cannot be found based on the provided parameters.

livef1.login(username: str = None, password: str = None, *, force: bool = False, save_token: bool = None, token_path=None, env_path=None) → F1Token[source]#

A saved token that has not expired is reused without signing in, unless force is True.

Parameters:

username, passwordstr, optional: F1 account credentials. If omitted, F1_USERNAME and F1_PASSWORD are read from the environment or from env_path. If they are still missing, the user is prompted and the entered values are saved to env_path after a successful sign-in.
forcebool, optional: Sign in again even if a valid token exists. Default is False.
save_tokenbool, optional: Save the token to token_path. If False, the token is kept in memory only. Default is True.
token_pathstr or pathlib.Path, optional: Where the token is saved. If given, the absolute path is also saved as LIVEF1_TOKEN_PATH in env_path, so later runs find the token without passing it again. Default is LIVEF1_TOKEN_PATH from the environment or env_path, else ~/.livef1/f1tv_auth_token.json.
env_pathstr or pathlib.Path, optional: The .env file credentials are read from and saved to. Default is the first .env in the current working directory or one of its parents, else .env in the current working directory.
Defaults of ``save_token``, ``token_path`` and ``env_path`` can be set
with :func:`livef1.configure`.

Returns:

F1Token: The live timing token.

Raises:

AuthenticationError: If no credentials are available or the sign-in fails.

Examples

>>> import livef1
>>> livef1.login()  # .env, environment or prompt
>>> livef1.login(force=True, save_token=False)

livef1.logout(token_path=None)[source]#

Forget the live timing token, in memory and on disk.

The credentials in the .env file are kept.

Parameters:

token_pathstr or pathlib.Path, optional: The saved token to delete. Default is the configured token path.

livef1.set_log_level(level)[source]#

Set the logging level for the livef1 logger.

Parameters:

levelUnion[str, int]: The logging level to set. Can be either a string ('DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL') or the corresponding integer value.

Examples

>>> set_log_level('DEBUG')
>>> set_log_level(logging.INFO)