Fast-F1 v3.0.x 版本全解析默认缓存、Ergast 完整接入与数据解析体系的重构【免费下载链接】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本指南以 Fast-F1 官方变更记录 docs/changelog/v3.0.x.rst 为骨架系统梳理 v3.0.0 到 v3.0.7 八个补丁版本引入的核心能力升级、Bug 修复与破坏性变更。你将掌握缓存机制如何从手动开启变为默认启用并支持离线模式、新 Ergast 接口的完整能力边界、日志体系的统一配置方式以及Laps/Session新增列与方法如Deleted、total_laps、pick_lap在实战中的正确用法同时了解升级到 v3.0 时必须注意的 API 移除清单与迁移路径。v3.0.0一个里程碑式的大版本v3.0.0发布于 2023-05-02是整个 3.0 系列的奠基版本其改动横跨缓存、数据源、日志、Laps 数据结构四大板块几乎所有后续小版本的修复都建立在这一版重构之上。下文按官方 Release Notes 的章节顺序展开。缓存系统默认启用、两级架构与离线模式v3.0.0 最大的体验变化是缓存不再需要手动配置。此前用户必须显式调用Cache.enable_cache()才能开启缓存从 v3.0.0 起缓存默认开启并自动落在操作系统规定的临时目录。从 fastf1/req.py 中Cache类的文档与实现可以确认缓存目录的确定遵循如下优先级显式调用fastf1.Cache.enable_cache(path/to/cache)指定的目录优先级最高环境变量FASTF1_CACHE指定的目录在未调用enable_cache时生效操作系统默认缓存目录Windows%LOCALAPPDATA%\Temp\fastf1macOS~/Library/Caches/fastf1Linux~/.cache/fastf1若~/.cache不存在则回退到~/.fastf1其中enable_cache必须在导入 fastf1 之后、调用任何其他 FastF1 功能之前调用以确保缓存配置正确见 fastf1/req.py 的文档说明。从源码可以印证缓存的实际工作方式分为两个阶段fastf1/req.pyStage 1原始 HTTP 请求缓存。所有 GET/POST 请求经由requests-cache写入 SQLite 数据库fastf1_http_cache.sqlite并采用expire_after12 小时、cache_controlTrue、stale_if_errorTrue等策略fastf1/req.py支持通过缓存控制头定期刷新数据。Stage 2解析结果缓存。api_request_wrapper将解析后的数据以 pickle 形式写入按年/事件/场次组织的目录树文件后缀为.ff1pklfastf1/req.py。由于解析在计算上开销很大Stage 2 能显著加速重复运行的脚本。Cache类的类级 API 在源码中均有对应实现可用的主要方法如下方法功能关键参数与说明Cache.enable_cache(cache_dir, ignore_versionFalse, force_renewFalse, use_requests_cacheTrue)启用/切换缓存目录cache_dir必须已存在ignore_version允许忽略 API 解析器版本不匹配不推荐可能加载不兼容数据force_renew强制重新下载并更新缓存路径支持~与%VAR%展开fastf1/req.pyCache.clear_cache(cache_dirNone, deepFalse)清除全部缓存默认清空默认缓存目录中的所有.ff1pkl文件deepTrue时额外删除 Stage 1 的 SQLite 文件可以无需先启用缓存直接调用fastf1/req.pyCache.offline_mode(enabled)启用/关闭离线模式启用后不再发送任何真实请求只返回缓存数据适合冻结缓存状态或在网络不稳定时使用注意使用自定义缓存目录时须在enable_cache之后调用fastf1/req.pyCache.set_enabled()/Cache.set_disabled()临时启用/禁用缓存用于对特定代码段临时禁用缓存fastf1/req.pyCache.ci_mode(enabled)CI 模式过期缓存也会被复用且禁用 Stage 2 pickle 缓存保证测试可预测、减少并发请求fastf1/req.py两个值得注意的实现细节缓存命中不计入 API 速率限制。_SessionWithRateLimiting通过补丁requests.send对匹配 URL 模式施加限流而_CachedSessionWithRateLimiting以requests_cache.CachedSession为基类fastf1/req.py凡能被缓存直接服务的请求都不会触发限流器。临时错误响应会被过滤。_custom_cache_filter会拦截 Ergast 返回 HTTP 200 但正文含Unable to select database的错误响应避免这类瞬时错误被误缓存fastf1/req.py——这正对应了 v3.0.0 Bug Fixes 中修复特定临时错误响应被缓存的条目。此外v3.0.0 中Cache类本身获得了自定义__repr___MetaCache见 fastf1/req.py直接print(fastf1.Cache)即可看到类似FastF1 cache (size) path的当前缓存状态摘要。Ergast F1 API 完整接入v3.0.0 用全新的完整实现取代了此前功能极其有限的 Ergast 支持新接口具备以下能力全部在官方文档 docs/api_reference/jolpica.rst 中有对应说明支持全部端点Endpoints支持全部查询过滤器Query Filters数据可按 Pandas DataFrame 或原始Raw格式返回支持自动类型转换将字段转为最合适的数据类型复用 FastF1 缓存体系支持结果数量限制与分页result limits and pagination强制执行 Ergast 定义的速率限制且缓存命中的请求不计入限流额度。需要说明的是该模块底层对应的公开 API 后来由 Ergast 迁移至 Jolpica-F1成为其 drop-in 兼容的继任者出于向后兼容模块名fastf1.ergast保持不变但数据实际来源于 Jolpica-F1详见 docs/api_reference/jolpica.rst 的说明。这也解释了 v3.0.0 中同时出现新增 Ergast 完整支持与移除fastf1.ergast.fetch_weekend这两条看似矛盾的记录——前者是面向新接口的完整重写后者是旧接口中不再需要的遗留函数。日志体系重做统一set_log_levelv3.0.0 重新实现了日志系统使所有子模块的日志级别可以通过fastf1.set_log_level统一配置。结合 fastf1/logger.py 的实现可以看到其设计FastF1 所有子模块 logger 都是根 loggerfastf1的子 loggerLoggingManager.get_child见 fastf1/logger.py因此设置根 logger 的 handler 级别即可全局生效set_log_level(level)接受logging模块的级别常量如logging.INFO或字符串如WARNING内部通过logging._nameToLevel将字符串转成数值fastf1/logger.py控制台 handler 默认级别为INFOfastf1/logger.py这与数据加载常耗时数秒、INFO 级别用于输出进度信息的设计意图一致支持通过环境变量FASTF1_DEBUG1或LoggingManager.debug True开启调试模式此时数据加载方法的兜底异常捕获soft_exceptions见 fastf1/logger.py被禁用所有未处理异常都会直接抛出便于开发调试。import fastf1 import logging fastf1.set_log_level(logging.WARNING) # 或 fastf1.set_log_level(WARNING)Laps 与 Session 数据结构增强v3.0.0 对fastf1.core.Laps和fastf1.core.Session的增强是本版本对日常分析工作流影响最深的部分车手退赛时补全最后一圈。当车手在赛道上退赛时一个部分完成的最后一圈partial last lap会被加入Laps并生成对应的Lap对象这让绘制该类圈的遥测数据变得容易。圈速删除标记。加载赛事控制消息race control messages后解析器会识别哪些圈被删除Laps新增Deleted与DeletedReason两列分别标记删除状态与原因。总圈数属性。Session.total_laps提供比赛或冲刺赛sprint的预期总圈数从 fastf1/core.py 可以看到该属性在数据未加载时会通过_get_property_warn_not_loaded返回None并给出警告。排位赛分段。新增Laps.split_qualifying_sessions()可把排位赛圈速拆分为 Q1、Q2、Q3 三个独立的Laps对象若某段被取消则返回Nonefastf1/core.pyq1, q2, q3 laps.split_qualifying_sessions()按圈号选取。新增Laps.pick_lap(lap_number)与Laps.pick_laps(lap_numbers)fastf1/core.py可按圈号便捷选取特定圈。赛道状态数据。Session.track_status暴露赛道状态数据fastf1/core.py同时Telemetry.add_track_status(drop_existingTrue)可将赛道状态信息合并进遥测数据fastf1/core.py便于分析黄旗/红旗等状态对速度的影响。圈速修正。正赛第一圈圈速现在从 Ergast 自动补齐此前缺失车手间每圈的开始/结束时间也被精确对齐消除了此前几十毫秒量级的顺序差异。终点位置与官方分类。Laps/Lap在每圈末尾新增当前Position列SessionResults与DriverResult新增ClassifiedPosition对正赛和冲刺赛列出官方分类的完赛名次或未分类的原因如退赛、被取消资格等。更有意义的对象表示。Session获得自定义__repr__打印对象时会显示年份、轮次、赛事名称与场次名称。赛手结果扩展。SessionResults与DriverResult新增HeadshotURL与CountryCode字段。轮胎配方颜色。fastf1.plotting.COMPOUND_COLORS提供轮胎配方compound颜色映射。在 fastf1/plotting/constants.json 中可以看到各配方色值例如未知测试配方TEST-UNKNOWN的色值为#434649fastf1/plotting/_base.py。事件计划表与场次 API 改进时区感知时间戳事件计划表中的Session*Date从此为时区感知的本地时间戳此前为无时区的本地时间同时新增无时区的 UTC 时间戳Session*DateUtc。两者仅在 backend 为fastf1或f1timing时可用。新增 fallback 后端F1 timing data API 被加入事件计划数据的备选后端issue #260提升了计划数据获取的健壮性。严格搜索fastf1.get_event新增strict_search参数关闭模糊匹配fuzzy matching用于对场次名进行精确匹配。其他值得关注的变更livetiming 客户端支持全部 Python 版本此前该功能被限制在 Python 3.9 及以下v3.0.0 通过将存在兼容问题的python-signalr-client依赖整合进 FastF1 并修复了 Python 3.10 的问题消除了版本上限。conda-forge 安装支持FastF1 现在可通过 conda-forge 渠道安装此变更由 daylinmorgan 贡献。内部类型统一Laps中所有原先为int的列改为float以支持NaN值。性能优化fastf1.api.car_data与fastf1.api.pos_data获得性能提升。破坏性变更与迁移清单升级到 v3.0.0 前必须审查以下不兼容改动行为变化fastf1.utils.to_datetime与fastf1.utils.to_timedelta在字符串无法解析时返回None而不是抛出异常异常处理逻辑需相应调整。冲刺赛的名称统一为Sprint。此前 2021 赛季称为Sprint Qualifying其余赛季为Sprint现在一律为Sprint。移除的 API 元素fastf1.events.Event的属性name、date、gp被移除fastf1.get_session/fastf1.events.get_session不再支持省略identifier参数创建Event对象上述两个函数不再接受event参数统一改用identifierfastf1.core.get_session改用fastf1.get_session与fastf1.core.get_round无替代品被移除Session.load_laps与Session.load_telemetry方法被移除统一走Session.loadSession.weekend属性被移除DriverResult的name、familyname、grid、position、team属性被移除fastf1.core.Driver与fastf1.core.Weekend类被整体移除fastf1.ergast.fetch_weekend被移除。新增的弃用声明fastf1.api模块在未来版本将被视为私有并可能被修改或移除官方建议不要在业务代码中使用该模块若确有需求应在 GitHub 提交 issue 说明。fastf1.utils.delta_time已被标记为弃用因其结果有失准倾向将在未来版本修改或移除。v3.0.1 – v3.0.7补丁版本修复速览版本发布日期核心内容v3.0.12023-05-07修复命令行无法使用 livetiming 客户端的问题即fastf1包作为 CLI 入口时fastf1.livetiming.__main__相关路径不可用的问题v3.0.22023-05-09改进对 Sprint Shootout冲刺排位赛的支持并为其补充场次结果mdsakalu 贡献改善多个内部函数的异常处理v3.0.32023-05-19修复轮胎配方颜色代码格式错误Casper-Guo修复仅出现在 Pandas 1.5.3 及更早版本上、导致 Qualifying 类场次如 Sprint Shootout结果无法计算的 Bugv3.0.42023-06-03为轮胎配方TEST-UNKNOWN补充缺失的颜色Casper-Guo提升依赖timple的最低版本要求v3.0.52023-06-21修复加载历史场次时的报错#400修复圈速未被正确标记为 Personal Best 的 Bug——该问题同时会导致Laps.pick_fastest返回错误的圈#403v3.0.62023-06-21强制从 v3.0.4 及更早版本升级后刷新缓存否则 v3.0.5 的修复在数据已被缓存时不会生效v3.0.72023-07-17修复缺少位置数据时无法加载遥测数据反之亦然的问题#412修复 v3.0.3 引入的 Sprint Shootout 结果加载回归#413为 AlphaTauri 车队的 Ricciardo 补充车手颜色pesaventofilippo见 fastf1/plotting/constants.json其中 v3.0.6 的说明直接指向了缓存体系的一个关键运维事实Stage 2 的 pickle 缓存带有 API 解析器版本号校验Cache._API_CORE_VERSION 15见 fastf1/req.py当版本不匹配时会自动判定缓存不可用并重新下载、更新缓存。因此从旧版本升级后首次运行会自动触发缓存刷新无需手动清缓存若在特殊场景下确需忽略版本不匹配可显式传入ignore_versionTrue官方明确不建议。实战建议v3.0 升级后的标准工作流结合上述变更v3.0 时代推荐的典型使用模式如下import fastf1 import logging # 1. 缓存v3.0 起默认启用无需手动开启 # 如需自定义位置在导入后、其他调用前设置 # fastf1.Cache.enable_cache(/path/to/existing/cache_dir) # 2. 日志统一调整输出级别 fastf1.set_log_level(WARNING) # 3. 离线环境只使用已缓存的数据不发出任何网络请求 # fastf1.Cache.offline_mode(True) # 4. 加载场次注意 v3.0 起统一使用 identifier 参数 session fastf1.get_session(2023, 5, Q) session.load() laps session.laps # 5. 新 API 的使用 fastest laps.pick_fastest() # 依赖正确的 Personal Best 标记v3.0.5 修复 q1, q2, q3 laps.split_qualifying_sessions() # 拆分排位赛三段 lap5 laps.pick_lap(5) # 按圈号选取 print(session.total_laps) # 比赛/冲刺赛预期总圈数 print(fastf1.Cache) # 查看缓存目录与占用自定义 __repr__升级前请对照上文的移除清单全面扫描存量代码重点排查Session.weekend、Driver、Weekend、event参数、to_datetime/to_timedelta异常语义以及冲刺赛名称判断逻辑这几类高频使用点。若需回看早期版本的演进脉络可继续阅读 docs/changelog/previous.rst 与 docs/changelog/index.rst 中收录的历史版本记录。【免费下载链接】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），仅供参考
Fast-F1 v3.0.x 版本全解析默认缓存、Ergast 完整接入与数据解析体系的重构【免费下载链接】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本指南以 Fast-F1 官方变更记录 docs/changelog/v3.0.x.rst 为骨架系统梳理 v3.0.0 到 v3.0.7 八个补丁版本引入的核心能力升级、Bug 修复与破坏性变更。你将掌握缓存机制如何从手动开启变为默认启用并支持离线模式、新 Ergast 接口的完整能力边界、日志体系的统一配置方式以及Laps/Session新增列与方法如Deleted、total_laps、pick_lap在实战中的正确用法同时了解升级到 v3.0 时必须注意的 API 移除清单与迁移路径。v3.0.0一个里程碑式的大版本v3.0.0发布于 2023-05-02是整个 3.0 系列的奠基版本其改动横跨缓存、数据源、日志、Laps 数据结构四大板块几乎所有后续小版本的修复都建立在这一版重构之上。下文按官方 Release Notes 的章节顺序展开。缓存系统默认启用、两级架构与离线模式v3.0.0 最大的体验变化是缓存不再需要手动配置。此前用户必须显式调用Cache.enable_cache()才能开启缓存从 v3.0.0 起缓存默认开启并自动落在操作系统规定的临时目录。从 fastf1/req.py 中Cache类的文档与实现可以确认缓存目录的确定遵循如下优先级显式调用fastf1.Cache.enable_cache(path/to/cache)指定的目录优先级最高环境变量FASTF1_CACHE指定的目录在未调用enable_cache时生效操作系统默认缓存目录Windows%LOCALAPPDATA%\Temp\fastf1macOS~/Library/Caches/fastf1Linux~/.cache/fastf1若~/.cache不存在则回退到~/.fastf1其中enable_cache必须在导入 fastf1 之后、调用任何其他 FastF1 功能之前调用以确保缓存配置正确见 fastf1/req.py 的文档说明。从源码可以印证缓存的实际工作方式分为两个阶段fastf1/req.pyStage 1原始 HTTP 请求缓存。所有 GET/POST 请求经由requests-cache写入 SQLite 数据库fastf1_http_cache.sqlite并采用expire_after12 小时、cache_controlTrue、stale_if_errorTrue等策略fastf1/req.py支持通过缓存控制头定期刷新数据。Stage 2解析结果缓存。api_request_wrapper将解析后的数据以 pickle 形式写入按年/事件/场次组织的目录树文件后缀为.ff1pklfastf1/req.py。由于解析在计算上开销很大Stage 2 能显著加速重复运行的脚本。Cache类的类级 API 在源码中均有对应实现可用的主要方法如下方法功能关键参数与说明Cache.enable_cache(cache_dir, ignore_versionFalse, force_renewFalse, use_requests_cacheTrue)启用/切换缓存目录cache_dir必须已存在ignore_version允许忽略 API 解析器版本不匹配不推荐可能加载不兼容数据force_renew强制重新下载并更新缓存路径支持~与%VAR%展开fastf1/req.pyCache.clear_cache(cache_dirNone, deepFalse)清除全部缓存默认清空默认缓存目录中的所有.ff1pkl文件deepTrue时额外删除 Stage 1 的 SQLite 文件可以无需先启用缓存直接调用fastf1/req.pyCache.offline_mode(enabled)启用/关闭离线模式启用后不再发送任何真实请求只返回缓存数据适合冻结缓存状态或在网络不稳定时使用注意使用自定义缓存目录时须在enable_cache之后调用fastf1/req.pyCache.set_enabled()/Cache.set_disabled()临时启用/禁用缓存用于对特定代码段临时禁用缓存fastf1/req.pyCache.ci_mode(enabled)CI 模式过期缓存也会被复用且禁用 Stage 2 pickle 缓存保证测试可预测、减少并发请求fastf1/req.py两个值得注意的实现细节缓存命中不计入 API 速率限制。_SessionWithRateLimiting通过补丁requests.send对匹配 URL 模式施加限流而_CachedSessionWithRateLimiting以requests_cache.CachedSession为基类fastf1/req.py凡能被缓存直接服务的请求都不会触发限流器。临时错误响应会被过滤。_custom_cache_filter会拦截 Ergast 返回 HTTP 200 但正文含Unable to select database的错误响应避免这类瞬时错误被误缓存fastf1/req.py——这正对应了 v3.0.0 Bug Fixes 中修复特定临时错误响应被缓存的条目。此外v3.0.0 中Cache类本身获得了自定义__repr___MetaCache见 fastf1/req.py直接print(fastf1.Cache)即可看到类似FastF1 cache (size) path的当前缓存状态摘要。Ergast F1 API 完整接入v3.0.0 用全新的完整实现取代了此前功能极其有限的 Ergast 支持新接口具备以下能力全部在官方文档 docs/api_reference/jolpica.rst 中有对应说明支持全部端点Endpoints支持全部查询过滤器Query Filters数据可按 Pandas DataFrame 或原始Raw格式返回支持自动类型转换将字段转为最合适的数据类型复用 FastF1 缓存体系支持结果数量限制与分页result limits and pagination强制执行 Ergast 定义的速率限制且缓存命中的请求不计入限流额度。需要说明的是该模块底层对应的公开 API 后来由 Ergast 迁移至 Jolpica-F1成为其 drop-in 兼容的继任者出于向后兼容模块名fastf1.ergast保持不变但数据实际来源于 Jolpica-F1详见 docs/api_reference/jolpica.rst 的说明。这也解释了 v3.0.0 中同时出现新增 Ergast 完整支持与移除fastf1.ergast.fetch_weekend这两条看似矛盾的记录——前者是面向新接口的完整重写后者是旧接口中不再需要的遗留函数。日志体系重做统一set_log_levelv3.0.0 重新实现了日志系统使所有子模块的日志级别可以通过fastf1.set_log_level统一配置。结合 fastf1/logger.py 的实现可以看到其设计FastF1 所有子模块 logger 都是根 loggerfastf1的子 loggerLoggingManager.get_child见 fastf1/logger.py因此设置根 logger 的 handler 级别即可全局生效set_log_level(level)接受logging模块的级别常量如logging.INFO或字符串如WARNING内部通过logging._nameToLevel将字符串转成数值fastf1/logger.py控制台 handler 默认级别为INFOfastf1/logger.py这与数据加载常耗时数秒、INFO 级别用于输出进度信息的设计意图一致支持通过环境变量FASTF1_DEBUG1或LoggingManager.debug True开启调试模式此时数据加载方法的兜底异常捕获soft_exceptions见 fastf1/logger.py被禁用所有未处理异常都会直接抛出便于开发调试。import fastf1 import logging fastf1.set_log_level(logging.WARNING) # 或 fastf1.set_log_level(WARNING)Laps 与 Session 数据结构增强v3.0.0 对fastf1.core.Laps和fastf1.core.Session的增强是本版本对日常分析工作流影响最深的部分车手退赛时补全最后一圈。当车手在赛道上退赛时一个部分完成的最后一圈partial last lap会被加入Laps并生成对应的Lap对象这让绘制该类圈的遥测数据变得容易。圈速删除标记。加载赛事控制消息race control messages后解析器会识别哪些圈被删除Laps新增Deleted与DeletedReason两列分别标记删除状态与原因。总圈数属性。Session.total_laps提供比赛或冲刺赛sprint的预期总圈数从 fastf1/core.py 可以看到该属性在数据未加载时会通过_get_property_warn_not_loaded返回None并给出警告。排位赛分段。新增Laps.split_qualifying_sessions()可把排位赛圈速拆分为 Q1、Q2、Q3 三个独立的Laps对象若某段被取消则返回Nonefastf1/core.pyq1, q2, q3 laps.split_qualifying_sessions()按圈号选取。新增Laps.pick_lap(lap_number)与Laps.pick_laps(lap_numbers)fastf1/core.py可按圈号便捷选取特定圈。赛道状态数据。Session.track_status暴露赛道状态数据fastf1/core.py同时Telemetry.add_track_status(drop_existingTrue)可将赛道状态信息合并进遥测数据fastf1/core.py便于分析黄旗/红旗等状态对速度的影响。圈速修正。正赛第一圈圈速现在从 Ergast 自动补齐此前缺失车手间每圈的开始/结束时间也被精确对齐消除了此前几十毫秒量级的顺序差异。终点位置与官方分类。Laps/Lap在每圈末尾新增当前Position列SessionResults与DriverResult新增ClassifiedPosition对正赛和冲刺赛列出官方分类的完赛名次或未分类的原因如退赛、被取消资格等。更有意义的对象表示。Session获得自定义__repr__打印对象时会显示年份、轮次、赛事名称与场次名称。赛手结果扩展。SessionResults与DriverResult新增HeadshotURL与CountryCode字段。轮胎配方颜色。fastf1.plotting.COMPOUND_COLORS提供轮胎配方compound颜色映射。在 fastf1/plotting/constants.json 中可以看到各配方色值例如未知测试配方TEST-UNKNOWN的色值为#434649fastf1/plotting/_base.py。事件计划表与场次 API 改进时区感知时间戳事件计划表中的Session*Date从此为时区感知的本地时间戳此前为无时区的本地时间同时新增无时区的 UTC 时间戳Session*DateUtc。两者仅在 backend 为fastf1或f1timing时可用。新增 fallback 后端F1 timing data API 被加入事件计划数据的备选后端issue #260提升了计划数据获取的健壮性。严格搜索fastf1.get_event新增strict_search参数关闭模糊匹配fuzzy matching用于对场次名进行精确匹配。其他值得关注的变更livetiming 客户端支持全部 Python 版本此前该功能被限制在 Python 3.9 及以下v3.0.0 通过将存在兼容问题的python-signalr-client依赖整合进 FastF1 并修复了 Python 3.10 的问题消除了版本上限。conda-forge 安装支持FastF1 现在可通过 conda-forge 渠道安装此变更由 daylinmorgan 贡献。内部类型统一Laps中所有原先为int的列改为float以支持NaN值。性能优化fastf1.api.car_data与fastf1.api.pos_data获得性能提升。破坏性变更与迁移清单升级到 v3.0.0 前必须审查以下不兼容改动行为变化fastf1.utils.to_datetime与fastf1.utils.to_timedelta在字符串无法解析时返回None而不是抛出异常异常处理逻辑需相应调整。冲刺赛的名称统一为Sprint。此前 2021 赛季称为Sprint Qualifying其余赛季为Sprint现在一律为Sprint。移除的 API 元素fastf1.events.Event的属性name、date、gp被移除fastf1.get_session/fastf1.events.get_session不再支持省略identifier参数创建Event对象上述两个函数不再接受event参数统一改用identifierfastf1.core.get_session改用fastf1.get_session与fastf1.core.get_round无替代品被移除Session.load_laps与Session.load_telemetry方法被移除统一走Session.loadSession.weekend属性被移除DriverResult的name、familyname、grid、position、team属性被移除fastf1.core.Driver与fastf1.core.Weekend类被整体移除fastf1.ergast.fetch_weekend被移除。新增的弃用声明fastf1.api模块在未来版本将被视为私有并可能被修改或移除官方建议不要在业务代码中使用该模块若确有需求应在 GitHub 提交 issue 说明。fastf1.utils.delta_time已被标记为弃用因其结果有失准倾向将在未来版本修改或移除。v3.0.1 – v3.0.7补丁版本修复速览版本发布日期核心内容v3.0.12023-05-07修复命令行无法使用 livetiming 客户端的问题即fastf1包作为 CLI 入口时fastf1.livetiming.__main__相关路径不可用的问题v3.0.22023-05-09改进对 Sprint Shootout冲刺排位赛的支持并为其补充场次结果mdsakalu 贡献改善多个内部函数的异常处理v3.0.32023-05-19修复轮胎配方颜色代码格式错误Casper-Guo修复仅出现在 Pandas 1.5.3 及更早版本上、导致 Qualifying 类场次如 Sprint Shootout结果无法计算的 Bugv3.0.42023-06-03为轮胎配方TEST-UNKNOWN补充缺失的颜色Casper-Guo提升依赖timple的最低版本要求v3.0.52023-06-21修复加载历史场次时的报错#400修复圈速未被正确标记为 Personal Best 的 Bug——该问题同时会导致Laps.pick_fastest返回错误的圈#403v3.0.62023-06-21强制从 v3.0.4 及更早版本升级后刷新缓存否则 v3.0.5 的修复在数据已被缓存时不会生效v3.0.72023-07-17修复缺少位置数据时无法加载遥测数据反之亦然的问题#412修复 v3.0.3 引入的 Sprint Shootout 结果加载回归#413为 AlphaTauri 车队的 Ricciardo 补充车手颜色pesaventofilippo见 fastf1/plotting/constants.json其中 v3.0.6 的说明直接指向了缓存体系的一个关键运维事实Stage 2 的 pickle 缓存带有 API 解析器版本号校验Cache._API_CORE_VERSION 15见 fastf1/req.py当版本不匹配时会自动判定缓存不可用并重新下载、更新缓存。因此从旧版本升级后首次运行会自动触发缓存刷新无需手动清缓存若在特殊场景下确需忽略版本不匹配可显式传入ignore_versionTrue官方明确不建议。实战建议v3.0 升级后的标准工作流结合上述变更v3.0 时代推荐的典型使用模式如下import fastf1 import logging # 1. 缓存v3.0 起默认启用无需手动开启 # 如需自定义位置在导入后、其他调用前设置 # fastf1.Cache.enable_cache(/path/to/existing/cache_dir) # 2. 日志统一调整输出级别 fastf1.set_log_level(WARNING) # 3. 离线环境只使用已缓存的数据不发出任何网络请求 # fastf1.Cache.offline_mode(True) # 4. 加载场次注意 v3.0 起统一使用 identifier 参数 session fastf1.get_session(2023, 5, Q) session.load() laps session.laps # 5. 新 API 的使用 fastest laps.pick_fastest() # 依赖正确的 Personal Best 标记v3.0.5 修复 q1, q2, q3 laps.split_qualifying_sessions() # 拆分排位赛三段 lap5 laps.pick_lap(5) # 按圈号选取 print(session.total_laps) # 比赛/冲刺赛预期总圈数 print(fastf1.Cache) # 查看缓存目录与占用自定义 __repr__升级前请对照上文的移除清单全面扫描存量代码重点排查Session.weekend、Driver、Weekend、event参数、to_datetime/to_timedelta异常语义以及冲刺赛名称判断逻辑这几类高频使用点。若需回看早期版本的演进脉络可继续阅读 docs/changelog/previous.rst 与 docs/changelog/index.rst 中收录的历史版本记录。【免费下载链接】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），仅供参考
