{"id":47473112,"url":"https://github.com/ryansmccoy/py-sec-edgar","last_synced_at":"2026-04-13T15:03:17.666Z","repository":{"id":34488211,"uuid":"135492609","full_name":"ryansmccoy/py-sec-edgar","owner":"ryansmccoy","description":"Python application used to download, parse, and extract structured/unstructured data from filings in the SEC Edgar Database (including 10-K, 10-Q, 13-D, S-1, 8-K, etc.)","archived":false,"fork":false,"pushed_at":"2026-03-25T21:41:09.000Z","size":9330,"stargazers_count":123,"open_issues_count":4,"forks_count":21,"subscribers_count":6,"default_branch":"master","last_synced_at":"2026-04-08T21:03:00.587Z","etag":null,"topics":["financial","financial-data","financial-markets","gov","open-data","sec","sec-edgar","stock-market","united-states"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ryansmccoy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.rst","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap/INTEGRATION_OPPORTUNITIES.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-05-30T20:11:28.000Z","updated_at":"2026-03-27T23:35:42.000Z","dependencies_parsed_at":"2022-08-08T01:01:14.429Z","dependency_job_id":"de588630-1cc4-4246-b426-c5cb8f682323","html_url":"https://github.com/ryansmccoy/py-sec-edgar","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ryansmccoy/py-sec-edgar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryansmccoy%2Fpy-sec-edgar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryansmccoy%2Fpy-sec-edgar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryansmccoy%2Fpy-sec-edgar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryansmccoy%2Fpy-sec-edgar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ryansmccoy","download_url":"https://codeload.github.com/ryansmccoy/py-sec-edgar/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ryansmccoy%2Fpy-sec-edgar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31757482,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T13:27:56.013Z","status":"ssl_error","status_checked_at":"2026-04-13T13:21:23.512Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["financial","financial-data","financial-markets","gov","open-data","sec","sec-edgar","stock-market","united-states"],"created_at":"2026-03-25T10:00:25.232Z","updated_at":"2026-04-13T15:03:17.647Z","avatar_url":"https://github.com/ryansmccoy.png","language":"Python","funding_links":[],"categories":["Libraries \u0026 Tools"],"sub_categories":["Python"],"readme":"# py-sec-edgar: Professional SEC EDGAR Filing Processor\n\n\u003cdiv align=\"center\"\u003e\n\n[![PyPI version](https://badge.fury.io/py/py-sec-edgar.svg)](https://badge.fury.io/py/py-sec-edgar)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Documentation Status](https://readthedocs.org/projects/py-sec-edgar/badge/?version=latest)](https://py-sec-edgar.readthedocs.io/en/latest/?badge=latest)\n[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n[![Tests](https://github.com/ryansmccoy/py-sec-edgar/workflows/Tests/badge.svg)](https://github.com/ryansmccoy/py-sec-edgar/actions)\n[![Coverage](https://codecov.io/gh/ryansmccoy/py-sec-edgar/branch/master/graph/badge.svg)](https://codecov.io/gh/ryansmccoy/py-sec-edgar)\n[![GitHub stars](https://img.shields.io/github/stars/ryansmccoy/py-sec-edgar.svg)](https://github.com/ryansmccoy/py-sec-edgar/stargazers)\n\n**A powerful, modern Python application for downloading, processing, and analyzing SEC EDGAR filings with professional-grade workflow automation.**\n\n[🚀 Quick Start](#-quick-start) • [📖 Documentation](#-documentation) • [💼 Examples](#-comprehensive-examples) • [🔧 Installation](#-installation) • [⚡ Workflows](#-powerful-workflows)\n\n\u003c/div\u003e\n\n---\n\npy-sec-edgar transforms complex SEC filing data into accessible, structured information with enterprise-grade reliability and ease of use:\n\n### 🎯 **Key Features**\n- **🏗️ Professional Workflow System**: Four specialized workflows for different data collection needs\n- **⚡ High-Performance Processing**: Efficient bulk download and processing of SEC archives\n- **🎛️ Advanced Filtering**: Filter by ticker symbols, form types, date ranges, and more\n- **🔄 Real-Time Monitoring**: RSS feed integration for live filing notifications\n- **📊 Structured Data Extraction**: Extract and parse filing contents automatically\n- **🛡️ Enterprise-Ready**: Robust error handling, logging, and configuration management\n- **🐍 Modern Python**: Built with Python 3.10+, type hints, and modern best practices\n\n### 🎪 **Use Cases**\n- **📈 Investment Research**: Download 10-K/10-Q filings for fundamental analysis\n- **🔍 Compliance Monitoring**: Track insider trading (Form 4) and ownership changes\n- **📰 News \u0026 Events**: Monitor 8-K filings for material corporate events\n- **🏫 Academic Research**: Bulk download historical filing data for studies\n- **🤖 Machine Learning**: Create datasets for NLP and financial prediction models\n- **📊 Portfolio Management**: Automated due diligence for investment portfolios\n\n---\n\n## 🚀 Quick Start\n\nGet up and running with py-sec-edgar in under 2 minutes:\n\n### 1. Install with uv (Recommended)\n```bash\n# Install uv if you haven't already\npip install uv\n\n# Clone and setup the project\ngit clone https://github.com/ryansmccoy/py-sec-edgar.git\ncd py-sec-edgar\n\n# Install dependencies\nuv sync\n\n# Verify installation\nuv run python -m py_sec_edgar --help\n```\n\n### 2. Your First Filing Download\n```bash\n# First, explore what's available without downloading (safe exploration)\nuv run python -m py_sec_edgar workflows rss --show-entries --count 10 --list-only\n\n# See what Apple filings are available without downloading\nuv run python -m py_sec_edgar workflows daily --tickers AAPL --days-back 7 --forms \"8-K\" --no-download\n\n# When ready, download Apple's latest 10-K annual report (includes 2025Q3 data)\nuv run python -m py_sec_edgar workflows full-index --tickers AAPL --forms \"10-K\" --download --extract\n\n# Process the latest quarterly data (2025Q3)\nuv run python -m py_sec_edgar workflows full-index --quarter 2025Q3 --download --extract\n\n# Monitor recent filings for your portfolio (explore first, then download)\nuv run python -m py_sec_edgar workflows daily --tickers AAPL --tickers MSFT --tickers GOOGL --days-back 7 --forms \"8-K\" --no-download\n# When satisfied, add --download flag to actually download files\n\n# Monitor Apple's earnings announcement from August 1, 2024\nuv run python -m py_sec_edgar workflows daily --tickers AAPL --start-date 2024-08-01 --end-date 2024-08-01 --forms \"8-K\" --download --extract\n\n# Real-time RSS monitoring (list mode for exploration)\nuv run python -m py_sec_edgar workflows rss --show-entries --count 10 --list-only\n```\n\n### 3. Explore Your Data\n```bash\n# Your downloaded filings are organized like this:\nsec_data/\n├── Archives/edgar/data/\n│   └── 320193/                    # Apple's CIK\n│       └── 000032019324000123/    # Specific filing\n│           ├── aapl-20240930.htm  # Main 10-K document\n│           ├── exhibits/          # All exhibits\n│           └── Financial_Report.xlsx  # Structured financial data\n```\n\n---\n\n## 🔧 Installation\n\n### Prerequisites\n- **Python 3.10+** (Required)\n- **uv package manager** (Recommended) or pip\n- **5GB+ disk space** for substantial data collection\n\n### Method 1: Development Installation (Recommended)\n```bash\n# Clone the repository\ngit clone https://github.com/ryansmccoy/py-sec-edgar.git\ncd py-sec-edgar\n\n# Install with uv (handles everything automatically)\nuv sync\n\n# Install with pip (alternative)\npip install -e .\n```\n\n### Method 2: Direct Installation\n```bash\n# Install from PyPI\npip install py-sec-edgar\n\n# Or with uv\nuv pip install py-sec-edgar\n```\n\n### Method 3: Production Installation\n```bash\n# For production environments\nuv pip install py-sec-edgar[prod]\n\n# For development with all tools\nuv sync --extra dev\n```\n\n---\n\n## ⚡ Powerful Workflows\n\npy-sec-edgar provides four specialized workflows, each optimized for different use cases. Each workflow has **comprehensive documentation** with dozens of real-world examples:\n\n\u003cdiv align=\"center\"\u003e\n\n| Workflow | Best For | Data Source | Time Range | Full Documentation |\n|----------|----------|-------------|------------|-------------------|\n| **📚 Full Index** | Historical research, bulk analysis | Quarterly archives | All historical data | **[📖 Complete Guide](docs/workflows/FULL_INDEX_WORKFLOW.md)** |\n| **📅 Daily** | Recent monitoring, current events | Daily index feeds | Last 1-90 days | **[📖 Complete Guide](docs/workflows/DAILY_WORKFLOW.md)** |\n| **📊 Monthly** | XBRL structured data | Monthly XBRL archives | Monthly intervals | **[📖 Complete Guide](docs/workflows/MONTHLY_WORKFLOW.md)** |\n| **📡 RSS** | Real-time monitoring | Live RSS feeds | Real-time updates | **[📖 Complete Guide](docs/workflows/RSS_WORKFLOW.md)** |\n\n\u003c/div\u003e\n\n### 📅 **SEC Data Availability \u0026 Update Schedule**\n\nUnderstanding when SEC data is available helps you choose the right workflow for your needs:\n\n\u003cdiv align=\"center\"\u003e\n\n| Data Type | Update Frequency | Availability | Best Workflow | Notes |\n|-----------|------------------|--------------|---------------|--------|\n| **🔴 Live Filings** | Real-time | As filed | **RSS** | Immediate access to new filings |\n| **📊 Daily Index** | Nightly at 10 PM ET | Previous business day | **Daily** | Complete daily filing lists |\n| **📈 Full Index** | Updated throughout quarter | Current quarter + historical | **Full Index** | Comprehensive quarterly data |\n| **📋 Quarterly Index** | End of quarter | Complete quarter (static) | **Full Index** | Final quarterly archives |\n| **🔄 Weekly Rebuild** | Saturday mornings | All corrected data | **All workflows** | Post-acceptance corrections included |\n\n\u003c/div\u003e\n\n**Key Update Schedule Details:**\n- **🌙 Daily Index Files**: Updated nightly starting around 10:00 PM ET with the previous business day's filings\n- **📊 Full Index Files**: Updated continuously throughout the current quarter, including all filings from quarter start through the previous business day\n- **📅 Quarterly Index Files**: Static archives created at quarter-end containing the complete, final quarterly data\n- **🔧 Weekly Rebuilds**: Every Saturday morning, all full and quarterly index files are rebuilt to incorporate post-acceptance corrections and amendments\n- **⚡ Real-time RSS**: Live feed updated immediately as filings are accepted by the SEC\n\n**📖 Data Currency Best Practices:**\n- **For current events**: Use RSS workflow for immediate access to breaking filings\n- **For recent activity**: Use Daily workflow for systematic monitoring of the last 1-90 days\n- **For historical research**: Use Full Index workflow for comprehensive quarterly archives\n- **For completeness**: Wait until Saturday morning rebuild for the most accurate quarterly data\n\n\u003e 💡 **Pro Tip**: Each workflow documentation contains 20+ practical examples, from basic usage to advanced enterprise patterns. Start with the [Workflow Documentation Hub](docs/workflows/) for complete coverage!\n\n### 📚 Full Index Workflow\n*Perfect for comprehensive historical analysis and bulk data collection*\n\n```bash\n# First, explore what's available for Apple without downloading\nuv run python -m py_sec_edgar workflows full-index --tickers AAPL --no-download\n\n# When ready, download all Apple filings from quarterly archives\nuv run python -m py_sec_edgar workflows full-index --tickers AAPL --download\n\n# Process the latest quarterly data (2025Q3) with extraction\nuv run python -m py_sec_edgar workflows full-index --quarter 2025Q3 --download --extract\n\n# Investment research: Explore tech giants first, then download\nuv run python -m py_sec_edgar workflows full-index \\\n    --tickers AAPL --tickers MSFT --tickers GOOGL --tickers AMZN --tickers META \\\n    --forms \"10-K\" \\\n    --no-download  # Remove this flag when ready to download\n\n# Academic research: Fortune 500 analysis with latest data\nuv run python -m py_sec_edgar workflows full-index \\\n    --ticker-file examples/fortune500.csv \\\n    --forms \"10-K\" \"10-Q\" \\\n    --quarter 2025Q3 \\\n    --download --extract\n```\n\n### 📅 Daily Workflow\n*Ideal for monitoring recent activity and staying current*\n\n```bash\n# Explore yesterday's filings without downloading first\nuv run python -m py_sec_edgar workflows daily --days-back 1 --no-download\n\n# When ready, download yesterday's filings\nuv run python -m py_sec_edgar workflows daily --days-back 1 --download\n\n# Weekly portfolio monitoring (explore first)\nuv run python -m py_sec_edgar workflows daily \\\n    --ticker-file examples/portfolio.csv \\\n    --days-back 7 \\\n    --forms \"8-K\" \"4\" \\\n    --no-download  # Remove this flag when ready to download\n\n# Monitor Apple's specific earnings announcement (August 1, 2024)\nuv run python -m py_sec_edgar workflows daily \\\n    --tickers AAPL \\\n    --start-date 2024-08-01 \\\n    --end-date 2024-08-01 \\\n    --forms \"8-K\" \\\n    --download --extract  # Direct download since we know what we want\n```\n\n### 📊 Monthly Workflow\n*Specialized for XBRL structured financial data*\n\n```bash\n# Explore what structured financial data is available (6 months)\nuv run python -m py_sec_edgar workflows monthly --months-back 6 --no-download\n\n# Download structured financial data when ready\nuv run python -m py_sec_edgar workflows monthly --months-back 6 --download\n\n# Focus on specific companies with extraction\nuv run python -m py_sec_edgar workflows monthly \\\n    --tickers AAPL --tickers MSFT \\\n    --months-back 12 \\\n    --download --extract\n```\n\n### 📡 RSS Workflow\n*Real-time monitoring and live feed processing*\n\n```bash\n# Explore latest filings in real-time (safe exploration)\nuv run python -m py_sec_edgar workflows rss --show-entries --count 20 --list-only\n\n# Monitor specific companies (list mode first)\nuv run python -m py_sec_edgar workflows rss \\\n    --query-ticker AAPL \\\n    --count 10 \\\n    --show-entries --list-only\n\n# When ready to process/download, remove --list-only flag\nuv run python -m py_sec_edgar workflows rss \\\n    --query-ticker AAPL \\\n    --count 10 \\\n    --download\n\n# Save RSS data for analysis (no download, just save feed data)\nuv run python -m py_sec_edgar workflows rss \\\n    --save-file rss_filings.json \\\n    --count 100 \\\n    --list-only\n```\n\n---\n\n## 💼 Comprehensive Examples\n\n### 🏢 Investment Research Workflow\n\n**Scenario**: You're analyzing potential investments in the renewable energy sector.\n\n```bash\n# Step 1: Use the provided renewable energy ticker list\n# File: examples/renewable_energy.csv (already created)\n\n# Step 2: Explore historical annual reports first (no download)\nuv run python -m py_sec_edgar workflows full-index \\\n    --ticker-file examples/renewable_energy.csv \\\n    --forms \"10-K\" \\\n    --no-download\n\n# Step 3: When ready, get historical annual reports with extraction\nuv run python -m py_sec_edgar workflows full-index \\\n    --ticker-file examples/renewable_energy.csv \\\n    --forms \"10-K\" \\\n    --download --extract\n\n# Step 4: Process specific quarterly filings (2025Q3)\nuv run python -m py_sec_edgar workflows full-index \\\n    --ticker-file examples/renewable_energy.csv \\\n    --quarter 2025Q3 \\\n    --forms \"10-Q\" \\\n    --download --extract\n\n# Step 5: Monitor recent Tesla activity (last 30 days for better data coverage)\nuv run python -m py_sec_edgar workflows daily \\\n    --tickers TSLA \\\n    --days-back 30 \\\n    --forms \"8-K\" \\\n    --no-download  # Explore first, then add --download when ready\n\n# Step 6: Set up real-time monitoring (exploration mode)\nuv run python -m py_sec_edgar workflows rss \\\n    --query-ticker TSLA \\\n    --count 10 \\\n    --show-entries --list-only\n```\n\n**Result**: Complete dataset with historical context, recent activity, and real-time monitoring setup.\n\n### 📊 Academic Research Pipeline\n\n**Scenario**: Studying CEO compensation trends across S\u0026P 500 companies.\n\n```bash\n# Step 1: Explore proxy statements availability (no download)\nuv run python -m py_sec_edgar workflows full-index \\\n    --ticker-file examples/sp500_tickers.csv \\\n    --forms \"DEF 14A\" \\\n    --no-download\n\n# Step 2: Download proxy statements when ready\nuv run python -m py_sec_edgar workflows full-index \\\n    --ticker-file examples/sp500_tickers.csv \\\n    --forms \"DEF 14A\" \\\n    --download --extract\n\n# Step 3: Process latest quarterly data (2025Q3) for comprehensive analysis\nuv run python -m py_sec_edgar workflows full-index \\\n    --ticker-file examples/sp500_tickers.csv \\\n    --quarter 2025Q3 \\\n    --forms \"10-Q\" \"DEF 14A\" \\\n    --download --extract\n\n# Step 4: Get recent quarterly filings (last 60 days for good data coverage)\nuv run python -m py_sec_edgar workflows daily \\\n    --ticker-file examples/sp500_tickers.csv \\\n    --days-back 60 \\\n    --forms \"10-Q\" \\\n    --no-download  # Explore first\n\n# Step 5: Extract structured financial data for analysis\nuv run python -m py_sec_edgar workflows monthly \\\n    --ticker-file examples/sp500_tickers.csv \\\n    --months-back 12 \\\n    --download --extract\n```\n\n### 🔍 Compliance Monitoring System\n\n**Scenario**: Monitor insider trading and ownership changes for your portfolio.\n\n```bash\n# Step 1: Explore recent insider trading (Form 4) - last 7 days\nuv run python -m py_sec_edgar workflows daily \\\n    --ticker-file examples/portfolio.csv \\\n    --days-back 7 \\\n    --forms \"4\" \\\n    --no-download  # Explore first\n\n# Step 2: When ready, download recent insider trading data\nuv run python -m py_sec_edgar workflows daily \\\n    --ticker-file examples/portfolio.csv \\\n    --days-back 14 \\\n    --forms \"4\" \\\n    --download --extract\n\n# Step 3: Track large ownership changes (last 30 days)\nuv run python -m py_sec_edgar workflows daily \\\n    --ticker-file examples/portfolio.csv \\\n    --days-back 30 \\\n    --forms \"SC 13G\" \"SC 13D\" \\\n    --download --extract\n\n# Step 4: Set up real-time insider trading alerts (exploration mode)\nuv run python -m py_sec_edgar workflows rss \\\n    --query-form \"4\" \\\n    --count 25 \\\n    --show-entries --list-only\n```\n\n### 📰 News \u0026 Events Monitoring\n\n**Scenario**: Stay ahead of market-moving news with automated 8-K monitoring.\n\n```bash\n# Monitor Apple's recent activity (last 30 days for good coverage)\nuv run python -m py_sec_edgar workflows daily \\\n    --tickers AAPL \\\n    --days-back 30 \\\n    --forms \"8-K\" \\\n    --no-download  # Explore first, then add --download\n\n# Monitor Tesla's recent activity (last 30 days)\nuv run python -m py_sec_edgar workflows daily \\\n    --tickers TSLA \\\n    --days-back 30 \\\n    --forms \"8-K\" \\\n    --no-download  # Explore first\n\n# When ready to download Apple's recent annual reports\nuv run python -m py_sec_edgar workflows daily \\\n    --tickers AAPL \\\n    --days-back 90 \\\n    --forms \"10-K\" \\\n    --download --extract\n\n# Set up comprehensive current events monitoring (exploration mode)\nuv run python -m py_sec_edgar workflows rss \\\n    --query-form \"8-K\" \\\n    --show-entries \\\n    --count 25 \\\n    --list-only\n\n# Advanced: Monitor multiple companies for 8-K filings\nuv run python -m py_sec_edgar workflows daily \\\n    --ticker-file examples/portfolio.csv \\\n    --days-back 14 \\\n    --forms \"8-K\" \\\n    --no-download\n```\n\n---\n\n## 🗂️ Understanding SEC Filings\n\npy-sec-edgar makes it easy to work with SEC filings, but understanding what each form contains helps you choose the right data:\n\n### 📋 Essential Form Types\n\n| Form | Description | Frequency | Key Content |\n|------|-------------|-----------|-------------|\n| **10-K** | Annual Report | Yearly | Complete business overview, audited financials, risk factors |\n| **10-Q** | Quarterly Report | Quarterly | Unaudited quarterly financials, updates since last 10-K |\n| **8-K** | Current Events | As needed | Material corporate events, breaking news |\n| **DEF 14A** | Proxy Statement | Annually | Executive compensation, board elections, shareholder proposals |\n| **4** | Insider Trading | Within 2 days | Executive stock transactions |\n| **SC 13G/D** | Beneficial Ownership | When threshold crossed | Large shareholder positions (\u003e5%) |\n\n### 🏗️ How SEC Data is Organized\n\n**SEC Website Structure:**\n```\nhttps://www.sec.gov/Archives/edgar/data/[CIK]/[AccessionNumber]/[Filename]\n```\n\n**py-sec-edgar Local Structure:**\n```\nsec_data/\n├── Archives/edgar/\n│   ├── full-index/           # Downloaded quarterly archives\n│   │   ├── 2024/QTR1/\n│   │   ├── 2024/QTR2/\n│   │   └── 2025/QTR3/        # Latest quarterly data\n│   └── data/                 # Extracted filing contents\n│       └── [CIK]/            # Company folders (e.g., 320193 for Apple)\n│           └── [Filing]/     # Individual filing folders\n│               ├── main_document.htm\n│               ├── exhibits/\n│               └── Financial_Report.xlsx\n```\n\n### 🔍 Understanding Company Identifiers\n\n**Central Index Key (CIK)**: Unique numerical identifier assigned by SEC\n- Example: Apple Inc. = 320193\n- Permanent, never recycled\n- Used in all SEC filings and URLs\n\n**Ticker Symbol**: Stock exchange trading symbol\n- Example: AAPL for Apple Inc.\n- Can change due to rebranding, mergers\n- py-sec-edgar handles ticker-to-CIK mapping automatically\n\n### 📊 Filing Statistics (Historical Context)\n\n| Form Type | Total Filings | Average per Year | Primary Use Case |\n|-----------|---------------|------------------|------------------|\n| Form 4 | 6,420,154 | ~800,000 | Insider trading monitoring |\n| 8-K | 1,473,193 | ~180,000 | Breaking news and events |\n| 10-Q | 552,059 | ~70,000 | Quarterly earnings analysis |\n| 10-K | 180,787 | ~22,000 | Annual comprehensive analysis |\n| 13F-HR | 224,996 | ~28,000 | Institutional holdings tracking |\n\n---\n\n## 🎛️ Advanced Configuration\n\n### ⚙️ Environment Configuration\n\npy-sec-edgar works out of the box with sensible defaults from `.env.example`. For custom configuration, create a `.env` file:\n\n```bash\n# Copy the example file and customize\ncp .env.example .env\n```\n\nKey environment variables:\n\n```bash\n# SEC Data Directory (cross-platform)\nSEC_DATA_DIR=./sec_data\n\n# User Agent (Required by SEC)\nUSER_AGENT=\"YourCompany AdminContact@yourcompany.com\"\n\n# Request Settings (Conservative defaults)\nREQUEST_DELAY=5.5\nMAX_RETRIES=3\n\n# Logging Configuration\nLOG_LEVEL=WARNING\nDEBUG=false\n```\n\n\u003e 💡 **Important**: You must update `USER_AGENT` with your contact information for production use, as required by SEC guidelines.\n\n### 📝 Ticker File Format\n\nCreate CSV files with ticker symbols (or use the provided examples):\n\n```csv\n# examples/portfolio.csv\nTICKER\nAAPL\nMSFT\nGOOGL\nAMZN\nTSLA\n\n# Or simple format\nAAPL\nMSFT\nGOOGL\n```\n\n### 🔧 Programmatic Usage\n\npy-sec-edgar provides two Python APIs for programmatic usage:\n\n#### Simple API (`SEC` class) - Quick Downloads\n```python\nfrom py_sec_edgar import SEC, Forms\n\nasync with SEC(data_dir=\"./sec_data\") as sec:\n    # Download filings for specific companies\n    result = await sec.download(\n        tickers=[\"AAPL\", \"MSFT\"],\n        forms=[Forms.FORM_10K],\n        days=365\n    )\n    print(f\"Downloaded {result.file_count} files\")\n\n    # List downloaded filings\n    filings = await sec.list_filings(ticker=\"AAPL\")\n```\n\n#### Advanced API (`SECFeed` class) - Full FeedSpine Integration\n```python\nfrom py_sec_edgar import SECFeed, SECFeedConfig\nfrom py_sec_edgar.reporters import RichProgressReporter\n\n# SECFeed provides: DuckDB storage, blob storage, search, caching\nasync with SECFeed(\n    tickers=[\"AAPL\", \"MSFT\"],\n    forms=[\"10-K\", \"10-Q\"],\n    days=365,\n    enable_search=True,\n    enable_cache=True,\n) as feed:\n    # Collect with progress reporting\n    await feed.collect(progress=RichProgressReporter())\n\n    # Typed access to filings\n    async for filing in feed.filings(form_type=\"10-K\"):\n        print(f\"{filing.content.company_name}: {filing.content.accession_number}\")\n\n    # Full-text search\n    results = await feed.search(\"revenue growth\", limit=10)\n\n    # Download documents (cached in blob storage)\n    doc = await feed.download_document(filing_url)\n```\n\n#### Workflow Functions\n```python\nfrom py_sec_edgar.workflows import (\n    run_full_index_workflow,\n    run_daily_workflow,\n    run_monthly_workflow,\n    run_rss_workflow\n)\n\n# Run full index workflow\nrun_full_index_workflow(\n    tickers=[\"AAPL\", \"MSFT\"],\n    forms=[\"10-K\", \"10-Q\"],\n    extract=True\n)\n\n# Monitor recent filings\nrun_daily_workflow(\n    tickers=[\"AAPL\", \"MSFT\"],\n    days_back=7,\n    forms=[\"8-K\"],\n    extract=True\n)\n```\n\n---\n\n## 🔨 Development \u0026 Contribution\n\n### 🏗️ Development Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/ryansmccoy/py-sec-edgar.git\ncd py-sec-edgar\n\n# Setup development environment\nuv sync --extra dev\n\n# Install pre-commit hooks\nuv run pre-commit install\n\n# Run tests\nuv run pytest\n\n# Run linting\nuv run ruff check\nuv run ruff format\n\n# Type checking\nuv run mypy src/\n```\n\n### 🧪 Testing\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=py_sec_edgar --cov-report=html\n\n# Run specific test categories\nuv run pytest -m \"not slow\"          # Skip slow tests\nuv run pytest -m integration         # Integration tests only\nuv run pytest tests/test_filing.py   # Specific test file\n```\n\n### 📊 Performance Testing\n\n```bash\n# Test with small dataset\nuv run python -m py_sec_edgar workflows full-index \\\n    --tickers AAPL \\\n    --forms \"10-K\" \\\n    --no-extract\n\n# Benchmark larger operations\ntime uv run python -m py_sec_edgar workflows daily \\\n    --tickers AAPL --tickers MSFT --tickers GOOGL \\\n    --days-back 30 \\\n    --extract\n```\n\n---\n\n## 📖 Documentation\n\n### 📚 Comprehensive Guides\n\n- **[Full Documentation](https://py-sec-edgar.readthedocs.io)**: Complete API reference and guides\n- **[Workflow Documentation Hub](docs/workflows/)**: Detailed workflow guides with comprehensive examples\n  - **[📚 Full Index Workflow](docs/workflows/FULL_INDEX_WORKFLOW.md)**: Complete quarterly archive processing for historical research\n  - **[📅 Daily Workflow](docs/workflows/DAILY_WORKFLOW.md)**: Recent filings monitoring and systematic updates\n  - **[📊 Monthly Workflow](docs/workflows/MONTHLY_WORKFLOW.md)**: XBRL structured data processing for quantitative analysis\n  - **[📡 RSS Workflow](docs/workflows/RSS_WORKFLOW.md)**: Real-time RSS feed processing with advanced querying\n\n### 🔗 Quick References\n\n- **[CLI Reference](docs/cli-reference.md)**: Complete command-line interface documentation\n- **[Configuration Guide](docs/configuration.md)**: Environment and settings configuration\n- **[API Reference](docs/api-reference.md)**: Programmatic usage documentation\n- **[Troubleshooting](docs/troubleshooting.md)**: Common issues and solutions\n\n---\n\n## 🚨 Important Notes\n\n### ⚖️ SEC Compliance\n- **User Agent Required**: The SEC requires a proper User-Agent header with your contact information\n- **Rate Limiting**: py-sec-edgar includes respectful rate limiting (0.1s delay by default)\n- **Fair Use**: Please be respectful of SEC resources and don't overwhelm their servers\n\n### 💾 Storage Requirements\n- **Full Index Processing**: Can generate several GB of data per quarter\n- **Extracted Content**: Individual filings can be 10-100MB when extracted\n- **Recommendation**: Start with specific tickers/forms, then scale up\n\n### 🔒 Data Privacy\n- **Public Data Only**: All data accessed is publicly available SEC filings\n- **No Personal Info**: py-sec-edgar only accesses corporate disclosure documents\n- **Compliance Ready**: Suitable for professional and academic use\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n### 🐛 Reporting Issues\n1. Check existing [issues](https://github.com/ryansmccoy/py-sec-edgar/issues)\n2. Create detailed bug reports with examples\n3. Include system information and error logs\n\n### 🔧 Contributing Code\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes with tests\n4. Run the test suite: `uv run pytest`\n5. Submit a pull request\n\n### 📝 Contributing Documentation\n- Improve existing documentation\n- Add new examples and use cases\n- Create tutorials for specific workflows\n\n---\n\n## 📄 License\n\npy-sec-edgar is dual-licensed:\n\n- **Personal Use**: MIT License (free for personal, educational, and research use)\n- **Commercial Use**: GNU AGPLv3 License (free with copyleft requirements)\n- **Business Licensing**: Contact [github@ryansmccoy.com](mailto:github@ryansmccoy.com) for commercial licensing options\n\nSee [LICENSE](LICENSE) for full details.\n\n---\n\n## 📞 Support \u0026 Community\n\n### 💬 Getting Help\n- **[GitHub Issues](https://github.com/ryansmccoy/py-sec-edgar/issues)**: Bug reports and feature requests\n- **[Discussions](https://github.com/ryansmccoy/py-sec-edgar/discussions)**: Questions and community support\n- **[Documentation](https://py-sec-edgar.readthedocs.io)**: Comprehensive guides and API reference\n\n### 📧 Professional Support\n- **Business Inquiries**: [github@ryansmccoy.com](mailto:github@ryansmccoy.com)\n- **Commercial Licensing**: Available for enterprise use\n- **Custom Development**: Professional services available\n\n---\n\n## 🙏 Acknowledgments\n\n- **SEC EDGAR System**: For providing free access to corporate filing data\n- **Python Community**: For the excellent libraries that make this project possible\n- **Contributors**: Everyone who has contributed code, documentation, and feedback\n- **Users**: The community that drives continuous improvement\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**⭐ Star this repository if py-sec-edgar helps your financial analysis! ⭐**\n\n**Built with ❤️ for the financial analysis and research community**\n\n[🏠 Homepage](https://github.com/ryansmccoy/py-sec-edgar) • [📖 Docs](https://py-sec-edgar.readthedocs.io) • [🐛 Issues](https://github.com/ryansmccoy/py-sec-edgar/issues) • [💬 Discussions](https://github.com/ryansmccoy/py-sec-edgar/discussions)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryansmccoy%2Fpy-sec-edgar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fryansmccoy%2Fpy-sec-edgar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fryansmccoy%2Fpy-sec-edgar/lists"}