Initial commit
This commit is contained in:
kdusek
@@ -0,0 +1,278 @@
|
||||
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)
|
||||
Reference in New Issue
Block a user