## File: README.md
A python package for accessing and analyzing Formula 1 results,
schedules, timing data and telemetry.
## Main Features
- Access to F1 timing data, telemetry, sessions results and more
- Full support for the Ergast compatible [jolpica-f1](https://github.com/jolpica/jolpica-f1/blob/main/docs/README.md) API to access current and
historical F1 data
- All data is provided in the form of extended Pandas DataFrames to make
working with the data easy while having powerful tools available
- Adds custom functions to the Pandas objects specifically to make working
with F1 data quick and simple
- Integration with Matplotlib to facilitate data visualization
- Implements caching for all API requests to speed up your scripts
## Installation
It is recommended to install FastF1 using `pip`:
```commandline
pip install fastf1
```
Alternatively, a wheel or a source distribution can be downloaded from Pypi.
You can also install using `conda`:
```commandline
conda install -c conda-forge fastf1
```
#### Installation in Pyodide, JupyterLite and other WASM-based environments
FastF1 should be mostly compatible with Pyodide and other WASM-based
environments, although this is not extensively tested. Currently, the
installation and usage require some additional steps. You can find more
information and a guide in
[this external repository](https://github.com/f1datajunkie/jupyterlite-fastf1)
and the discussion in [this issue](https://github.com/theOehrly/Fast-F1/issues/667).
### Third-party packages
- R package that wraps FastF1: https://cran.r-project.org/package=f1dataR
Third-party packages are not directly related to the FastF1 project. Questions
and suggestions regarding these packages need to be directed at their
respective maintainers.
## Documentation
The official documentation can be found here:
[docs.fastf1.dev](https://docs.fastf1.dev)
## Supporting the Project
If you want to support the continuous development of FastF1, you can sponsor me
on GitHub or buy me a coffee.
https://github.com/sponsors/theOehrly
[](https://www.buymeacoffee.com/fastf1)
## Notice
FastF1 and this website are unofficial and are not associated in any way with
the Formula 1 companies. F1, FORMULA ONE, FORMULA 1, FIA FORMULA ONE WORLD
CHAMPIONSHIP, GRAND PRIX and related marks are trade marks of Formula One
Licensing B.V.
---
## File: docs/contributing/coding_guide.rst
.. _pr-guidelines:
***********************
Pull request guidelines
***********************
Pull requests (PRs) are the mechanism for contributing to FastF1s code and
documentation.
Summary for PR authors
======================
.. note::
* We value contributions from people with all levels of experience. In
particular if this is your first PR not everything has to be perfect.
We'll guide you through the PR process.
* Nevertheless, try to follow the guidelines below as well as you can to
help make the PR process quick and smooth.
* Be patient with reviewers. We try our best to respond quickly, but we
have limited bandwidth. If there is no feedback within a couple of days,
please ping us by posting a comment to your PR.
* Do not submit fully AI generated pull requests. Please read the :ref:`ai-policy`.
When making a PR, pay attention to:
.. rst-class:: checklist
* Adhere to the :ref:`coding_guidelines`.
* Update the :ref:`documentation ` if necessary.
* Aim at making the PR as "ready-to-go" as you can. This helps to speed up
the review process.
* It is ok to open incomplete or work-in-progress PRs if you need help or
feedback from the developers. You may mark these as
`draft pull requests `_
on GitHub.
* When updating your PR, instead of adding new commits to fix something, please
consider amending your initial commit(s) to keep the history clean.
You can achieve this using
.. code-block:: bash
git commit --amend --no-edit
git push [your-remote-repo] [your-branch] --force-with-lease
See also :ref:`contributing` for how to make a PR.
.. _pr-guidelines-details:
Detailed guidelines
===================
.. _pr-documentation:
Documentation
-------------
* Every new feature should be documented. If it's a new module, don't
forget to add a new rst file to the API docs.
* Each high-level function should have a small example in
the ``Examples`` section of the docstring. This should be as simple as
possible to demonstrate the method. More complex examples should go into
a dedicated example file in the :file:`examples` directory, which will be
rendered to the examples gallery in the documentation.
* Build the docs and make sure all formatting warnings are addressed.
* See :ref:`documenting-fastf1` for our documentation style guide.
* If your change is a major new feature, update
:file:`docs/changelog.rst`.
.. _pr-automated-tests:
Automated tests
---------------
Whenever a pull request is created or updated, various automated test tools
will run on all supported versions of Python.
Make sure that all test are passing. (All checks are listed at the bottom of
the GitHub page of your pull request)
---
## File: docs/contributing/contributing.rst
.. _contributing:
============
Contributing
============
The community around FastF1 is slowly building and everyone is welcome to
contribute to the project.
.. note::
Before making contributions to FastF1, please read the :ref:`ai-policy`.
Submitting a bug report
=======================
If you find a bug in the code or documentation, do not hesitate to open a
new issue in the `issue section `_
on Github. You are also welcome to post feature requests or pull requests.
If you have more general questions or problems that likely are not caused by
a bug in FastF1, you can open a new
`discussion `_ instead.
If you are reporting a bug, please do your best to include the following:
- A short, top-level summary of the bug. In most cases, this should be 1-2
sentences.
- A short, self-contained code snippet to reproduce the bug, ideally allowing
a simple copy and paste to reproduce. Please do your best to reduce the code
snippet to the minimum required.
- The actual outcome of the code snippet.
- The expected outcome of the code snippet.
- The FastF1 version and Python version that you are using.
You can grab the version with the following commands::
>>> import fastf1
>>> fastf1.__version__ # doctest: +SKIP
'2.2.1'
>>> import platform
>>> platform.python_version() # doctest: +SKIP
'3.9.2'
We have preloaded the issue creation page with a Markdown template that you
can use to organize this information.
Thank you for your help in keeping bug reports complete, targeted and
descriptive.
Requesting a new feature
========================
Please post feature requests in the
`issue section `_ on Github.
Since FastF1 is an open source project with limited resources, you are
encouraged to also participate in the implementation as much as you can.
.. _contributing-code:
Contributing code
=================
.. _how-to-contribute:
How to contribute
-----------------
The preferred way to contribute to FastF1 is to fork the `main
repository `__ on GitHub,
then submit a "pull request" (PR).
A brief overview is:
1. `Create an account `_ on GitHub if you do not
already have one.
2. Fork the `project repository `_:
click on the 'Fork' button near the top of the page. This creates a copy of
the code under your account on the GitHub server.
3. Clone this copy to your local disk::
git clone https://github.com//Fast-F1.git
4. Enter the directory and install the local version of FastF1.
See :ref:`installing_for_devs` for instructions
5. Create a branch to hold your changes::
git checkout -b my-feature origin/main
and start making changes. Never work in the ``main`` branch!
6. Work on this copy, on your computer, using Git to do the version control.
When you're done editing e.g., ``fastf1/core.py``, do::
git add fastf1/core.py
git commit
to record your changes in Git, then push them to GitHub with::
git push -u origin my-feature
Finally, go to the web page of your fork of the FastF1 repo, and click
'Pull request' to send your changes to the maintainer for review.
.. seealso::
* `Git documentation `_
* `Git-Contributing to a Project `_
* `Introduction to GitHub `_
Contributing pull requests
--------------------------
It is recommended to check that your contribution complies with the following
rules before submitting a pull request:
* If your pull request addresses an issue, please use the title to describe the
issue and mention the issue number in the pull request description to ensure
that a link is created to the original issue.
* All public methods should have informative docstrings with sample usage when
appropriate. Use the `google docstring standard
`_.
* Formatting should follow the recommendations of PEP8_, as enforced by
ruff_. The maximum line length for all changed lines is 79 characters.
You can check code style compliance from the command line with ::
python -m pip install ruff
ruff check .
or your editor may provide integration with it. The above command will not
flag lines that are too long!
Ruff will also be run before each commit if you have the pre-commit hooks
installed (see :ref:`install_pre_commit`).
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
.. _ruff: https://docs.astral.sh/ruff/
* Changes (both new features and bugfixes) should have good test coverage. See
:ref:`testing` for more details.
* Import the following modules using the standard scipy conventions::
import numpy as np
import pandas as pd
import matplotlib as mpl
import matplotlib.pyplot as plt
* If your change is a major new feature, add an entry to the ``Changelog``
section by editing ``docs/changelog.rst``
.. note::
The current state of the FastF1 code base is not compliant with all
of those guidelines, but we expect that enforcing those constraints on all
new contributions will move the overall code base quality in the right
direction.
.. seealso::
* :ref:`coding_guidelines`
* :ref:`testing`
* :ref:`documenting-fastf1`
.. _contributing_documentation:
Contributing documentation
==========================
You as an end-user of FastF1 can make a valuable contribution because you
more clearly see the potential for improvement than a core developer.
For example, you can:
- Fix a typo
- Clarify a docstring
- Write or update an :ref:`example plot `
The documentation source files live in the same GitHub repository as the code.
Contributions are proposed and accepted through the pull request process.
For details see :ref:`how-to-contribute`.
If you have trouble getting started, you may instead open an `issue`_
describing the intended improvement.
.. _issue: https://github.com/theOehrly/Fast-F1/issues
.. seealso::
* :ref:`documenting-fastf1`
.. _contributing_gallery_examples:
Contributing examples to the gallery
------------------------------------
FastF1 uses `Sphinx-Gallery `_
to generate a gallery of examples. The examples gallery is generated from the
files located in the :file:`examples` folder. To add a new gallery example,
create a new python file in this directory. The file should contain all the
code required to plot the examples. Check out the documentation of
Sphinx-Gallery to find out how to format your example code to include headings,
sections and explanatory text for your example.
.. _coding_guidelines:
Coding guidelines
=================
Supported versions of Python and dependencies
---------------------------------------------
This project supports:
- All minor versions of Python released 42 months prior to the project, and at
minimum the two latest minor versions.
- All minor versions of Numpy, Pandas and Matplotlib released in the 24 months
prior to the project, and at minimum the last three minor versions.
- For other dependencies: As a guideline, this project will try to support all
minor versions initially released in the 12 months prior to our planned
release date or the oldest that supports our minimum Python. We will only
bump these dependencies as we need new features or the old versions are no
longer compatible with other minimum version requirements of this project.
These guidelines are based on `NEP 29`__ .
__ https://numpy.org/neps/nep-0029-deprecation_policy.html
API changes
-----------
API consistency and stability are of great value. Therefore, API changes
(e.g. signature changes, behavior changes, removals) will only be conducted
if the added benefit is worth the user effort for adapting.
API changes in FastF1 have to be performed following the deprecation process
below, except in very rare circumstances as deemed necessary by the developers.
This ensures that users are notified before the change will take effect and thus
prevents unexpected breaking of code.
Note that FastF1 often needs to be adapted to changes in external APIs which
may come without prior warning. To be able to efficiently keep up with these
external changes, it can be necessary to make changes to FastF1 on shorter
notice than described below. In general, breaking changes and deprecations
should be avoided if possible and users should be given prior warnings and as
much time as possible to adapt.
Rules
~~~~~
- Deprecations are targeted at the next minor release (e.g. 3.x)
- Deprecated API is generally removed two minor releases
after introduction of the deprecation. Longer deprecations can be imposed by
core developers on a case-by-case basis to give more time for the transition
- The old API must remain fully functional during the deprecation period
- If alternatives to the deprecated API exist, they should be available
during the deprecation period
Introducing
~~~~~~~~~~~
1. Announce the deprecation in the changelog
:file:`docs/changelog.rst` (reference your pull request as well)
2. If possible, issue a warning when the deprecated
API is used, using the python `warnings` module. The correct warning levels
are:
- `DeprecationWarning` for the first minor release where the deprecation is
announced. These warnings are mostly not shown to end users by default
(depending on how a function is called) but are shown to developers.
- `FutureWarning` starting from the second minor release where the
deprecation is announced. These warnings are always shown to end users
and developers.
Expiring
~~~~~~~~
1. Announce the deprecation in the changelog
:file:`docs/changelog.rst` (reference your pull request as well)
For the content, you can usually copy the deprecation notice
and adapt it slightly.
2. Change the code functionality and remove any related deprecation warnings.
Adding new API
--------------
Every new function, parameter and attribute that is not explicitly marked as
private (i.e., starts with an underscore) becomes part of FastF1's public
API. As discussed above, changing the existing API is cumbersome. Therefore,
take particular care when adding new API:
- Mark helper functions and internal attributes as private by prefixing them
with an underscore.
- Carefully think about good names for your functions and variables.
- Try to adopt patterns and naming conventions from existing parts of the
FastF1 API.
- Consider making as many arguments keyword-only as possible. See also
`API Evolution the Right Way -- Add Parameters Compatibly`__.
__ https://emptysqua.re/blog/api-evolution-the-right-way/#adding-parameters
New modules and files: installation
-----------------------------------
* If you have added new files or directories, or reorganized existing
ones, make sure the new files are included in the match patterns in
in *packages* in :file:`setup.cfg`.
.. _using_logging:
Using logging for debug messages
--------------------------------
FastF1 uses a logging system that is based on the standard Python `logging`
library to write verbose warnings, information, and debug messages.
Please use it! In all those places you write `print` calls to do your
debugging, try using `logger.debug` instead!
FastF1 creates one main logger and then uses child loggers for each module.
To include logging in your module, at the top of the module, you need to add
``from fastf1.logger import get_logger``. Then calls in your code like::
# set up the logger once (!)
logger = get_logger(__name__)
# code
logger.info('Here is some information')
logger.debug('Here is some more detailed information')
# more code
will log to a logger named ``fastf1.yourmodulename``.
Which logging level to use?
~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are five levels at which you can emit messages.
- `logger.critical` and `logger.error` are really only there for errors that
will end the use of the library but not kill the interpreter.
- `logger.warning` is used to warn the user, for example, if an operation has
failed gracefully, if some action is likely to have unintended side-effects
or similar.
- `logger.info` is for information that the user may want to know if the
program behaves oddly. For instance, if a driver did not participate in a
session, some data cannot be loaded for this specific driver. But FastF1 can
still be used normally with data of all other drivers in this session.
- `logger.debug` is the least likely to be displayed, and hence can be the
most verbose. Information that is usually only required for development
and debugging of FastF1 should be logged here.
By default, in FastF1, logging displays all log messages at levels higher than
``logging.INFO`` to `sys.stderr`.
.. _logging tutorial: https://docs.python.org/3/howto/logging.html#logging-basic-tutorial
Allowing optional functions to fail gracefully
----------------------------------------------
FastF1 processes lots of data that may change unexpectedly, contain unknown
values or that is not always available. Of course, the best way to deal with
this is to write code that is as robust as possible. But of course, it is not
always possible to foresee what unexpected data your code might need to deal
with. In some cases, FastF1 cannot work without some specific data being
processed correctly. But in other cases, FastF1 can still be used with limited
functionality if we prevent it from crashing when such an error is encountered.
Examples for such cases are:
- loading optional data: weather data, telemetry, ...
- doing additional (cross) validation of data
- applying corrections to improve the accuracy of data
- ...
If such a task fails, we want FastF1 to show a warning to the user. But
especially if such an error is encountered during data loading, it should not
crash FastF1 and make the whole session unavailable to the user. Loading
incomplete data is always preferred over loading no data at all.
To deal with this, FastF1 provides a special function decorator called
:func:`fastf1.logger.soft_exceptions` that can be used as follows::
from fastf1.logger import soft_exceptions
@soft_exceptions(descr_name="optional data processing",
msg="Failed to do some optional data processing",
logger=logger)
def _optional_data_loading():
...
return
The basic functionality of this decorator is to wrap a one big
`try: ... except Exception: ...` clause around the function call.
But additionally, if the function call fails, the `msg` is shown to the user,
using the logging level `WARNING`. The traceback is logged with the logging
level `DEBUG` and prefaced with the line `"Traceback for failure in
{descr_name}"`.
You need to pass the `logger` for the current module as a third argument to the
decorator.
This catch-all exception handling makes development more difficult, because for
example a debugger won't be able to stop on an unhandled exception. Therefore,
it is possible to easily disable the exception handling for all functions that
are decorated in this way. This is described in detail here:
:ref:`logging`.
---
## File: docs/contributing/devenv_setup.rst
.. _installing_for_devs:
=====================================
Setting up FastF1 for development
=====================================
.. _dev-environment:
Creating a dedicated environment
================================
You should set up a dedicated environment to decouple your FastF1
development from other Python and FastF1 installations on your system.
Here we use python's virtual environment `venv`_, but you may also use others
such as conda.
.. _venv: https://docs.python.org/3/library/venv.html
A new environment can be set up with ::
python -m venv
and activated with one of the following::
source /bin/activate # Linux/macOS
\Scripts\activate.bat # Windows cmd.exe
\Scripts\Activate.ps1 # Windows PowerShell
Whenever you plan to work on FastF1, remember to activate the development
environment in your shell.
Retrieving the latest version of the code
=========================================
FastF1 is hosted at https://github.com/theOehrly/Fast-F1.git.
git clone https://github.com/theOehrly/Fast-F1.git
This will place the sources in a directory :file:`Fast-F1` below your
current working directory.
If you have the proper privileges, you can use ``git@`` instead of
``https://``, which works through the ssh protocol and might be easier to use
if you are using 2-factor authentication.
Installing FastF1 in editable mode
======================================
Install FastF1 in editable mode from the :file:`Fast-F1` directory
using the command ::
python -m pip install -e .
The 'editable/develop mode', builds everything and places links in your Python
environment so that Python will be able to import FastF1 from your
development source directory. This allows you to import your modified version
of FastF1 without re-installing after every change.
.. _install_pre_commit:
Installing additional dependencies for development
==================================================
To install additional dependencies for development and testing run the
following command within the :file:`Fast-F1` directory::
python -m pip install -r requirements/dev.txt
If you also want to build the documentation, you need to install further
additional dependencies::
python -m pip install -r requirements/doc-build.txt
.. _pre_commit_hooks:
Installing pre-commit hooks
===========================
It is recommended to install `pre-commit `_ hooks.
These will automatically check and partially fix code style issues (using the
ruff linter and isort) when you run ``git commit``. The hooks are defined in
the top level ``.pre-commit-config.yaml`` file. To install the hooks ::
pip install pre-commit
pre-commit install
---
## File: docs/contributing/documenting_fastf1.rst
.. _documenting-fastf1:
=====================
Writing documentation
=====================
Getting started
===============
General file structure
----------------------
All documentation is built from the :file:`docs/`. The :file:`docs/`
directory contains configuration files for Sphinx and reStructuredText
(ReST_; ``.rst``) files that are rendered to documentation pages.
Setting up the doc build
------------------------
The documentation for FastF1 is generated from reStructuredText (ReST_)
using the Sphinx_ documentation generation tool.
To build the documentation you will need to
:ref:`set up FastF1 for development `.
Building the docs
-----------------
The documentation sources are found in the :file:`docs/` directory in the trunk.
The configuration file for Sphinx is :file:`docs/conf.py`. It controls which
directories Sphinx parses, how the docs are built, and how the extensions are
used. To build the documentation in html format run the following command
from the :file:`docs/` directory:
.. code:: sh
make html
The documentation build expects the cache directory :file:`doc_cache/` to exist
in the project root.
You will have to create it manually the first time you build the documentation.
The generated documentation can be found in :file:`docs/_build/html` and viewed
in an internet browser by opening the html files. Run the following command
to open the homepage of the documentation build:
.. code:: sh
make show
Writing documentation
---------------------
In general, the style guidelines and formatting conventions described in
https://matplotlib.org/stable/devel/documenting_mpl.html should be applied to
FastF1 as well.
One notable exception is that FastF1 uses the `google docstring standard
`_
instead of the numpydoc format.
.. _ReST: https://docutils.sourceforge.io/rst.html
.. _Sphinx: http://www.sphinx-doc.org
---
## File: docs/contributing/index.rst
.. _developers-guide-index:
############
Contributing
############
Thank you for your interest in helping to improve FastF1! There are various
ways to contribute to FastF1. All of them are super valuable but don't
necessarily require writing code at all. For example:
- contributing to the documentation
- opening new issues for bugs
- requesting new features
- asking for clarification on things you find unclear
- fixing bugs
- writing example scripts for the gallery
.. raw:: html
[Report a bug](contributing.html#submitting-a-bug-report)
[Request a feature](contributing.html#request-a-new-feature)
[Contribute code](contributing.html#contributing-code)
[Write documentation](contributing.html#contributing-documentation)
.. toctree::
:maxdepth: 2
contributing.rst
devenv_setup.rst
testing.rst
documenting_fastf1.rst
coding_guide.rst
ai_policy.rst
**Acknowledgement**: This contribution guide is heavily based on and in large
parts copied over and adapted from Matplotlibs documentation. There's no need
to reinvent the wheel if others have done a great job of explaining things
already.