Metadata-Version: 2.4
Name: secrs
Version: 0.1.0
Summary: SEC EDGAR financial statement data, local caching, screening, and valuation tools.
Author: William-Kruta
Project-URL: Repository, https://github.com/William-Kruta/SecRS
Project-URL: Issues, https://github.com/William-Kruta/SecRS/issues
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: beautifulsoup4>=4.14.3
Requires-Dist: polars>=1.40.0
Requires-Dist: requests>=2.33.1
Requires-Dist: tqdm>=4.67.3
Requires-Dist: yahoors>=0.1.6
Requires-Dist: yfinance>=1.3.0

# 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.

```bash
pip install -e .
```

Or install the direct requirements first:

```bash
pip install -r requirements.txt
```

## Quick Start

```python
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`:

```python
from secrs.ticker import Ticker

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

Force a refresh of cached statement data:

```python
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.

```python
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.

```python
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

```python
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:

```python
from secrs.dcf import dcf

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

## Revenue Segments

SecRS can parse inline XBRL filings for revenue by segment.

```python
from secrs.ticker import Ticker

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

print(segments)
```

## Spreadsheet Export

```python
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:

```bash
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

```text
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.
