edgartools-sec-data

edgartools：SEC EDGAR 数据访问

edgartools 是本部门读取 SEC 数据的标准方式。它已预装在你的环境中。请使用 Python（脚本或 python -c），不要手动抓取 sec.gov 页面。

始终先设置身份信息

SEC 要求自动化请求提供联系人身份信息。每次会话都要在进行任何其他调用之前执行此操作：

from edgar import set_identity
set_identity("Research Desk workshop [email protected]")  # use the EDGAR_IDENTITY value you were given

（也可以在运行 Python 前导出 EDGAR_IDENTITY 环境变量。）

公司和申报文件

from edgar import Company

company = Company("NVDA")              # by ticker (or CIK)
company.name, company.cik, company.industry

filings = company.get_filings(form="10-K")   # also "10-Q", "8-K", "DEF 14A", ...
latest_10k = filings.latest()                # most recent of that form
latest_10q = company.get_filings(form="10-Q").latest()

latest_10k.form, latest_10k.filing_date, latest_10k.accession_no

如果用户询问“最新申报文件”，请从最新的 10-K / 10-Q 中选择日期较近的那份。外国私人发行人提交的是 20-F，而不是 10-K。

阅读申报文件

filing = latest_10k
tenk = filing.obj()        # rich object for 10-K/10-Q: sections, financials

# Sections (10-K item numbers; 10-Q uses Part/Item naming)
risk_factors = tenk["Item 1A"]      # Risk Factors text
mda = tenk["Item 7"]                # Management's Discussion & Analysis
business = tenk["Item 1"]

# Plain text of the whole filing if you need to search it
text = filing.text()

各章节篇幅很长——请提取所需内容，而不是将整个章节粘贴到回复中。

财务报表（XBRL）

financials = tenk.financials          # also: company.get_financials() for the latest annual figures

income = financials.income_statement()
balance = financials.balance_sheet()
cashflow = financials.cashflow_statement()

这些会返回表格对象（兼容 pandas）。常见字段包括：总收入、毛利、营业收入、净利润、现金及现金等价物、总债务、库存、研发费用。同一报表通常也包含上一期的数据列——进行同比比较时，请使用该列，而不是再获取一份申报文件。

分部和地区收入

合并收入会掩盖实际情况；分部附注才会体现集中度和地区变化。分部数据位于财务报表附注（ASC 280）中，而非主要报表中：

# The segment/geography breakdown is a note, not a primary statement.
# Search the filing text for the segment note and read the tables around it.
text = filing.text()
for marker in ["Segment Information", "revenue by geographic", "Disaggregation of Revenue"]:
    idx = text.find(marker)
    if idx != -1:
        print(text[idx : idx + 3000])   # the note's tables follow the heading
        break

报告分部／地区收入时，应同时列出合并收入，并指出：任何同比变动超过约 20% 的地区或分部，以及任何客户集中度披露（通常表述为“一个客户占收入的 X%”）。

实用模式

• **同比风险因素差异：**提取今年和去年的 10-K 中的 Item 1A（company.get_filings(form="10-K") 已按顺序排列；取前两项）并进行比较。
• 内部人交易：company.get_filings(form="4") 会列出 Form 4 内部人交易申报文件。
• **保持谨慎：**API 接口会不断变化。如果某个属性或方法不存在，请检查它（dir(obj)、help(obj)），或改用 filing.text() 并进行定向搜索，同时在输出中注明所用的替代方法。
• **礼貌使用 EDGAR：**只发送必要的请求；该库会在会话中缓存所有内容。

单位和报告规范

• 报表数值通常以原始 USD 计；报告时请换算成百万（value / 1e6）并标明单位。
• 始终注明数字来自哪份申报文件（表格类型、财年期间、申报日期）。
• 如果 XBRL 中缺少某个数字或其含义不明确，请如实说明，不要估算。