edgar-parser 0.1.0__tar.gz

edgar_parser-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+venv/
+__pycache__/
+*.pyc
+.DS_Store
+.env
+cache/
+dist/
+*.egg-info/
+.mypy_cache/
+.pytest_cache/

edgar_parser-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Henry Chien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

edgar_parser-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: edgar-parser
+Version: 0.1.0
+Summary: Structured financial data from SEC EDGAR filings — 10-Q, 10-K, and 8-K
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: beautifulsoup4
+Requires-Dist: lxml
+Requires-Dist: numpy
+Requires-Dist: openpyxl
+Requires-Dist: pandas
+Requires-Dist: python-dateutil
+Requires-Dist: python-dotenv
+Requires-Dist: rapidfuzz
+Requires-Dist: requests
+Provides-Extra: llm
+Requires-Dist: anthropic; extra == 'llm'
+Description-Content-Type: text/markdown
+
+# edgar-parser
+
+Structured financial data from SEC EDGAR filings.
+
+Give your Python application access to income statements, balance sheets, cash flows, and qualitative sections from 10-Q, 10-K, and 8-K filings — parsed directly from SEC EDGAR with no third-party data vendor required.
+
+This isn't a raw EDGAR scraper. The library handles XBRL namespace resolution, fiscal period matching, current vs. prior period alignment, sign normalization, and fuzzy metric lookup — so you get clean, analysis-ready data.
+
+## What it does
+
+**Core Extraction** (`parse_filing`)
+- Parses iXBRL facts from 10-Q and 10-K filings on SEC EDGAR
+- Resolves XBRL namespaces, units, scales, and dimensional qualifiers
+- Enriches facts with presentation roles and negated-label sign flipping
+
+**Period Matching** (`match_filing`)
+- Aligns current and prior period values for each financial line item
+- Handles quarterly, full-year, and 4Q (derived annual) modes
+- Zip-matching with adaptive fallback to fuzzy matching for edge cases
+
+**8-K Earnings Extraction** (`earnings_8k`) — *optional, requires `anthropic`*
+- Extracts financial data from 8-K earnings press releases using Claude
+- Automatic fallback when 10-Q/10-K is not yet available for a period
+- Same output schema as core extraction for seamless integration
+
+**Filing Sections** (`section_parser`)
+- Parses qualitative sections from 10-K/10-Q filings (Risk Factors, MD&A, Business, etc.)
+- Summary and full-text modes with configurable word limits
+
+**High-Level Tools** (`tools`)
+- `get_financials(ticker, year, quarter)` — all facts for a filing period
+- `get_filings(ticker, year, quarter)` — list available filings (10-Q, 10-K, 8-K)
+- `get_metric(ticker, year, quarter, metric_name)` — single metric lookup with fuzzy matching
+- `get_filing_sections(ticker, year, quarter)` — qualitative section text
+
+## Install
+
+```bash
+pip install edgar-parser
+```
+
+For 8-K earnings extraction (uses Claude API):
+
+```bash
+pip install "edgar-parser[llm]"
+```
+
+## Quick start
+
+```python
+from edgar_parser.tools import get_financials, get_metric
+
+# Get all financial facts from Apple's Q1 2025 10-Q
+result = get_financials("AAPL", 2025, 1)
+for fact in result["facts"][:5]:
+    print(f"{fact['metric']}: {fact['current_value']}")
+
+# Look up a single metric
+revenue = get_metric("AAPL", 2025, 1, "Revenue")
+print(f"Revenue: {revenue['value']} {revenue['unit']}")
+```
+
+Or use the lower-level API for more control:
+
+```python
+from edgar_parser import parse_filing, match_filing
+
+# Parse raw XBRL facts
+parsed = parse_filing("AAPL", 2025, 1, full_year_mode=False)
+
+# Match current vs. prior periods
+matched = match_filing(parsed)
+print(matched.head())
+```
+
+## Key functions
+
+| Function | Module | Description |
+|----------|--------|-------------|
+| `get_financials` | `tools` | All facts for a ticker/period, with caching |
+| `get_filings` | `tools` | List SEC filings (10-Q, 10-K, 8-K) for a period |
+| `get_metric` | `tools` | Single metric lookup with fuzzy matching |
+| `get_filing_sections` | `tools` | Qualitative section text (Risk Factors, MD&A, etc.) |
+| `parse_filing` | `pipeline` | Low-level XBRL fact extraction |
+| `enrich_filing` | `pipeline` | Fiscal period categorization and enrichment |
+| `match_filing` | `matching` | Current vs. prior period alignment |
+| `find_8k_for_period` | `earnings_8k` | Find 8-K earnings release for a fiscal period |
+
+## Requirements
+
+- Python 3.10+
+- No API key needed — data comes directly from SEC EDGAR (public)
+- Optional: `ANTHROPIC_API_KEY` environment variable for 8-K extraction

edgar_parser-0.1.0/README.md

