sec-edgar-downloader下载目录结构完全解析增量下载、重复跳过与accession_numbers_to_skip作用指南【免费下载链接】sec-edgar-downloader Download filings from the SEC EDGAR database using Python项目地址: https://gitcode.com/gh_mirrors/se/sec-edgar-downloadersec-edgar-downloader是一个 Python 工具包用于从美国证券交易委员会SECEDGAR 数据库批量下载公司财报文件如 10-K、8-K 等。本文带你彻底搞懂它的下载目录结构以及两大核心能力——自动跳过重复文件重复跳过和accession_numbers_to_skip参数帮助你用最小代价完成增量下载。一、目录结构长什么样四级文件夹速览调用dl.get(8-K, AAPL)后所有文件默认保存在当前工作目录下的sec-edgar-filings根文件夹中也可在构造Downloader时指定download_folder。完整层级如下sec-edgar-filings/ └── AAPL/ ← 公司标识层 └── 8-K/ ← 文件类型层 └── 0000320193-22-000108/ ← 档案编号层accession number ├── full-submission.txt ← 完整申报文本 └── primary-document.html ← 主文档需 download_detailsTrue层级内容说明第 1 级sec-edgar-filings根目录名由 _constants.py 中的ROOT_SAVE_FOLDER_NAME定义第 2 级AAPL公司标识传股票代码时用代码如AAPL传CIK时用 CIK 号第 3 级8-K文件类型即get()的第一个参数如10-K、SC 13G第 4 级 档案编号唯一标识格式如0000320193-22-000108全球唯一对应一份申报这一结构由_orchestrator.py中的get_save_location()函数生成规则清晰、层次直观方便后续按公司/类型快速定位文件。小提示同一家公司既可以按代码AAPL也可以按 CIK0000320193下载两种方式会落在不同的第 2 级文件夹下规划目录时请注意统一。二、重复跳过机制文件已存在就自动略过这是实现增量下载的关键一环。每次下载前程序会先检查目标路径的文件是否已存在若full-submission.txt已存在→ 直接跳过不发起网络请求若不存在 → 才真正下载并写入磁盘。相关逻辑位于 sec_edgar_downloader/_orchestrator.py 的fetch_and_save_filings()中if not save_location.exists():判断。实际效果同一参数重复执行dl.get()时第二次几乎零开销因为所有已下载的文件都会被自动跳过——这正是重复跳过的本意。三、accession_numbers_to_skip提前排除指定申报如果你事先知道某些档案编号accession number不想下载比如已在别处处理过、或已知文件损坏可以直接传入accession_numbers_to_skip参数让程序在下载清单生成后先过滤再下载连网络请求都省了。dl.get( 10-K, AAPL, accession_numbers_to_skip{0000320193-22-000108} )参数说明类型为Set[str]元素是档案编号字符串即第 4 级文件夹名在 sec_edgar_downloader/_orchestrator.py 的fetch_and_save_filings()中命中集合的申报会被整体剔除该参数自 5.0.3 版本加入变更记录见 CHANGELOG.md。重复跳过 vs accession_numbers_to_skip 的区别机制触发时机是否需要额外参数适用场景文件存在跳过下载前检查本地文件否自动生效日常增量更新accession_numbers_to_skip生成下载清单后过滤是需传入编号集合已知要排除特定申报四、增量下载最佳实践after 参数 自动跳过组合拳日常更新数据时推荐日期过滤 重复跳过双保险# 只拉取最近 7 天的 8-K旧文件自动跳过 dl.get(8-K, AAPL, after2026-08-15)after/before用YYYY-MM-DD格式限定日期区间_utils.py的validate_and_parse_date()负责校验区间内即使包含已下载过的申报文件存在检查仍会将其略过get()返回值是本次实际处理的申报数量便于做日志和断点统计。再配合accession_numbers_to_skip排除个别问题申报即可构建一套稳定、幂等的增量下载流水线。五、常见问题与避坑清单下载目录在哪默认当前工作目录Downloader构造函数的第 3 个参数可自定义例如Downloader(MyCompany, mexx.com, ./data)。为什么没看到 primary-document 文件需显式传download_detailsTrue才会下载主文档XML/HTML默认只下full-submission.txt。代码和 CIK 会导致文件重复吗会分别存放在不同文件夹建议团队统一约定一种标识方式。请求被限流内置限流器已按 SEC 公平访问政策限制为每秒 10 次请求见 sec_edgar_downloader/_sec_gateway.py无需额外处理。结语sec-edgar-downloader用根目录/公司/类型/档案编号的四级目录 文件存在检查 accession_numbers_to_skip白名单排除天然支持幂等的增量下载。理解这套目录结构后无论是构建财报数据集还是做定期数据同步都能做到不重复、不遗漏、可控可查。更多参数细节可查阅 README.rst 与 tests/test_end_to_end_integration.py 中的完整目录示例。【免费下载链接】sec-edgar-downloader Download filings from the SEC EDGAR database using Python项目地址: https://gitcode.com/gh_mirrors/se/sec-edgar-downloader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
