<p align="center">
<a href="https://github.com/lucasastorian/edgartools">
<img src="docs/images/edgartools-logo.png" alt="EdgarTools Python SEC EDGAR library logo" height="80">
</a>
</p>
<h3 align="center">Async-Enabled Python Library for SEC EDGAR Data Extraction</h3>
<p align="center">
<a href="https://pypi.org/project/edgartools-async"><img src="https://img.shields.io/pypi/v/edgartools-async.svg" alt="PyPI - Version"></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/lucasastorian/edgartools/blob/main/LICENSE"><img src="https://img.shields.io/github/license/lucasastorian/edgartools" alt="GitHub"></a>
</p>
<p align="center">
<b>Async fork of edgartools with enhanced XBRL support for non-US GAAP statements (IFRS, etc.). Extract financial data without blocking your event loop - perfect for high-throughput financial data pipelines.</b>
</p>
> **⭐ ALL CREDIT GOES TO [EDGARTOOLS](https://github.com/dgunning/edgartools) ⭐**
> This is a temporary fork created solely to add async support for immediate production needs. **ALL** the heavy lifting, design, and core functionality is from the brilliant work of [Dwight Gunning](https://github.com/dgunning) and the edgartools community.
>
> **Use the original [edgartools](https://github.com/dgunning/edgartools) for production** - it's actively maintained, has extensive documentation, and a strong community. This fork exists only to add async APIs until they're merged upstream.
>
> If you find this useful, please ⭐ star and support the original project: https://github.com/dgunning/edgartools</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()
```
## ⚡ Async API (New in edgartools-async)
Perfect for high-throughput pipelines and concurrent processing:
```python
import asyncio
from edgar import get_company_async, set_identity
async def main():
# Set identity BEFORE async operations
set_identity("your.name@example.com")
# Load company data without blocking event loop
company = await get_company_async("AAPL", user_agent="your.name@example.com")
# Load SGML data asynchronously
filings = company.get_filings(form="10-K")
sgml = await filings[0].sgml_async()
# Batch load multiple filings concurrently
from edgar._filings import load_sgmls_concurrently
filings_list = list(company.get_filings(form="10-Q"))[:10]
sgmls = await load_sgmls_concurrently(filings_list, max_in_flight=32)
print(f"Loaded {len(sgmls)} filings concurrently!")
asyncio.run(main())
```
### Key Async Features:
- **`get_company_async()`**: Non-blocking company instantiation
- **`filing.sgml_async()`**: Async SGML file loading
- **`load_sgmls_concurrently()`**: Batch concurrent loading with rate limiting
- **Thread-safe identity management**: No stdin blocking in async contexts
## 🌍 Enhanced Non-US GAAP Support (New in edgartools-async)
Improved handling of international financial statements (IFRS, etc.):
### Key Enhancements:
- **IFRS taxonomy support**: Better detection and parsing of IFRS statements
- **Quarterly vs YTD fallback**: Intelligently selects best available periods (prefers 3-month, falls back to YTD for cash flow)
- **Sparse period filtering**: Removes comparison periods with incomplete data
- **Improved concept matching**: Better revenue/income detection across taxonomies
- **Abstract element inference**: Automatically identifies abstract/header rows
- **Revenue deduplication**: Smarter handling of dimensional breakdowns vs parent totals
### Example: Foreign Filer with IFRS
```python
from edgar import Company
# Works seamlessly with non-US GAAP filers
company = Company("SAP") # German company using IFRS
financials = company.income_statement(periods=4, annual=True)
# Automatically detects and parses IFRS taxonomy
```
## 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.
EdgarTools is distributed under the [MIT License](LICENSE).
## 📊 Star History
[](https://star-history.com/#dgunning/edgartools&Timeline)
Raw data
{
"_id": null,
"home_page": null,
"name": "edgartools-async",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Lucas Astorian <lucas@intellifin.ai>",
"keywords": "async, asyncio, company, edgar, filings, finance, financial, ifrs, non-us-gaap, python, reports, sec, xbrl",
"author": null,
"author_email": "Dwight Gunning <dgunning@gmail.com>, Lucas Astorian <lucas@intellifin.ai>",
"download_url": "https://files.pythonhosted.org/packages/8f/14/9dee65ecb3c3f8ea1b6fde7a3070e9eca812ecbb5569bf9d554eb4c546f3/edgartools_async-1.0.7.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n<a href=\"https://github.com/lucasastorian/edgartools\">\n <img src=\"docs/images/edgartools-logo.png\" alt=\"EdgarTools Python SEC EDGAR library logo\" height=\"80\">\n</a>\n</p>\n\n<h3 align=\"center\">Async-Enabled Python Library for SEC EDGAR Data Extraction</h3>\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/edgartools-async\"><img src=\"https://img.shields.io/pypi/v/edgartools-async.svg\" alt=\"PyPI - Version\"></a>\n <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>\n <a href=\"https://github.com/lucasastorian/edgartools/blob/main/LICENSE\"><img src=\"https://img.shields.io/github/license/lucasastorian/edgartools\" alt=\"GitHub\"></a>\n</p>\n\n<p align=\"center\">\n <b>Async fork of edgartools with enhanced XBRL support for non-US GAAP statements (IFRS, etc.). Extract financial data without blocking your event loop - perfect for high-throughput financial data pipelines.</b>\n</p>\n\n> **\u2b50 ALL CREDIT GOES TO [EDGARTOOLS](https://github.com/dgunning/edgartools) \u2b50**\n> This is a temporary fork created solely to add async support for immediate production needs. **ALL** the heavy lifting, design, and core functionality is from the brilliant work of [Dwight Gunning](https://github.com/dgunning) and the edgartools community.\n>\n> **Use the original [edgartools](https://github.com/dgunning/edgartools) for production** - it's actively maintained, has extensive documentation, and a strong community. This fork exists only to add async APIs until they're merged upstream.\n>\n> If you find this useful, please \u2b50 star and support the original project: https://github.com/dgunning/edgartools</p>\n\n\n\n## SEC Filing Data Extraction with Python\n\n| With EdgarTools | Without EdgarTools |\n|-----------------------------------------------|---------------------------------------------|\n| \u2705 Instant access to any filing since 1994 | \u274c Hours spent navigating SEC.gov |\n| \u2705 Clean Python API with intuitive methods | \u274c Complex web scraping code |\n| \u2705 Automatic parsing into pandas DataFrames | \u274c Manual extraction of financial data |\n| \u2705 Specialized data objects for each form type | \u274c Custom code for each filing type |\n| \u2705 One-line conversion to clean, readable text | \u274c Messy HTML parsing for text extraction |\n| \u2705 LLM-ready text extraction for AI pipelines | \u274c Extra processing for AI/LLM compatibility |\n| \u2705 Automatic throttling to avoid blocks | \u274c Rate limiting headaches |\n\n## Apple's income statement in 1 line of code\n\n```python\nbalance_sheet = Company(\"AAPL\").get_financials().balance_sheet() \n```\n\n## \ud83d\ude80 Quick Start (2-minute tutorial)\n\n```python\n# 1. Import the library\nfrom edgar import *\n\n# 2. Tell the SEC who you are (required by SEC regulations)\nset_identity(\"your.name@example.com\") # Replace with your email\n\n# 3. Find a company\ncompany = Company(\"MSFT\") # Microsoft\n\n# 4. Get company filings\nfilings = company.get_filings() \n\n# 5. Filter by form \ninsider_filings = filings.filter(form=\"4\") # Insider transactions\n\n# 6. Get the latest filing\ninsider_filing = insider_filings[0]\n\n# 7. Convert to a data object\nownership = insider_filing.obj()\n```\n\n\n\n## \u26a1 Async API (New in edgartools-async)\n\nPerfect for high-throughput pipelines and concurrent processing:\n\n```python\nimport asyncio\nfrom edgar import get_company_async, set_identity\n\nasync def main():\n # Set identity BEFORE async operations\n set_identity(\"your.name@example.com\")\n\n # Load company data without blocking event loop\n company = await get_company_async(\"AAPL\", user_agent=\"your.name@example.com\")\n\n # Load SGML data asynchronously\n filings = company.get_filings(form=\"10-K\")\n sgml = await filings[0].sgml_async()\n\n # Batch load multiple filings concurrently\n from edgar._filings import load_sgmls_concurrently\n filings_list = list(company.get_filings(form=\"10-Q\"))[:10]\n sgmls = await load_sgmls_concurrently(filings_list, max_in_flight=32)\n print(f\"Loaded {len(sgmls)} filings concurrently!\")\n\nasyncio.run(main())\n```\n\n### Key Async Features:\n- **`get_company_async()`**: Non-blocking company instantiation\n- **`filing.sgml_async()`**: Async SGML file loading\n- **`load_sgmls_concurrently()`**: Batch concurrent loading with rate limiting\n- **Thread-safe identity management**: No stdin blocking in async contexts\n\n## \ud83c\udf0d Enhanced Non-US GAAP Support (New in edgartools-async)\n\nImproved handling of international financial statements (IFRS, etc.):\n\n### Key Enhancements:\n- **IFRS taxonomy support**: Better detection and parsing of IFRS statements\n- **Quarterly vs YTD fallback**: Intelligently selects best available periods (prefers 3-month, falls back to YTD for cash flow)\n- **Sparse period filtering**: Removes comparison periods with incomplete data\n- **Improved concept matching**: Better revenue/income detection across taxonomies\n- **Abstract element inference**: Automatically identifies abstract/header rows\n- **Revenue deduplication**: Smarter handling of dimensional breakdowns vs parent totals\n\n### Example: Foreign Filer with IFRS\n```python\nfrom edgar import Company\n\n# Works seamlessly with non-US GAAP filers\ncompany = Company(\"SAP\") # German company using IFRS\nfinancials = company.income_statement(periods=4, annual=True)\n# Automatically detects and parses IFRS taxonomy\n```\n\n## SEC Filing Analysis: Real-World Solutions\n\n### Company Financial Analysis\n\n**Problem:** Need to analyze a company's financial health across multiple periods.\n\n\n\n[See full code](docs/examples.md#company_financial_analysis)\n\n\n\n## \ud83d\udcda Documentation\n\n\n- [User Journeys / Examples](https://edgartools.readthedocs.io/en/latest/examples/)\n- [Quick Guide](https://edgartools.readthedocs.io/en/latest/quick-guide/)\n- [Full API Documentation](https://edgartools.readthedocs.io/)\n- [EdgarTools Blog](https://www.edgartools.io)\n\n## \ud83d\udc65 Community & Support\n\n- [GitHub Issues](https://github.com/dgunning/edgartools/issues) - Bug reports and feature requests\n- [Discussions](https://github.com/dgunning/edgartools/discussions) - Questions and community discussions\n\n## \ud83d\udd2e Roadmap\n\n- **Coming Soon**: Enhanced visualization tools for financial data\n- **In Development**: Machine learning integrations for financial sentiment analysis\n- **Planned**: Interactive dashboard for filing exploration\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions from the community! Here's how you can help:\n\n- **Code**: Fix bugs, add features, improve documentation\n- **Examples**: Share interesting use cases and examples\n- **Feedback**: Report issues or suggest improvements\n- **Spread the Word**: Star the repo, share with colleagues\n\nSee our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## \u2764\ufe0f Sponsors & Support\n\nIf you find EdgarTools valuable, please consider supporting its development:\n\n<a href=\"https://www.buymeacoffee.com/edgartools\" target=\"_blank\">\n <img src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 40px !important;width: 144px !important;\" >\n</a>\n\nYour support helps maintain and improve EdgarTools for the entire community!\n\n## Key Features for SEC Data Extraction and Analysis\n\n- **Comprehensive Filing Access**: Retrieve **any** SEC filing (10-K, 10-Q, 8-K, 13F, S-1, Form 4, etc.) since 1994.\n- **Financial Statement Extraction**: Easily access **Balance Sheets, Income Statements, Cash Flows**, and individual line items using XBRL tags or common names.\n- **SEC EDGAR API**: Programmatic access to the complete SEC database.\n- **Smart Data Objects**: Automatic parsing of filings into structured Python objects.\n- **Fund Holdings Analysis**: Extract and analyze **13F holdings** data for investment managers.\n- **Insider Transaction Monitoring**: Get structured data from **Form 3, 4, 5** filings.\n- **Clean Text Extraction**: One-line conversion from filing HTML to clean, readable text suitable for NLP.\n- **Targeted Section Extraction**: Pull specific sections like **Risk Factors (Item 1A)** or **MD&A (Item 7)**.\n- **AI/LLM Ready**: Text formatting and chunking optimized for AI pipelines.\n- **Performance Optimized**: Leverages libraries like `lxml` and potentially `PyArrow` for efficient data handling.\n- **XBRL Support**: Extract and analyze XBRL-tagged data.\n- **Intuitive API**: Simple, consistent interface for all data types.\n\nEdgarTools is distributed under the [MIT License](LICENSE).\n\n## \ud83d\udcca Star History\n\n[](https://star-history.com/#dgunning/edgartools&Timeline)",
"bugtrack_url": null,
"license": null,
"summary": "Async-enabled fork of edgartools with enhanced XBRL support for non-US GAAP financial statements",
"version": "1.0.7",
"project_urls": {
"Documentation": "https://dgunning.github.io/edgartools/",
"Issues": "https://github.com/lucasastorian/edgartools/issues",
"Original Source": "https://github.com/dgunning/edgartools",
"Source": "https://github.com/lucasastorian/edgartools"
},
"split_keywords": [
"async",
" asyncio",
" company",
" edgar",
" filings",
" finance",
" financial",
" ifrs",
" non-us-gaap",
" python",
" reports",
" sec",
" xbrl"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a0a843d543344a58942f0823284278170b4d6b46ae907190aba1f13a9f42e4ee",
"md5": "cf3754ed14d8a590916d0846157921b1",
"sha256": "fa7a582ddf867012489f790988bddf644633b564e967030fee27ba97f7153107"
},
"downloads": -1,
"filename": "edgartools_async-1.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cf3754ed14d8a590916d0846157921b1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 1667864,
"upload_time": "2025-10-30T21:24:19",
"upload_time_iso_8601": "2025-10-30T21:24:19.611512Z",
"url": "https://files.pythonhosted.org/packages/a0/a8/43d543344a58942f0823284278170b4d6b46ae907190aba1f13a9f42e4ee/edgartools_async-1.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8f149dee65ecb3c3f8ea1b6fde7a3070e9eca812ecbb5569bf9d554eb4c546f3",
"md5": "dc365bc3eb4f8851eaa00088238e2d52",
"sha256": "aa67e67d0e807e38d7d636a3b163e59ea13ac67dac425e2345f51bbe5755e11c"
},
"downloads": -1,
"filename": "edgartools_async-1.0.7.tar.gz",
"has_sig": false,
"md5_digest": "dc365bc3eb4f8851eaa00088238e2d52",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 1565833,
"upload_time": "2025-10-30T21:24:22",
"upload_time_iso_8601": "2025-10-30T21:24:22.576098Z",
"url": "https://files.pythonhosted.org/packages/8f/14/9dee65ecb3c3f8ea1b6fde7a3070e9eca812ecbb5569bf9d554eb4c546f3/edgartools_async-1.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-30 21:24:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lucasastorian",
"github_project": "edgartools",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "edgartools-async"
}
JSON