@@ -0,0 +1,93 @@
+# edgar-parser
+
+Structured financial data from SEC EDGAR filings.
+
+Give your Python application access to income statements, balance sheets, cash flows, and qualitative sections from 10-Q, 10-K, and 8-K filings — parsed directly from SEC EDGAR with no third-party data vendor required.
+
+This isn't a raw EDGAR scraper. The library handles XBRL namespace resolution, fiscal period matching, current vs. prior period alignment, sign normalization, and fuzzy metric lookup — so you get clean, analysis-ready data.
+
+## What it does
+
+**Core Extraction** (`parse_filing`)
+- Parses iXBRL facts from 10-Q and 10-K filings on SEC EDGAR
+- Resolves XBRL namespaces, units, scales, and dimensional qualifiers
+- Enriches facts with presentation roles and negated-label sign flipping
+
+**Period Matching** (`match_filing`)
+- Aligns current and prior period values for each financial line item
+- Handles quarterly, full-year, and 4Q (derived annual) modes
+- Zip-matching with adaptive fallback to fuzzy matching for edge cases
+
+**8-K Earnings Extraction** (`earnings_8k`) — *optional, requires `anthropic`*
+- Extracts financial data from 8-K earnings press releases using Claude
+- Automatic fallback when 10-Q/10-K is not yet available for a period
+- Same output schema as core extraction for seamless integration
+
+**Filing Sections** (`section_parser`)
+- Parses qualitative sections from 10-K/10-Q filings (Risk Factors, MD&A, Business, etc.)
+- Summary and full-text modes with configurable word limits
+
+**High-Level Tools** (`tools`)
+- `get_financials(ticker, year, quarter)` — all facts for a filing period
+- `get_filings(ticker, year, quarter)` — list available filings (10-Q, 10-K, 8-K)
+- `get_metric(ticker, year, quarter, metric_name)` — single metric lookup with fuzzy matching
+- `get_filing_sections(ticker, year, quarter)` — qualitative section text
+
+## Install
+
+```bash
+pip install edgar-parser
+```
+
+For 8-K earnings extraction (uses Claude API):
+
+```bash
+pip install "edgar-parser[llm]"
+```
+
+## Quick start
+
+```python
+from edgar_parser.tools import get_financials, get_metric
+
+# Get all financial facts from Apple's Q1 2025 10-Q
+result = get_financials("AAPL", 2025, 1)
+for fact in result["facts"][:5]:
+    print(f"{fact['metric']}: {fact['current_value']}")
+
+# Look up a single metric
+revenue = get_metric("AAPL", 2025, 1, "Revenue")
+print(f"Revenue: {revenue['value']} {revenue['unit']}")
+```
+
+Or use the lower-level API for more control:
+
+```python
+from edgar_parser import parse_filing, match_filing
+
+# Parse raw XBRL facts
+parsed = parse_filing("AAPL", 2025, 1, full_year_mode=False)
+
+# Match current vs. prior periods
+matched = match_filing(parsed)
+print(matched.head())
+```
+
+## Key functions
+
+| Function | Module | Description |
+|----------|--------|-------------|
+| `get_financials` | `tools` | All facts for a ticker/period, with caching |
+| `get_filings` | `tools` | List SEC filings (10-Q, 10-K, 8-K) for a period |
+| `get_metric` | `tools` | Single metric lookup with fuzzy matching |
+| `get_filing_sections` | `tools` | Qualitative section text (Risk Factors, MD&A, etc.) |
+| `parse_filing` | `pipeline` | Low-level XBRL fact extraction |
+| `enrich_filing` | `pipeline` | Fiscal period categorization and enrichment |
+| `match_filing` | `matching` | Current vs. prior period alignment |
+| `find_8k_for_period` | `earnings_8k` | Find 8-K earnings release for a fiscal period |
+
+## Requirements
+
+- Python 3.10+
+- No API key needed — data comes directly from SEC EDGAR (public)
+- Optional: `ANTHROPIC_API_KEY` environment variable for 8-K extraction

edgar_parser-0.1.0/edgar_parser/__init__.py

@@ -0,0 +1,4 @@
+"""edgar-parser: structured financial data from SEC EDGAR filings."""
+
+from .pipeline import FilingNotFoundError, enrich_filing, parse_filing
+from .matching import match_filing

edgar_parser-0.1.0/edgar_parser/config.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python
+# coding: utf-8
+
+from dotenv import load_dotenv
+load_dotenv()
+
+# === CONFIG & SETUP ==========================================
+
+# === HEADERS ======
+HEADERS = {
+    "User-Agent": "edgar-parser (Python library; github.com/henrysouchien/edgar-parser)",
+    "Accept-Encoding": "gzip, deflate",
+}
+
+TICKER_CIK_URL = "https://www.sec.gov/files/company_tickers.json"
+
+# === NUMBER OF FILINGS TO PULL ======
+N_10Q = 12
+N_10K = 4
+
+# === EXTRA FILING PULLS ===
+N_10Q_EXTRA = 0
+N_10K_EXTRA = 0
+
+# === SAFE LIMIT TIMES ===
+REQUEST_DELAY = 1  # in seconds
+
+# === EXPORTS ===
+OUTPUT_METRICS_DIR = "metrics"
+EXPORT_UPDATER_DIR = "exports"
+
+# 8-K earnings release extraction
+ANTHROPIC_MODEL_8K = "claude-sonnet-4-20250514"
+MAX_8K_HTML_BYTES = 500_000
+