secrs 0.1.0

SEC EDGAR financial statement data, local caching, screening, and valuation tools.

SecRS

SecRS is a Python toolkit for pulling SEC EDGAR financial statement data, caching it locally, and computing common equity research metrics. It works with Polars DataFrames and includes helpers for single-ticker analysis, batch statement loading, fundamental screening, spreadsheet export, and discounted cash flow valuation.

Features

• Fetch income statements, balance sheets, cash flow statements, and filing metadata from SEC EDGAR.
• Cache filings and parsed statement data in a local SQLite database.
• Work with annual 10-K data or quarterly 10-Q data.
• Compute ratios, margins, leverage, liquidity, valuation, and growth metrics.
• Screen ticker universes with metric filters.
• Export a ticker model to an .xlsx workbook.
• Run a DCF model with manual or auto-derived assumptions.

Installation

This project requires Python 3.12 or newer.

pip install -e .

Or install the direct requirements first:

pip install -r requirements.txt

Quick Start

from secrs.ticker import Ticker

aapl = Ticker("AAPL")

print(aapl.info)
print(aapl.income_statement.revenue)
print(aapl.balance_sheet.total_assets)
print(aapl.cash_flow.free_cash_flow)
print(aapl.ratios)
print(aapl.margins)

Use quarterly data by passing quarterly=True:

from secrs.ticker import Ticker

msft = Ticker("MSFT", quarterly=True)
print(msft.income_statement.data)

Force a refresh of cached statement data:

from secrs.ticker import Ticker

nvda = Ticker("NVDA", force_refresh=True)
print(nvda.cash_flow.data)

Batch Statements

Tickers provides convenience methods for loading multiple companies into one DataFrame.

from secrs.ticker import Tickers

tickers = Tickers()

income = tickers.get_income_statements(["AAPL", "MSFT", "GOOG"], pivot=True)
balance = tickers.get_balance_sheets(["AAPL", "MSFT", "GOOG"], pivot=True)
cash_flow = tickers.get_cash_flows(["AAPL", "MSFT", "GOOG"], pivot=True)

print(income)
print(balance)
print(cash_flow)

Screening

Use Screener or screen_tickers to filter a list of tickers by computed metrics.

from secrs.screener import screen_tickers

results = screen_tickers(
    ["AAPL", "MSFT", "GOOG", "NVDA"],
    pe_ratio=("<", 35),
    gross_margin=(">", 0.40),
    revenue_growth=(">", 0.05),
    include_metrics=["market_cap", "enterprise_value", "current_ratio"],
)

print(results)

Supported filter operators are <, <=, >, >=, ==, and !=.

Common metric groups include:

• Ratios: pe_ratio, ps_ratio, pb_ratio, pfcf_ratio
• Margins: gross_margin, operating_margin, net_margin, fcf_margin, roa, roe, roic
• Leverage: debt_to_equity, debt_to_assets, net_debt_to_ebitda, interest_coverage
• Liquidity: current_ratio, quick_ratio, cash_ratio, net_cash, net_cash_per_share
• Valuation: market_cap, enterprise_value, ev_sales_ratio, ev_ebitda_ratio, ev_fcf_ratio
• Growth: revenue_growth, gross_profit_growth, operating_income_growth, net_income_growth, eps_growth, fcf_growth

DCF Valuation

from secrs.dcf import dcf

result = dcf(
    "AAPL",
    discount_rate=0.10,
    terminal_growth_rate=0.03,
    forecast_years=5,
)

print(result.intrinsic_value_per_share)
print(result.enterprise_value)
print(result.projections)
print(result.assumptions)
print(result.warnings)

Auto mode derives assumptions from available fundamentals and market data:

from secrs.dcf import dcf

result = dcf("MSFT", auto=True)
print(result)

Revenue Segments

SecRS can parse inline XBRL filings for revenue by segment.

from secrs.ticker import Ticker

aapl = Ticker("AAPL")
segments = aapl.segments(start_date="2020-01-01")

print(segments)

Spreadsheet Export

from secrs.ticker import Ticker

model = Ticker("AAPL")
path = model.export_to_spreadsheet("aapl_model.xlsx")

print(path)

Data Storage

SecRS stores parsed data in a local SQLite database and saves downloaded filing text under a local data directory.

Default locations are platform-specific:

• Database: user config directory, under secrs/secrs.db
• Filing data: user data directory, under secrs/filings

Override paths with environment variables:

export SECRS_DB=/path/to/secrs.db
export SECRS_DATA_DIR=/path/to/secrs-data

Data Sources

SecRS uses SEC EDGAR for company filings and statement data. Market prices and company information are fetched through Yahoo Finance-backed dependencies (yahoors and yfinance). Network calls are cached where the project has local caching support, but external services can still rate-limit, change response formats, or return incomplete data.

Project Layout

secrs/
  ticker.py                 Single and batch ticker APIs
  screener.py               Fundamental screening
  dcf.py                    Discounted cash flow valuation
  modules/                  Statement, ratio, margin, liquidity, leverage, valuation logic
  periphery/                SEC metadata, filing parsing, candles, spreadsheet export
  data/                     SQLite initialization and path configuration
  utils/                    Fetching, formatting, dates, metrics, constants

Notes

• Returned tables are Polars DataFrames.
• First runs can be slower because filings and market data need to be downloaded.
• SEC concepts vary by company and filing. Some metrics may be null when a company does not report the required concept or reports it under an unsupported tag.
• This package is for research workflows and does not provide investment advice.