FastF1 变更日志全解读从 v3.8.0 到 v3.9.0 的 API 演进、弃用清理与数据可靠性修复【免费下载链接】Fast-F1FastF1 is a python package for accessing and analyzing Formula 1 results, schedules, timing data and telemetry项目地址: https://gitcode.com/GitHub_Trending/fa/Fast-F1FastF1 是用于访问和分析 F1 比赛结果、赛程、计时数据与遥测数据的 Python 包。本文基于仓库内 docs/changelog/current.rst该文件被 docs/changelog/index.rst 通过.. include::引入发布说明页面对 v3.8.0 至 v3.9.0 五个版本的全部变更逐条展开并结合源码实现讲解其底层原理。读完本文你将掌握这些版本对Session.results、异常体系、fastf1.utils与EventSchedule等核心 API 的具体影响以及升级迁移时需要注意的每一项改动。v3.9.0开发中API 清理与排位赛结果行为变更v3.9.0 目前标记为(in development)尚未正式发布但变更方向已经明确一是彻底移除长期弃用的 API二是修正Session.results在排位赛场景下的数据处理逻辑三是开启新一轮弃用。移除fastf1.utils.delta_timefastf1.utils.delta_time函数被正式移除。该函数自 v3.0.0 起即被弃用原因是它会产生不准确的结果对应 issue #884。从当前源码搜索看fastf1/utils.py与整个fastf1包中已不存在delta_time的定义使用它会直接抛出AttributeError。如果代码中仍引用该函数必须改用基于Laps与Telemetry对象计算的替代方案。行为变更Qualifying / Sprint Qualifying 的Session.results这是 v3.9.0 最重要的功能性改动涉及两类调整未通过 107% 规则的车手其 Q1 最佳成绩现在会保留在结果中。旧行为下这些车手的时间会被从结果中排除新行为则完整保留 Q1 时间为数据分析提供更完整的信息。ClassifiedPosition列会被填充。Q1 即被淘汰的车手该列取值被设为字符串N表示 Not Classified旧行为下该列完全不被使用。该逻辑在源码中有两处体现。一处是 fastf1/core.py 中基于圈速计算排位赛结果的_calculate_qualifying_results# augment not classified based on 107% rule fastest_q1 quali_results[Q1].min() eliminated quali_results[Q2].isna() nc (quali_results[Q1] (fastest_q1 * 1.07)) eliminated c_pos quali_results[Position].astype(str) c_pos.loc[nc] N quali_results[ClassifiedPosition] c_pos另一处在 fastf1/core.py 的结果加载路径中当self.name Qualifying时执行同样的 107% 规则判定注释明确说明old Ergast API does not provide this info。变更日志指出新行为部分源于 Jolpica-F1 API 返回数据的改变同时使返回结果与文档中早已描述的行为保持一致数据信息量也更丰富。弃用fastf1.utils三个解析辅助函数fastf1.utils.recursive_dict_get、fastf1.utils.to_datetime、fastf1.utils.to_timedelta被标记为弃用#884。这三个函数从未打算成为公共 API 的一部分其实现在 v3.9.0 中被迁移至内部模块 fastf1/internals/parsing_helpers.py。当前 fastf1/utils.py 的模块头注释明确写道The functions in this module were never intended to be part of the public API; see issue #884 for more details. They remain importable for backwards compatibility but emit a FutureWarning and forward to the implementations in fastf1._utils.公共名称recursive_dict_get、to_timedelta、to_datetime继续可用但它们现在只是转发到内部实现的薄包装thin wrapper每次调用都会通过warnings.warn(..., FutureWarning)发出弃用警告源码中实际使用FutureWarning类别并将在未来版本中移除。新的内部实现保留了原行为to_timedelta支持24.3564、36:54、8:45:46等灵活的时间字符串格式1 至 6 位小数精度to_datetime支持2020-12-13T13:27:15.320000Z形式的日期字符串可选尾随Z可选毫秒/微秒精度解析失败时返回None并记录 debug 日志。迁移建议时间解析可改用pandas.to_timedelta/pandas.to_datetime或直接使用内部模块fastf1.internals.parsing_helpers注意内部模块不保证 API 稳定性。弃用get_event_by_round的round关键字参数EventSchedule.get_event_by_round的round关键字参数被弃用#890应在代码中改用round_number。源码 fastf1/events.py 的实现展示了完整的迁移约束传入round...时发出FutureWarning若同时传入round与round_number直接抛出ValueErrorCannot pass both...不传任何参数时抛出ValueErrorround_number 0时抛出ValueErrorCannot get testing event by round number!找不到对应轮次时抛出ValueErrorInvalid round: ...。仓库中的测试 fastf1/tests/test_events.py 对上述行为做了完整覆盖包括test_event_schedule_get_event_by_round_deprecated_kwarg验证旧参数仍可用但触发警告、同时传两个参数会报错等场景。import fastf1 schedule fastf1.get_event_schedule(2025) event schedule.get_event_by_round(round_number1) # 新用法 # 旧用法 schedule.get_event_by_round(round1) 已弃用新特性练习赛结果现在包含Time与PositionSessionResults现在为练习赛Practice 1、Practice 2、Practice 3提供Time最佳圈速和Position两列。此前这两列在练习赛中恒为NaT/NaN。底层实现是 fastf1/core.py 中的_calculate_practice_like_session_results当结果数据缺失且满足self.name in self._PRACTICE_LIKE_SESSIONS即 Practice 1/2/3定义见 fastf1/core.py时该方法从已加载的圈速数据中按车手分组取LapTime最小值重命名为Time并排序生成Positionbest_laps ( self._laps.loc[ ~self._laps[LapTime].isna() ~self._laps[Deleted] ] .groupby(DriverNumber) .agg({LapTime: min}) .rename(columns{LapTime: Time}) .sort_values(byTime) .reset_index() ) best_laps[Position] (best_laps.index 1).astype(float64)注意该方法依赖self.laps[Deleted]的布尔信息若未加载 race control messages会输出警告missing information about deleted laps。获取练习赛结果的示例session fastf1.get_session(2026, 1, FP1) session.load() print(session.results[[DriverNumber, Time, Position]])v3.8.3三个数据可靠性修复v3.8.3 于 2026 年 4 月 29 日发布是当前最新的稳定版本集中修复了三个数据质量问题修复未发车车手被错误生成不存在的首圈#899此前部分未参加发车的车手会被错误添加一个实际不存在的第一圈该问题在 2026 年中国大奖赛中被观察到。修复开赛阶段轮胎数据延迟导致部分圈速缺少轮胎数据#893当源头轮胎数据在 session 开始时延迟到达时部分圈次的轮胎数据会缺失该问题在 2018 年阿塞拜疆大奖赛中被观察到。修复支援赛support race车手数据意外污染 F1 车手数据#908由 Casper-Guo 贡献在少数边界场景下来自支援赛的异常车手数据会混入 F1 车手列表与结果数据。v3.8.2撞车圈去重与空时间戳处理v3.8.2 于 2026 年 3 月 29 日发布包含两项修复修复撞车圈crash lap被重复添加#852由 sheehanr 贡献当圈速数据已加载、随后又单独加载遥测数据时撞车圈会被重复计入。这一交互问题提醒用户注意load()各数据块之间的加载顺序与缓存联动。干净处理 Jolpica-F1 API 响应中的空时间戳#868面对 API 返回的空时间戳字段FastF1 现在能优雅处理不再产生解析异常。v3.8.12026 季前测试支持v3.8.1 于 2026 年 2 月 11 日发布内容是为 2026 年季前测试Pre-Season Testing提供适配补丁确保get_testing_event/get_testing_session相关能力在新赛季测试阶段可用。v3.8.0依赖升级、异常体系重构与绘图常量自动生成v3.8.0 于 2026 年 2 月 10 日发布是这五个版本中改动面最大的一个涵盖依赖、异常体系、绘图与多项修复。依赖变更Python 3.9 支持终止Pydantic 加入Python 最低版本从 3.9 提升至 3.103.9 不再受支持。新增依赖 Pydantic用于数据模型校验。部分核心依赖的最低版本要求提升与 requirements/minver.txt 记录一致依赖最低版本v3.8.0 起matplotlib 3.8.0numpy 1.26.0pandas 2.1.1requests 2.30.0scipy 1.11.0升级时请确保环境满足上述版本约束。新子模块fastf1.exceptions统一的公共异常入口新的子模块 fastf1/exceptions.py 成为所有公共自定义异常的唯一入口未来新增异常也会集中于此。该模块内部还通过模块头注释说明了 FastF1 的异常设计哲学接口型代码直接抛出异常数据处理型代码采用尽可能优雅降级、把错误转成警告的策略而继承自FastF1CriticalError的异常如RateLimitExceededError属于不可恢复错误必须穿透 catch-all 错误处理直接抛给用户。该模块当前的公共异常类包括异常继承关系触发场景DataNotLoadedErrorException访问尚未加载的数据ErgastErrorExceptionErgast API 错误基类ErgastJsonErrorErgastError服务器响应无法解析ErgastInvalidRequestErrorErgastError请求被服务器拒绝NoLapDataErrorExceptionAPI 请求成功但无可用数据FuzzyMatchErrorValueError模糊匹配置信度不足FastF1CriticalErrorRuntimeError不可恢复内部错误基类RateLimitExceededErrorFastF1CriticalError任一 API 触发硬性速率限制弃用异常必须从fastf1.exceptions导入v3.8.0 同步开启了三个异常导入路径的弃用从fastf1.ergast.interface导入ErgastError、ErgastJsonError、ErgastInvalidRequestError已弃用从fastf1.core导入NoLapDataError、DataNotLoadedError、InvalidSessionError已弃用从fastf1顶层导入RateLimitExceededError已弃用。其中InvalidSessionError情况特殊它实际上已不再被使用fastf1/exceptions.py 中标注TODO: remove in v3.11目前通过模块级__getattr__返回内部_InvalidSessionError并发出弃用警告计划在 v3.11 移除。迁移示例# 旧写法已弃用 from fastf1.core import DataNotLoadedError, NoLapDataError from fastf1.ergast.interface import ErgastError from fastf1 import RateLimitExceededError # 新写法统一从 fastf1.exceptions 导入 from fastf1.exceptions import ( DataNotLoadedError, ErgastError, NoLapDataError, RateLimitExceededError, )Bug 修复防止支援赛车手混入车手列表与结果数据#836此前在少数边界场景下由于源头数据异常支援赛车手会被错误包含进 F1 车手列表与结果数据。RateLimitExceededError现在会被正确抛出#748、#842此前该异常在内部 catch-all 错误处理中被吞掉导致用户无法感知速率限制修复后它会以FastF1CriticalError的语义直接抛给调用方便于用户实现重试或限流逻辑from fastf1.exceptions import RateLimitExceededError try: session.load() except RateLimitExceededError: print(触发了 API 硬性速率限制请稍后重试。)新特性速度陷阱值自动填充当速度陷阱speed trap数据缺失时FastF1 现在会尽可能自动填充#834。实现位于 fastf1/core.py针对每个车手对SpeedI1、SpeedI2、SpeedST使用前向填充ffill前提是该圈不是 FastF1 自动生成的圈、且未处于红旗TrackStatus 不含 5状态下终点线速度陷阱SpeedFL的填充额外要求该圈没有进站PitInTime为空。此修复针对的是 API 数据会跳过连续等价值的问题#775。新特性车队名称/颜色常量的自动生成与 2026 赛季常量自动生成常量作为兜底方案#848fastf1.plotting子模块完整功能依赖车队名称与颜色常量。现在当遇到车队名称变更、或需要绘制 FastF1 尚未内置常量的未来赛季数据时FastF1 会基于 F1 API 返回的数据自动生成常量。注意自动生成的车队名称常量可能不完美且此时所有配色方案都会跟随 official 色系。2026 赛季车队名称与颜色常量已初步加入可在 fastf1/plotting/constants.json 中查看后续赛季开始阶段可能会继续微调以更好还原车队品牌形象并使调色板更易区分。自动生成的触发与警告逻辑在 fastf1/plotting/_backend.pywarnings.warn( fNo built-in team name/color constants for {year}. fUpdate FastF1 for official values. fUsing auto-generated names/colors (may be inaccurate). fAll color schemes will follow the official scheme. )也就是说绘图时如果收到 No built-in team name/color constants 警告说明当前赛季常量尚未内置正在使用 API 数据自动生成的近似值升级 FastF1 或等待常量更新可消除该警告。升级迁移要点速查FastF1 的弃用策略在变更日志末尾有明确注释弃用的 API 会在弃用两个次要版本后移除Deprecated API is removed two minor releases after its deprecation.。基于 v3.8.0 至 v3.9.0 的全部变更升级到 v3.9.x 时建议按以下清单检查代码删除或替换fastf1.utils.delta_time调用v3.9.0 已移除直接报错将schedule.get_event_by_round(roundN)改为get_event_by_round(round_numberN)不再依赖fastf1.utils.recursive_dict_get / to_datetime / to_timedelta改用pandas等价函数或内部模块后者需自行承担 API 变动风险将所有异常导入迁移到fastf1.exceptionsErgastError、ErgastJsonError、ErgastInvalidRequestError、NoLapDataError、DataNotLoadedError、RateLimitExceededError等确认运行环境 Python 3.10且 matplotlib / numpy / pandas / requests / scipy 满足 v3.8.0 的最低版本要求关注排位赛结果语义变化107% 规则淘汰车手的 Q1 时间现在保留在Session.results中ClassifiedPosition会以N标记未分类车手练习赛场景可直接使用session.results[[Time, Position]]获取最佳圈速与排序。以上变更的原始来源为 docs/changelog/current.rst涉及的具体实现可进一步阅读 docs/api_reference/exceptions.rst、docs/api_reference/events.rst 与 docs/api_reference/utils.rst 等 API 参考文档以及本文引用的各源码文件与 fastf1/tests 下的对应测试用例以在升级前完成完整的兼容性验证。【免费下载链接】Fast-F1FastF1 is a python package for accessing and analyzing Formula 1 results, schedules, timing data and telemetry项目地址: https://gitcode.com/GitHub_Trending/fa/Fast-F1创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考