278 lines
11 KiB
Plaintext
278 lines
11 KiB
Plaintext
Metadata-Version: 2.3
|
|
Name: edgartools
|
|
Version: 4.25.0
|
|
Summary: Navigate Edgar filings with ease
|
|
Project-URL: Documentation, https://dgunning.github.io/edgartools/
|
|
Project-URL: Issues, https://github.com/dgunning/edgartools/issues
|
|
Project-URL: Source, https://github.com/dgunning/edgartools
|
|
Author-email: Dwight Gunning <dgunning@gmail.com>
|
|
License: MIT
|
|
Keywords: company,edgar,filings,finance,financial,python,reports,sec
|
|
Classifier: Development Status :: 4 - Beta
|
|
Classifier: License :: OSI Approved :: MIT License
|
|
Classifier: Programming Language :: Python
|
|
Classifier: Programming Language :: Python :: 3.10
|
|
Classifier: Programming Language :: Python :: 3.11
|
|
Classifier: Programming Language :: Python :: 3.12
|
|
Classifier: Programming Language :: Python :: 3.13
|
|
Classifier: Programming Language :: Python :: 3.14
|
|
Classifier: Programming Language :: Python :: Implementation :: CPython
|
|
Classifier: Programming Language :: Python :: Implementation :: PyPy
|
|
Requires-Python: >=3.10
|
|
Requires-Dist: beautifulsoup4>=4.10.0
|
|
Requires-Dist: hishel==0.1.3
|
|
Requires-Dist: httpx>=0.25.0
|
|
Requires-Dist: httpxthrottlecache>=0.1.6
|
|
Requires-Dist: humanize>=4.0.0
|
|
Requires-Dist: jinja2>=3.1.0
|
|
Requires-Dist: lxml>=4.4
|
|
Requires-Dist: nest-asyncio>=1.5.1
|
|
Requires-Dist: orjson>=3.6.0
|
|
Requires-Dist: pandas>=2.0.0
|
|
Requires-Dist: pyarrow>=17.0.0
|
|
Requires-Dist: pydantic>=2.0.0
|
|
Requires-Dist: rank-bm25>=0.2.1
|
|
Requires-Dist: rapidfuzz>=3.5.0
|
|
Requires-Dist: rich>=13.8.0
|
|
Requires-Dist: stamina>=24.2.0
|
|
Requires-Dist: tabulate>=0.9.0
|
|
Requires-Dist: textdistance>=4.5.0
|
|
Requires-Dist: tqdm>=4.62.0
|
|
Requires-Dist: unidecode>=1.2.0
|
|
Provides-Extra: ai
|
|
Requires-Dist: mcp==1.12.3; (python_version >= '3.10') and extra == 'ai'
|
|
Requires-Dist: tiktoken>=0.10.0; extra == 'ai'
|
|
Provides-Extra: ai-dev
|
|
Requires-Dist: pytest-mock>=3.12.0; extra == 'ai-dev'
|
|
Requires-Dist: responses>=0.24.0; extra == 'ai-dev'
|
|
Provides-Extra: data
|
|
Requires-Dist: duckdb>=1.0.0; extra == 'data'
|
|
Description-Content-Type: text/markdown
|
|
|
|
<p align="center">
|
|
<a href="https://github.com/dgunning/edgartools">
|
|
<img src="docs/images/edgartools-logo.png" alt="EdgarTools Python SEC EDGAR library logo" height="80">
|
|
</a>
|
|
</p>
|
|
|
|
<h3 align="center">Python Library for SEC EDGAR Data Extraction and Analysis</h3>
|
|
|
|
<p align="center">
|
|
<a href="https://pypi.org/project/edgartools"><img src="https://img.shields.io/pypi/v/edgartools.svg" alt="PyPI - Version"></a>
|
|
<a href="https://github.com/dgunning/edgartools/actions"><img src="https://img.shields.io/github/actions/workflow/status/dgunning/edgartools/python-hatch-workflow.yml" alt="GitHub Workflow Status"></a>
|
|
<a href="https://www.codefactor.io/repository/github/dgunning/edgartools"><img src="https://www.codefactor.io/repository/github/dgunning/edgartools/badge" alt="CodeFactor"></a>
|
|
<a href="https://github.com/pypa/hatch"><img src="https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg" alt="Hatch project"></a>
|
|
<a href="https://github.com/dgunning/edgartools/blob/main/LICENSE"><img src="https://img.shields.io/github/license/dgunning/edgartools" alt="GitHub"></a>
|
|
<a href="https://pypi.org/project/edgartools"><img src="https://img.shields.io/pypi/dm/edgartools" alt="PyPI - Downloads"></a>
|
|
</p>
|
|
|
|
<p align="center">
|
|
<b>Extract financial data from SEC EDGAR filings in 3 lines of Python code instead of 100+. Access company financials, insider trades, fund holdings, and XBRL data with an intuitive API designed for financial analysis.</b>
|
|
</p>
|
|
|
|
|
|
|
|
## SEC Filing Data Extraction with Python
|
|
|
|
| With EdgarTools | Without EdgarTools |
|
|
|-----------------------------------------------|---------------------------------------------|
|
|
| ✅ Instant access to any filing since 1994 | ❌ Hours spent navigating SEC.gov |
|
|
| ✅ Clean Python API with intuitive methods | ❌ Complex web scraping code |
|
|
| ✅ Automatic parsing into pandas DataFrames | ❌ Manual extraction of financial data |
|
|
| ✅ Specialized data objects for each form type | ❌ Custom code for each filing type |
|
|
| ✅ One-line conversion to clean, readable text | ❌ Messy HTML parsing for text extraction |
|
|
| ✅ LLM-ready text extraction for AI pipelines | ❌ Extra processing for AI/LLM compatibility |
|
|
| ✅ Automatic throttling to avoid blocks | ❌ Rate limiting headaches |
|
|
|
|
## Apple's income statement in 1 line of code
|
|
|
|
```python
|
|
balance_sheet = Company("AAPL").get_financials().balance_sheet()
|
|
```
|
|
|
|
## 🚀 Quick Start (2-minute tutorial)
|
|
|
|
```python
|
|
# 1. Import the library
|
|
from edgar import *
|
|
|
|
# 2. Tell the SEC who you are (required by SEC regulations)
|
|
set_identity("your.name@example.com") # Replace with your email
|
|
|
|
# 3. Find a company
|
|
company = Company("MSFT") # Microsoft
|
|
|
|
# 4. Get company filings
|
|
filings = company.get_filings()
|
|
|
|
# 5. Filter by form
|
|
insider_filings = filings.filter(form="4") # Insider transactions
|
|
|
|
# 6. Get the latest filing
|
|
insider_filing = insider_filings[0]
|
|
|
|
# 7. Convert to a data object
|
|
ownership = insider_filing.obj()
|
|
```
|
|
|
|
|
|
|
|
|
|
## SEC Filing Analysis: Real-World Solutions
|
|
|
|
### Company Financial Analysis
|
|
|
|
**Problem:** Need to analyze a company's financial health across multiple periods.
|
|
|
|
|
|
|
|
[See full code](docs/examples.md#company_financial_analysis)
|
|
|
|
|
|
|
|
## 📚 Documentation
|
|
|
|
|
|
- [User Journeys / Examples](https://edgartools.readthedocs.io/en/latest/examples/)
|
|
- [Quick Guide](https://edgartools.readthedocs.io/en/latest/quick-guide/)
|
|
- [Full API Documentation](https://edgartools.readthedocs.io/)
|
|
- [EdgarTools Blog](https://www.edgartools.io)
|
|
|
|
## 👥 Community & Support
|
|
|
|
- [GitHub Issues](https://github.com/dgunning/edgartools/issues) - Bug reports and feature requests
|
|
- [Discussions](https://github.com/dgunning/edgartools/discussions) - Questions and community discussions
|
|
|
|
## 🔮 Roadmap
|
|
|
|
- **Coming Soon**: Enhanced visualization tools for financial data
|
|
- **In Development**: Machine learning integrations for financial sentiment analysis
|
|
- **Planned**: Interactive dashboard for filing exploration
|
|
|
|
## 🤝 Contributing
|
|
|
|
We welcome contributions from the community! Here's how you can help:
|
|
|
|
- **Code**: Fix bugs, add features, improve documentation
|
|
- **Examples**: Share interesting use cases and examples
|
|
- **Feedback**: Report issues or suggest improvements
|
|
- **Spread the Word**: Star the repo, share with colleagues
|
|
|
|
See our [Contributing Guide](CONTRIBUTING.md) for details.
|
|
|
|
## ❤️ Sponsors & Support
|
|
|
|
If you find EdgarTools valuable, please consider supporting its development:
|
|
|
|
<a href="https://www.buymeacoffee.com/edgartools" target="_blank">
|
|
<img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 40px !important;width: 144px !important;" >
|
|
</a>
|
|
|
|
Your support helps maintain and improve EdgarTools for the entire community!
|
|
|
|
## Key Features for SEC Data Extraction and Analysis
|
|
|
|
- **Comprehensive Filing Access**: Retrieve **any** SEC filing (10-K, 10-Q, 8-K, 13F, S-1, Form 4, etc.) since 1994.
|
|
- **Financial Statement Extraction**: Easily access **Balance Sheets, Income Statements, Cash Flows**, and individual line items using XBRL tags or common names.
|
|
- **SEC EDGAR API**: Programmatic access to the complete SEC database.
|
|
- **Smart Data Objects**: Automatic parsing of filings into structured Python objects.
|
|
- **Fund Holdings Analysis**: Extract and analyze **13F holdings** data for investment managers.
|
|
- **Insider Transaction Monitoring**: Get structured data from **Form 3, 4, 5** filings.
|
|
- **Clean Text Extraction**: One-line conversion from filing HTML to clean, readable text suitable for NLP.
|
|
- **Targeted Section Extraction**: Pull specific sections like **Risk Factors (Item 1A)** or **MD&A (Item 7)**.
|
|
- **AI/LLM Ready**: Text formatting and chunking optimized for AI pipelines.
|
|
- **Performance Optimized**: Leverages libraries like `lxml` and potentially `PyArrow` for efficient data handling.
|
|
- **XBRL Support**: Extract and analyze XBRL-tagged data.
|
|
- **Intuitive API**: Simple, consistent interface for all data types.
|
|
|
|
## 🤖 AI-Native Integration
|
|
|
|
EdgarTools is designed from the ground up to work seamlessly with AI agents and LLM applications:
|
|
|
|
### Interactive Documentation
|
|
|
|
Every major object includes rich, searchable documentation accessible via the `.docs` property:
|
|
|
|
```python
|
|
from edgar import Company
|
|
|
|
company = Company("AAPL")
|
|
|
|
# Beautiful rich display with full API documentation
|
|
company.docs
|
|
|
|
# Search documentation with BM25 ranking
|
|
company.docs.search("get financials")
|
|
|
|
# AI-optimized text output for LLM context
|
|
context = company.text(detail='standard', max_tokens=500)
|
|
```
|
|
|
|
**3,450+ lines of API documentation** covering Company, Filing, XBRL, and Statement objects - always at your fingertips!
|
|
|
|
### AI Skills System
|
|
|
|
Extensible skill packages for specialized SEC analysis:
|
|
|
|
```python
|
|
from edgar.ai import list_skills, export_skill
|
|
|
|
# List available skills
|
|
skills = list_skills()
|
|
|
|
# Export to Claude Desktop format
|
|
export_skill("sec-analysis", format="claude-desktop")
|
|
```
|
|
|
|
Skills include:
|
|
- **Tutorial documentation** (skill.md, workflows.md, objects.md)
|
|
- **API reference** (complete method documentation)
|
|
- **Helper functions** (pre-built analysis workflows)
|
|
|
|
### Model Context Protocol (MCP) Server
|
|
|
|
Run EdgarTools as an MCP server for Claude Desktop and other MCP clients:
|
|
|
|
```bash
|
|
pip install edgartools[ai]
|
|
python -m edgar.ai
|
|
```
|
|
|
|
Configure in Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"edgartools": {
|
|
"command": "python",
|
|
"args": ["-m", "edgar.ai"],
|
|
"env": {
|
|
"EDGAR_IDENTITY": "Your Name your.email@example.com"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Then ask Claude:
|
|
- *"Research Apple Inc with financials"*
|
|
- *"Analyze Tesla's revenue trends over the last 4 quarters"*
|
|
- *"Compare Microsoft and Google's cash positions"*
|
|
|
|
### Why AI-Native Matters
|
|
|
|
- **Zero Friction**: `.docs` property provides instant learning without leaving your REPL
|
|
- **Token Efficient**: `.text()` methods use research-backed markdown-kv format
|
|
- **Progressive Disclosure**: Three detail levels (minimal/standard/detailed) for different contexts
|
|
- **Searchable**: BM25 semantic search finds relevant information instantly
|
|
- **Extensible**: BaseSkill class enables third-party skill packages
|
|
|
|
See [AI Integration Guide](docs/ai-integration.md) for complete documentation *(coming soon)*.
|
|
|
|
---
|
|
|
|
EdgarTools is distributed under the [MIT License](LICENSE).
|
|
|
|
## 📊 Star History
|
|
|
|
[](https://star-history.com/#dgunning/edgartools&Timeline) |