yfinance 持久化缓存机制全解析时区、Cookie 与 ISIN 缓存的存储位置与自定义配置【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinanceyfinance 是当前仓库中用于从 Yahoo! Finance 下载市场数据的 Python 库。为减少对 Yahoo 服务器的重复请求、加速本地化日期与鉴权流程yfinance 会在本地持久化存储三类数据时区timezone、Cookie 与 ISIN 映射。本文以官方文档 doc/source/advanced/caching.rst 为核心结合仓库源码yfinance/cache.py、yfinance/base.py、yfinance/data.py 等深入讲解缓存存储位置、底层 SQLite 实现、自定义缓存路径的 API 用法以及缓存异常时的降级策略。读完本文你将掌握 yfinance 缓存机制的全貌能够在容器、无写权限环境或需要隔离缓存的场景下正确配置与排查缓存问题。为什么 yfinance 需要持久化缓存从源码调用链看yfinance 的每次行情请求都依赖两类高频使用的本地数据时区timezone用于将 Yahoo 返回的 UTC 时间戳本地化为交易日所在时区的日期。若每次都要重新向 Yahoo 拉取时区会显著增加请求次数与延迟。在 yfinance/base.py 的_get_ticker_tz中先查询缓存未命中才回源抓取并把结果写回缓存。CookieYahoo 的部分接口要求带 Cookie 访问。首次成功获取后将其持久化后续请求直接复用避免反复请求fc.yahoo.com等地址见 yfinance/data.py 的_save_cookie_curlCffi/_load_cookie_curlCffi。官方文档明确指出持久化缓存的目的是To reduce requests to Yahoo减少对 Yahoo 的请求这也是整个缓存设计的第一原则。三类本地缓存不止时区与 Cookie文档正文只提到时区与 Cookie但从 yfinance/cache.py 的源码结构看实际上存在三类独立缓存每一类都对应一个独立的 SQLite 数据库文件缓存类型数据库文件名表/模型说明时区缓存TzCachetkr-tz.db_TZ_KVkey-value 表股票代码 → 时区名如America/New_YorkCookie 缓存CookieCachecookies.db_CookieSchema按 cookie 获取策略存储序列化后的 Cookie 字节与抓取时间ISIN 缓存ISINCacheisin-tkr.db_ISIN_KVkey-value 表含created_atISIN 国际证券代码 → 股票代码用于以 ISIN 作为 ticker 的场景三类缓存的实现高度同构每个缓存都有独立的DBManager管理数据库连接与目录、Cache门面类提供lookup/store接口以及哑缓存Dummy降级类见下文故障降级一节。这一对称结构在 yfinance/cache.py 中一目了然TzCache 见 L19-L206CookieCache 见 L214-L416ISINCache 见 L424-L618。ISIN 缓存的实际使用场景在 yfinance/base.py当用户以 ISIN 字符串实例化Ticker时先查get_isin_cache().lookup(isin)未命中则调用utils.get_ticker_by_isin(isin)通过 Yahoo 搜索反查再store写回缓存避免下次重复搜索。默认缓存位置随操作系统而变缓存根目录由 platformdirs 库的user_cache_dir()函数决定再拼接子目录py-yfinance见 yfinance/cache.py 的_cache_dir _os.path.join(_ad.user_cache_dir(), py-yfinance)。官方文档给出的三个平台默认路径为WindowsC:/Users/USER/AppData/Local/py-yfinanceLinux/home/USER/.cache/py-yfinancemacOS/Users/USER/Library/Caches/py-yfinance所有三个数据库文件tkr-tz.db、cookies.db、isin-tkr.db都直接存放在该目录下。需要注意USER是当前系统用户名请勿把它当成字面路径的一部分。自定义缓存位置set_tz_cache_location 与 set_cache_location当默认缓存目录不可写例如容器内只读文件系统、共享服务器限制家目录写入、或希望把缓存放入项目数据目录/临时目录时官方文档推荐使用set_tz_cache_location重新定向缓存位置import yfinance as yf yf.set_tz_cache_location(custom/cache/location)set_tz_cache_location是 yfinance 顶层公开 API在 yfinance/init.py 中导入并列入__all__。它的实现yfinance/cache.py只是调用了更底层的set_cache_locationdef set_tz_cache_location(cache_dir: str): set_cache_location(cache_dir) def set_cache_location(cache_dir: str): _TzDBManager.set_location(cache_dir) _CookieDBManager.set_location(cache_dir) _ISINDBManager.set_location(cache_dir)由此可以看出两个关键事实set_tz_cache_location一次生效于全部三类缓存时区、Cookie、ISIN并非只移动时区缓存传入的参数是父目录——yfinance 会在该目录下创建三个数据库文件目录本身若不存在会被自动创建_os.makedirs见 yfinance/cache.py。使用注意事项必须在缓存首次使用之前调用。源码 docstring 明确要求 Must be called before cache is used (that is, before fetching tickers)yfinance/cache.py。一旦TzDBManager/CookieDBManager/ISINDBManager的数据库已初始化再次调用set_location会先关闭旧数据库连接再切换目录但更稳妥的做法仍是程序启动后、首次取数前立即设置。相对路径可用但建议传绝对路径避免当前工作目录变化导致缓存散落多处。传入目录必须可读写。初始化时若目录不可读或不可写会抛出_TzCacheException/_CookieCacheException/_ISINCacheException提示Cannot read and write in ... folder对应缓存将自动降级为哑缓存详见下文。缓存到底存在哪里SQLite 与文件结构虽然文档没有展开但从源码可以确认三类缓存均为SQLite 数据库通过peeweeORM 访问import peewee as _peewee见 yfinance/cache.py。数据库打开时设置了两个重要 pragma见 L85-L88cls._db _peewee.SqliteDatabase( _os.path.join(cls._cache_dir, tkr-tz.db), pragmas{journal_mode: wal, cache_size: -64} )journal_mode wal启用 WALWrite-Ahead Logging日志模式提升并发读写性能也是多进程/多线程场景下更安全的默认选择cache_size -64SQLite 页缓存上限约为 64 KiB负值表示以 KB 为单位避免缓存占用过多内存。其余两个数据库cookies.db、isin-tkr.db使用完全相同的初始化参数见 L280-L283、L490-L493。数据结构方面时区缓存_TZ_KV表以股票代码为 primary key值为时区字符串without_rowid True让表本身成为 key-value 存储节省空间。Cookie 缓存_CookieSchema以strategy为主键fetch_date记录抓取时间自定义ISODateTimeField保证写入合法的 ISO 格式时间cookie_bytes为BlobField实际内容是用pickle序列化的 Cookie 字典_pkl.dumps/_pkl.loads见 L378、L402。ISIN 缓存_ISIN_KV表在 key-value 之外额外记录created_at创建时间用于清理一周以上的过期反向映射见 L596-L602删除值相同且创建时间超过一周的旧行防止 ISIN → ticker 映射漂移。另外缓存升级时还会自动清理旧格式文件初始化时若发现旧的tkr-tz.csv早期 yfinance 版本曾用 CSV 做时区缓存会自动删除L90-L92。因此看到缓存目录同时存在.db与.csv时不必手工处理新版会自动迁移。源码视角缓存如何被使用与更新时区缓存的读写路径在 yfinance/base.py 的_get_ticker_tz中先cache.get_tz_cache().lookup(self.ticker)查缓存若缓存值存在但utils.is_valid_timezone(tz)校验失败比如时区名已失效则store(self.ticker, None)主动清除脏数据并强制回源L144-L147回源成功后store写回若回源失败最多两次尝试从info的exchangeTimezoneName/timeZoneFullName字段兜底L149-L166。注意store(key, None)的特殊语义value 为None时执行删除操作_TZ_KV.delete().where(...)见 L189-L192这是源码提供的清缓存入口。Cookie 缓存的读写路径在 yfinance/data.py 中_save_cookie_curlCffi在成功拿到 Yahoo 域 Cookie 后以策略名curlCffi写入缓存_load_cookie_curlCffi读取时不仅反序列化还会检查 Cookie 过期时间expires字段换算成 UTC 后与当前时间比较过期则返回 False触发重新获取见 L213-L220。_get_cookie_basic依次尝试内存 Cookie → 持久化 Cookie → 在线抓取L226-L246。线程安全与进程退出清理所有缓存的初始化都受_cache_init_lockthreading.Lock保护L11、L43避免多线程并发初始化竞态。三个DBManager都在解释器退出时通过atexit.register(close_db)注册关闭回调L106、L297、L507确保 SQLite 连接优雅释放。缓存不可用时的降级策略这是一个容易被忽略但很重要的设计缓存初始化失败不会让 yfinance 崩溃而是自动降级为哑缓存Dummy。当目录创建失败或不可读写时get_db()捕获对应的*CacheException打印 info 级日志提示可使用set_tz_cache_location换位置并把self.dummy True见 yfinance/cache.py。此后lookup永远返回None等于永远走回源逻辑store直接 no-op 不写盘。对应地三个 Dummy 类_TzCacheDummy、_CookieCacheDummy、_ISINCacheDummy实现了与真实缓存相同的接口。这意味着在无写权限的环境里yfinance 依然能正常取数只是每次都要重新请求时区/Cookie——功能可用性能略降。如果你在日志中看到类似Failed to create TzCache, reason: ...的信息即可确认缓存已降级应按提示调用set_tz_cache_location指向一个可写目录。如何验证与测试缓存配置仓库自带缓存单元测试 tests/test_cache.py既是验证配置是否生效的参考也是理解 API 行为的最佳样例test_setTzCacheLocation调用yf.set_tz_cache_location(tmpdir)后断言_TzDBManager.get_location()指向新目录并验证store后tkr-tz.db文件真实存在于新目录test_storeTzNoRaise连续对同一 ticker 写入两个不同时区断言存储过程绝不抛异常store内部对IntegrityError做了存在则更新处理setUpClass/tearDownClass中演示了测试环境的缓存隔离与恢复用tempfile.TemporaryDirectory()做临时目录结束后清理并恢复原缓存位置。如需手动验证当前缓存位置可在 Python 中执行import yfinance as yf from yfinance import cache # 查看当前时区缓存目录 print(cache._TzDBManager.get_location()) # 查看已缓存的所有 ticker 时区需先初始化 tz_cache cache.get_tz_cache()常见问题FAQQ1如何清空缓存直接删除缓存目录下的三个.db文件tkr-tz.db、cookies.db、isin-tkr.db即可下次运行会自动重建也可以把set_tz_cache_location指向一个新目录实现隔离式缓存。请勿在 yfinance 运行时删除文件应确保程序退出后再清理。Q2为什么换了缓存目录后好像没生效最常见原因是调用时机太晚——缓存一旦被使用就已初始化。请把set_tz_cache_location放在程序最开头、任何Ticker/download调用之前。Q3缓存目录权限不对会怎样不会崩溃。对应缓存自动降级为哑缓存yfinance 照常工作但请求量上升日志中出现Failed to create ... Cache的 info 提示。Q4删除tkr-tz.db会不会影响历史行情数据不会。缓存只存时区映射与 Cookie 等元数据不保存行情数据本身删除后 yfinance 会在下一次调用时自动重建。小结yfinance 的持久化缓存机制围绕减少对 Yahoo 的请求这一目标设计三类 SQLite 缓存时区、Cookie、ISIN共享统一的存储目录与异常降级策略默认位置由platformdirs按操作系统决定通过顶层 APIyf.set_tz_cache_location(...)实际等价于set_cache_location同时作用于三类缓存可在首次使用前轻松改道。理解缓存文件的命名、WAL 模式、脏数据自愈与 Dummy 降级行为能帮助你在容器化、只读文件系统等受限环境中正确部署 yfinance并在排查请求变多目录不可写等问题时快速定位根因。若需进一步了解安装方式可参考 doc/source/advanced/install.rst完整配置项见 doc/source/advanced/config.rst。【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 yfinance 持久化缓存机制全解析：时区、Cookie 与 ISIN 缓存的存储位置与自定义配置
yfinance 持久化缓存机制全解析时区、Cookie 与 ISIN 缓存的存储位置与自定义配置【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinanceyfinance 是当前仓库中用于从 Yahoo! Finance 下载市场数据的 Python 库。为减少对 Yahoo 服务器的重复请求、加速本地化日期与鉴权流程yfinance 会在本地持久化存储三类数据时区timezone、Cookie 与 ISIN 映射。本文以官方文档 doc/source/advanced/caching.rst 为核心结合仓库源码yfinance/cache.py、yfinance/base.py、yfinance/data.py 等深入讲解缓存存储位置、底层 SQLite 实现、自定义缓存路径的 API 用法以及缓存异常时的降级策略。读完本文你将掌握 yfinance 缓存机制的全貌能够在容器、无写权限环境或需要隔离缓存的场景下正确配置与排查缓存问题。为什么 yfinance 需要持久化缓存从源码调用链看yfinance 的每次行情请求都依赖两类高频使用的本地数据时区timezone用于将 Yahoo 返回的 UTC 时间戳本地化为交易日所在时区的日期。若每次都要重新向 Yahoo 拉取时区会显著增加请求次数与延迟。在 yfinance/base.py 的_get_ticker_tz中先查询缓存未命中才回源抓取并把结果写回缓存。CookieYahoo 的部分接口要求带 Cookie 访问。首次成功获取后将其持久化后续请求直接复用避免反复请求fc.yahoo.com等地址见 yfinance/data.py 的_save_cookie_curlCffi/_load_cookie_curlCffi。官方文档明确指出持久化缓存的目的是To reduce requests to Yahoo减少对 Yahoo 的请求这也是整个缓存设计的第一原则。三类本地缓存不止时区与 Cookie文档正文只提到时区与 Cookie但从 yfinance/cache.py 的源码结构看实际上存在三类独立缓存每一类都对应一个独立的 SQLite 数据库文件缓存类型数据库文件名表/模型说明时区缓存TzCachetkr-tz.db_TZ_KVkey-value 表股票代码 → 时区名如America/New_YorkCookie 缓存CookieCachecookies.db_CookieSchema按 cookie 获取策略存储序列化后的 Cookie 字节与抓取时间ISIN 缓存ISINCacheisin-tkr.db_ISIN_KVkey-value 表含created_atISIN 国际证券代码 → 股票代码用于以 ISIN 作为 ticker 的场景三类缓存的实现高度同构每个缓存都有独立的DBManager管理数据库连接与目录、Cache门面类提供lookup/store接口以及哑缓存Dummy降级类见下文故障降级一节。这一对称结构在 yfinance/cache.py 中一目了然TzCache 见 L19-L206CookieCache 见 L214-L416ISINCache 见 L424-L618。ISIN 缓存的实际使用场景在 yfinance/base.py当用户以 ISIN 字符串实例化Ticker时先查get_isin_cache().lookup(isin)未命中则调用utils.get_ticker_by_isin(isin)通过 Yahoo 搜索反查再store写回缓存避免下次重复搜索。默认缓存位置随操作系统而变缓存根目录由 platformdirs 库的user_cache_dir()函数决定再拼接子目录py-yfinance见 yfinance/cache.py 的_cache_dir _os.path.join(_ad.user_cache_dir(), py-yfinance)。官方文档给出的三个平台默认路径为WindowsC:/Users/USER/AppData/Local/py-yfinanceLinux/home/USER/.cache/py-yfinancemacOS/Users/USER/Library/Caches/py-yfinance所有三个数据库文件tkr-tz.db、cookies.db、isin-tkr.db都直接存放在该目录下。需要注意USER是当前系统用户名请勿把它当成字面路径的一部分。自定义缓存位置set_tz_cache_location 与 set_cache_location当默认缓存目录不可写例如容器内只读文件系统、共享服务器限制家目录写入、或希望把缓存放入项目数据目录/临时目录时官方文档推荐使用set_tz_cache_location重新定向缓存位置import yfinance as yf yf.set_tz_cache_location(custom/cache/location)set_tz_cache_location是 yfinance 顶层公开 API在 yfinance/init.py 中导入并列入__all__。它的实现yfinance/cache.py只是调用了更底层的set_cache_locationdef set_tz_cache_location(cache_dir: str): set_cache_location(cache_dir) def set_cache_location(cache_dir: str): _TzDBManager.set_location(cache_dir) _CookieDBManager.set_location(cache_dir) _ISINDBManager.set_location(cache_dir)由此可以看出两个关键事实set_tz_cache_location一次生效于全部三类缓存时区、Cookie、ISIN并非只移动时区缓存传入的参数是父目录——yfinance 会在该目录下创建三个数据库文件目录本身若不存在会被自动创建_os.makedirs见 yfinance/cache.py。使用注意事项必须在缓存首次使用之前调用。源码 docstring 明确要求 Must be called before cache is used (that is, before fetching tickers)yfinance/cache.py。一旦TzDBManager/CookieDBManager/ISINDBManager的数据库已初始化再次调用set_location会先关闭旧数据库连接再切换目录但更稳妥的做法仍是程序启动后、首次取数前立即设置。相对路径可用但建议传绝对路径避免当前工作目录变化导致缓存散落多处。传入目录必须可读写。初始化时若目录不可读或不可写会抛出_TzCacheException/_CookieCacheException/_ISINCacheException提示Cannot read and write in ... folder对应缓存将自动降级为哑缓存详见下文。缓存到底存在哪里SQLite 与文件结构虽然文档没有展开但从源码可以确认三类缓存均为SQLite 数据库通过peeweeORM 访问import peewee as _peewee见 yfinance/cache.py。数据库打开时设置了两个重要 pragma见 L85-L88cls._db _peewee.SqliteDatabase( _os.path.join(cls._cache_dir, tkr-tz.db), pragmas{journal_mode: wal, cache_size: -64} )journal_mode wal启用 WALWrite-Ahead Logging日志模式提升并发读写性能也是多进程/多线程场景下更安全的默认选择cache_size -64SQLite 页缓存上限约为 64 KiB负值表示以 KB 为单位避免缓存占用过多内存。其余两个数据库cookies.db、isin-tkr.db使用完全相同的初始化参数见 L280-L283、L490-L493。数据结构方面时区缓存_TZ_KV表以股票代码为 primary key值为时区字符串without_rowid True让表本身成为 key-value 存储节省空间。Cookie 缓存_CookieSchema以strategy为主键fetch_date记录抓取时间自定义ISODateTimeField保证写入合法的 ISO 格式时间cookie_bytes为BlobField实际内容是用pickle序列化的 Cookie 字典_pkl.dumps/_pkl.loads见 L378、L402。ISIN 缓存_ISIN_KV表在 key-value 之外额外记录created_at创建时间用于清理一周以上的过期反向映射见 L596-L602删除值相同且创建时间超过一周的旧行防止 ISIN → ticker 映射漂移。另外缓存升级时还会自动清理旧格式文件初始化时若发现旧的tkr-tz.csv早期 yfinance 版本曾用 CSV 做时区缓存会自动删除L90-L92。因此看到缓存目录同时存在.db与.csv时不必手工处理新版会自动迁移。源码视角缓存如何被使用与更新时区缓存的读写路径在 yfinance/base.py 的_get_ticker_tz中先cache.get_tz_cache().lookup(self.ticker)查缓存若缓存值存在但utils.is_valid_timezone(tz)校验失败比如时区名已失效则store(self.ticker, None)主动清除脏数据并强制回源L144-L147回源成功后store写回若回源失败最多两次尝试从info的exchangeTimezoneName/timeZoneFullName字段兜底L149-L166。注意store(key, None)的特殊语义value 为None时执行删除操作_TZ_KV.delete().where(...)见 L189-L192这是源码提供的清缓存入口。Cookie 缓存的读写路径在 yfinance/data.py 中_save_cookie_curlCffi在成功拿到 Yahoo 域 Cookie 后以策略名curlCffi写入缓存_load_cookie_curlCffi读取时不仅反序列化还会检查 Cookie 过期时间expires字段换算成 UTC 后与当前时间比较过期则返回 False触发重新获取见 L213-L220。_get_cookie_basic依次尝试内存 Cookie → 持久化 Cookie → 在线抓取L226-L246。线程安全与进程退出清理所有缓存的初始化都受_cache_init_lockthreading.Lock保护L11、L43避免多线程并发初始化竞态。三个DBManager都在解释器退出时通过atexit.register(close_db)注册关闭回调L106、L297、L507确保 SQLite 连接优雅释放。缓存不可用时的降级策略这是一个容易被忽略但很重要的设计缓存初始化失败不会让 yfinance 崩溃而是自动降级为哑缓存Dummy。当目录创建失败或不可读写时get_db()捕获对应的*CacheException打印 info 级日志提示可使用set_tz_cache_location换位置并把self.dummy True见 yfinance/cache.py。此后lookup永远返回None等于永远走回源逻辑store直接 no-op 不写盘。对应地三个 Dummy 类_TzCacheDummy、_CookieCacheDummy、_ISINCacheDummy实现了与真实缓存相同的接口。这意味着在无写权限的环境里yfinance 依然能正常取数只是每次都要重新请求时区/Cookie——功能可用性能略降。如果你在日志中看到类似Failed to create TzCache, reason: ...的信息即可确认缓存已降级应按提示调用set_tz_cache_location指向一个可写目录。如何验证与测试缓存配置仓库自带缓存单元测试 tests/test_cache.py既是验证配置是否生效的参考也是理解 API 行为的最佳样例test_setTzCacheLocation调用yf.set_tz_cache_location(tmpdir)后断言_TzDBManager.get_location()指向新目录并验证store后tkr-tz.db文件真实存在于新目录test_storeTzNoRaise连续对同一 ticker 写入两个不同时区断言存储过程绝不抛异常store内部对IntegrityError做了存在则更新处理setUpClass/tearDownClass中演示了测试环境的缓存隔离与恢复用tempfile.TemporaryDirectory()做临时目录结束后清理并恢复原缓存位置。如需手动验证当前缓存位置可在 Python 中执行import yfinance as yf from yfinance import cache # 查看当前时区缓存目录 print(cache._TzDBManager.get_location()) # 查看已缓存的所有 ticker 时区需先初始化 tz_cache cache.get_tz_cache()常见问题FAQQ1如何清空缓存直接删除缓存目录下的三个.db文件tkr-tz.db、cookies.db、isin-tkr.db即可下次运行会自动重建也可以把set_tz_cache_location指向一个新目录实现隔离式缓存。请勿在 yfinance 运行时删除文件应确保程序退出后再清理。Q2为什么换了缓存目录后好像没生效最常见原因是调用时机太晚——缓存一旦被使用就已初始化。请把set_tz_cache_location放在程序最开头、任何Ticker/download调用之前。Q3缓存目录权限不对会怎样不会崩溃。对应缓存自动降级为哑缓存yfinance 照常工作但请求量上升日志中出现Failed to create ... Cache的 info 提示。Q4删除tkr-tz.db会不会影响历史行情数据不会。缓存只存时区映射与 Cookie 等元数据不保存行情数据本身删除后 yfinance 会在下一次调用时自动重建。小结yfinance 的持久化缓存机制围绕减少对 Yahoo 的请求这一目标设计三类 SQLite 缓存时区、Cookie、ISIN共享统一的存储目录与异常降级策略默认位置由platformdirs按操作系统决定通过顶层 APIyf.set_tz_cache_location(...)实际等价于set_cache_location同时作用于三类缓存可在首次使用前轻松改道。理解缓存文件的命名、WAL 模式、脏数据自愈与 Dummy 降级行为能帮助你在容器化、只读文件系统等受限环境中正确部署 yfinance并在排查请求变多目录不可写等问题时快速定位根因。若需进一步了解安装方式可参考 doc/source/advanced/install.rst完整配置项见 doc/source/advanced/config.rst。【免费下载链接】yfinanceDownload market data from Yahoo! Finances API项目地址: https://gitcode.com/GitHub_Trending/yf/yfinance创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考