edgartools — Deep Code Evaluation

# Basic installation
pip install edgartools

# With AI/MCP server integration (for Claude)
pip install edgartools[ai]

# With SQL querying via DuckDB
pip install edgartools[data]

# With cloud storage (S3, GCS, Azure)
pip install edgartools[all-cloud]

from edgar import set_identity, Company

# SEC requires User-Agent identification (mandatory)
set_identity("Your Name your.email@example.com")

# Now you can use the library
company = Company("AAPL")
filings = company.get_filings(form="10-K")

# SEC EDGAR enforces 10 requests/second. edgartools defaults to 9 for safety.
# The HTTP stack is layered:
#
#   Application Code
#        |
#   get_with_retry()          <-- stamina retry with exponential backoff
#        |
#   httpxthrottlecache        <-- file-based response caching + throttle
#        |
#   pyrate-limiter            <-- token-bucket rate limiter (9 req/sec)
#        |
#   httpx.Client              <-- actual HTTP/2 connection to SEC servers
#        |
#   truststore                <-- OS-level SSL/TLS verification

# Rate limit is configurable:
from edgar.httpclient import update_rate_limiter
update_rate_limiter(requests_per_second=5)  # reduce for politeness

from edgar import Company

company = Company("MSFT")
filing = company.get_filings(form="10-K").latest()
tenk = filing.obj()

# Access parsed financial statements
income  = tenk.financials.income_statement
balance = tenk.financials.balance_sheet
cashflow = tenk.financials.cash_flow_statement

# Export to pandas DataFrame
df = income.to_dataframe()

# Multi-period stitching (last 5 years)
from edgar import MultiFinancials
multi = company.financials  # auto-stitches across recent filings

# ParserConfig.for_ai() optimizes text for LLM consumption
from edgar.ai import ParserConfig

config = ParserConfig.for_ai()
text = filing.text(config=config)  # clean, LLM-friendly text

# MCP Server (for Claude Desktop / API)
# pip install edgartools[ai]
# edgartools-mcp-server  (launches MCP server)

from edgar import (
    # Setup
    set_identity,              # Required: set SEC User-Agent

    # Company Access
    Company,                   # Primary entry point for a SEC filer
    find_company,              # Fuzzy search for companies by name
    get_entity,                # Get entity by CIK number

    # Filings
    get_filings,               # Browse all recent filings (any form)
    get_by_accession_number,   # Direct filing lookup by accession #

    # Financial Data
    Financials,                # Single-period financial statements
    MultiFinancials,           # Multi-period stitched statements
    XBRL,                      # Raw XBRL data access

    # Specialized Forms
    ThirteenF,                 # 13F institutional holdings
    ProxyStatement,            # DEF 14A proxy statement

    # Search
    search_filings,            # Full-text search via EFTS

    # Storage & Config
    use_local_storage,         # Enable offline mode
    configure_http,            # HTTP settings (proxy, timeout)
)

# Company not found
try:
    company = Company("INVALID_TICKER")
except CompanyNotFoundError as e:
    print(f"Company not found: {e}")

# Filing without XBRL data (older filings)
try:
    xbrl = filing.xbrl()
except XBRLFilingWithNoXbrlData:
    print("This filing predates XBRL requirements")

# Rate limiting - automatic retry via stamina
# HTTP 403 responses are NOT retried (SEC rate limit)
# HTTP 5xx responses ARE retried with backoff

from edgar import Company, set_identity

set_identity("Your Name email@example.com")

company = Company("XOM")  # Exxon Mobil
tenk = company.get_filings(form="10-K").latest().obj()

# Extract risk factors section (common ESG disclosure location)
text = tenk.filing.text()

esg_keywords = {
    "Environmental": ["climate change", "carbon emissions", "renewable energy",
                       "greenhouse gas", "sustainability", "environmental"],
    "Social":        ["employee", "diversity", "human rights",
                       "health and safety", "community"],
    "Governance":    ["board of directors", "ethics", "compliance",
                       "executive compensation", "audit"],
}

for category, keywords in esg_keywords.items():
    hits = [kw for kw in keywords if kw.lower() in text.lower()]
    print(f"{category}: {len(hits)}/{len(keywords)} keywords found")

# Test Matrix: 5 companies x 7 years = 35 test cases
# Companies: AAPL, MSFT, TSLA, JPM, XOM
# Years: 2015, 2017, 2019, 2021, 2023, 2025, 2026
#
# For each combination:
#   1. Fetch 10-K filing for that year
#   2. Parse into TenK object
#   3. Extract financial statements (income, balance, cashflow)
#   4. Extract full text and count ESG keywords
#   5. Measure timing for each operation
#
# Expected results:
#   - 2015-2023: All companies should have 10-K filings
#   - TSLA pre-2018: Limited XBRL data (smaller company then)
#   - 2025-2026: Most recent filings, may not exist yet for all
#
# Run: python esg_eval/test_edgartools_full.py
# Output: esg_eval/results_edgartools_full.json