secfin 0.1.0

Fetch company financial records from SEC EDGAR

secfin

Fetch company financial records from SEC EDGAR.

Installation

pip install secfin

Or install from source:

pip install -e .

Quick Start

from secfin import SECClient, Company

# Initialize client (SEC requires User-Agent with contact info)
client = SECClient(user_agent="MyApp [e-mail]")

# Get company financials
company = Company("AAPL", client)

# Income Statement
income = company.get_income_statement()
print(f"Revenue: {income.revenue.latest()}")
print(f"Net Income: {income.net_income.latest()}")

# Balance Sheet
balance = company.get_balance_sheet()
print(f"Total Assets: {balance.total_assets.latest()}")
print(f"Cash: {balance.cash.latest()}")

# Cash Flow Statement
cashflow = company.get_cash_flow()
print(f"Operating Cash Flow: {cashflow.operating_cash_flow.latest()}")
print(f"Free Cash Flow: {cashflow.free_cash_flow.latest()}")

Features

• Income Statement: Revenue, Cost of Revenue, Gross Profit, Operating Income, Net Income, EPS
• Balance Sheet: Assets, Liabilities, Equity, Cash, Inventory, Debt
• Cash Flow: Operating, Investing, Financing cash flows, CapEx, Dividends

Data Export

Convert to pandas DataFrame:

# Get historical data as DataFrame
df = company.get_income_statement().to_dataframe()
print(df)

Get a summary of all financials:

summary = company.summary()
print(summary)

Quarterly vs Annual Data

# Annual data (10-K filings)
annual_income = company.get_income_statement(period="annual")

# Quarterly data (10-Q filings)
quarterly_income = company.get_income_statement(period="quarterly")

Earnings Dates

Get historical and estimated future earnings dates:

company = Company("AAPL", client)

# Last earnings date
last = company.last_earnings()
print(f"Last Filing: {last['date']} ({last['form_type']})")

# Next earnings (estimated)
next_e = company.next_earnings()
print(f"Next Expected: {next_e['date']} ({next_e['fiscal_quarter']})")

# Historical earnings dates
history = company.earnings_history(limit=10)
for h in history:
    print(f"{h['date']} | {h['form_type']} | {h['fiscal_quarter']}")

# Full earnings calendar
calendar = company.get_earnings_calendar()
print(f"Fiscal Year End: {calendar.fiscal_year_end}")
df = calendar.get_historical_df()

Example Output

Last Earnings:
  Filing Date: 2026-01-30
  Period End: 2025-12-27
  Form Type: 10-Q
  Quarter: Q1

Next Earnings (Estimated):
  Expected Date: 2026-04-30
  Form Type: 10-Q
  Quarter: Q2

Rate Limiting

The client automatically respects SEC's rate limit (10 requests/second).

Batch Fetching - Index Constituents

Fetch financials for entire indices:

from secfin import SECClient, BatchFetcher

client = SECClient("MyApp [e-mail]")
fetcher = BatchFetcher(client)

# Fetch all S&P 500 companies (~500 companies)
sp500_data = fetcher.fetch_sp500()

# Fetch all NASDAQ 100 companies (~100 companies)
nasdaq_data = fetcher.fetch_nasdaq100()

# Fetch custom list of tickers
tickers = ["AAPL", "MSFT", "GOOGL", "AMZN", "META"]
custom_data = fetcher.fetch_tickers(tickers)

Progress Tracking

def my_progress(current, total, ticker, status):
    print(f"Progress: {current}/{total} - {ticker}: {status}")

fetcher = BatchFetcher(client, on_progress=my_progress)
results = fetcher.fetch_nasdaq100()

Export to DataFrame

# Get summary DataFrame with key metrics
summary_df = fetcher.summary_dataframe(results)
print(summary_df)

# Get specific metric across all companies
revenue_df = fetcher.to_dataframe(results, "income_statement", "revenue")
print(revenue_df)

Available Indices

Index	Method	Companies
S&P 500	fetch_sp500()	~500
NASDAQ 100	fetch_nasdaq100()	~100
Russell 2000	fetch_russell2000(tickers)	~2000 (requires ticker list)

Russell 2000

Russell 2000 constituent list is not freely available. You need to provide your own list:

# Load your Russell 2000 tickers
russell_tickers = [...]  # Your list of ~2000 tickers

results = fetcher.fetch_russell2000(tickers=russell_tickers)

Requirements

• Python 3.9+
• requests
• pandas

License

MIT