NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #4613 most downloaded on PyPI
Python library to access and analyze SEC Edgar filings, XBRL financial statements, 10-K, 10-Q, and 8-K reports
Last release 5 days ago
26 Sep 2026
Ships on a steady schedule
a new release about every 1 weeks
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
4 years old
446 releases · first in 2022
One column per quarter.
This also eliminates dependency on the deprecated SEC ticker.txt endpoint which now returns 503 errors.
Company("AAPL") from ~30s to ~28ms (1000x faster). This also eliminates dependency on the deprecated SEC ticker.txt endpoint which now returns 503 errors.reportQuarterYear instead of reportCalendarYear. The parser now checks both fields, falling back appropriately.Full Changelog: https://github.com/dgunning/edgartools/compare/v5.0.1...v5.0.2
Minor feature and bugfix release.
Minor feature and bugfix release.
N-PX Filing Support (#526) - Complete support for Form N-PX (proxy voting records)
edgar.npx module with NPX and ProxyVotes classes13F Other Managers Property (#523) - Added other_managers property to ThirteenF class
summaryPage instead of coverPage)pip install edgartools==5.0.1
Full changelog: https://github.com/dgunning/edgartools/blob/main/CHANGELOG.md
Legacy parser available as fallback (deprecated, removal planned for v6.0)
This major release completes the migration to the new HTMLParser for 10-K and 10-Q document processing, delivering improved accuracy, consistency, and maintainability.
edgar.documents.HTMLParser by defaultparent_concept column to statement DataFrames for hierarchical analysisChunkedDocument to HTMLParser for 10-K and 10-Qparent_concept column to XBRL statement DataFrameslog import in company_reports modulesis_section_header method to HeaderDetectionStrategyHTMLParser by defaultChunkedDocument available as fallback but deprecatedpart_i_item_1 instead of Item 1)Most users won't need to change anything. If you relied on specific section key formats:
# Old format (still works via fallback)
ten_k['Item 1']
# New preferred format
ten_k['Part I, Item 1']
# or
ten_k.sections['part_i_item_1'].text()
pip install --upgrade edgartools
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.35.1...v5.0.0
…documented entry point works as expected ✅ No breaking changes: All existing functionality preserved
This is an emergency point release fixing a critical bug that broke the primary API entry point.
Priority: P0 (Emergency)
Beads Issue: edgartools-4e1
GitHub Issue: #519
Company("MSFT") and all ticker-based company lookups were failing with the error:
Both data sources are unavailable
This occurred when the SEC returned HTTP 304 "Not Modified" responses (standard caching behavior).
The inspect_response() function in edgar/httprequests.py only accepted HTTP 200 status codes, treating HTTP 304 "Not Modified" responses as errors. HTTP 304 is a valid success response indicating that cached content is still valid.
inspect_response() to accept both 200 and 304 status codes✅ Fixes core functionality: Company(ticker) now works correctly with cached responses
✅ Restores beginner-friendly API: Primary documented entry point works as expected
✅ No breaking changes: All existing functionality preserved
edgar/__about__.py - Version bumped to 4.35.1edgar/httprequests.py - Updated inspect_response() to accept 304tests/issues/regression/test_issue_519_http_304.py - New regression testsNow available on PyPI! 🚀
pip install --upgrade edgartools
Verify the version:
import edgar
print(edgar.__version__) # Should show 4.35.1
All tests pass:
Total time from triage to PyPI: ~2 hours ⚡
Special thanks to @happydebugcow for the detailed bug report with reproduction steps!
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.35.0...v4.35.1
XBRL Statement Hierarchy - parent_concept Column
XBRL Statement Hierarchy - parent_concept Column (#514)
13F Manager Assignment Enhancements (#512)
OtherManager column to holdings DataFrame13F Holdings Aggregation (#207)
holdings property for user-friendly aggregated viewConfigurable EDGAR Data Paths (#516)
edgar.configure_paths() functionEDGAR_LOCAL_DATA_DIR environment variableProgress Bar Suppression (#507)
disable_progress parameter for all download functionsEDGAR_VERIFY_SSL referenceSee CHANGELOG.md for complete details.
Install: pip install --upgrade edgartools
Test Isolation for SSL Verification Settings
tests/conftest.py, scripts/test_ssl_verify_fix.pyNothing published for this version
New edgar.diagnose_ssl module for comprehensive SSL/VPN troubleshooting
edgar.diagnose_ssl module for comprehensive SSL/VPN troubleshootingexamples/notebooks/beginner/Diagnosing-SSL-Issues.ipynbXBRL Revenue Deduplication Refinement (Issues #438 and #513)
XBRL Display Period Filtering (Issue #edgartools-d4w)
@pytest.mark.regression for selective executionCLAUDE.md Simplification
SSL Diagnostics Guide
Nothing published for this version
Income Statement Selection Bug (#506) - Fixed statement resolver selecting ComprehensiveIncomeLoss instead of IncomeStatement for some filings (e.g.,
Income Statement Selection Bug (#506) - Fixed statement resolver selecting ComprehensiveIncomeLoss instead of IncomeStatement for some filings (e.g., EFX 10-K 2015-2018)
HTTP Cache Directory Configuration (#508) - Fixed get_cache_directory() to respect EDGAR_LOCAL_DATA_DIR environment variable. Thanks @kevinchiu!
StatementType Quick Reference (#509) - Clarified correct APIs for accessing financial statements. Company.get_statement() does not exist; use Company.income_statement(), Company.balance_sheet(), Company.cash_flow() or XBRL.get_statement(StatementType.XXX)
Investment Fund Research Example (#510) - Fixed incorrect example in user_journeys.md. find("VFIAX") returns a FundClass, not a Fund with get_portfolio(). Corrected to show proper workflow: FundClass → series → get_filings(form='NPORT-P')
pip install edgartools==4.33.1
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.33.0...v4.33.1
Nothing published for this version
This release adds comprehensive support for parsing Schedule 13D (active ownership) and Schedule 13G (passive institutional ownership) filings.
This release adds comprehensive support for parsing Schedule 13D (active ownership) and Schedule 13G (passive institutional ownership) filings.
edgar.beneficial_ownership with models, parsers, amendments, and renderingfiling.obj() dispatcher for automatic form type handlingfrom edgar import Filing
# Access via filing.obj() dispatcher
filing = Filing(form='SCHEDULE 13D', cik='1373604', accession_no='...')
schedule = filing.obj() # Returns Schedule13D instance
# Access filing details
print(schedule.issuer_info.name)
print(schedule.reporting_persons)
print(schedule.items.item4_purpose_of_transaction)
Enables tracking of activist campaigns, institutional ownership, and beneficial ownership changes.
See CHANGELOG.md for full details.
Nothing published for this version
This release delivers a comprehensive overhaul of 8-K section detection with new HTML parser integration, complete item coverage, and multiple bug fix
This release delivers a comprehensive overhaul of 8-K section detection with new HTML parser integration, complete item coverage, and multiple bug fixes.
Complete 8-K Section Detection Overhaul
8-K Section Extraction Improvements
Current Filings Form Filtering (Issue #501)
Table Display Fix (PR #500)
Company Reports Package Structure
```bash pip install --upgrade edgartools ```
🤖 Generated with Claude Code
Release Date: 2025-11-20 Theme: Comprehensive documentation improvements for enterprise users and advanced use cases
Release Date: 2025-11-20
Theme: Comprehensive documentation improvements for enterprise users and advanced use cases
docs/advanced/customizing-standardization.mddocs/configuration.md and enhanced docs/advanced-guide.mdget_filings() and get_current_filings()page_size=None parameter for fetching all current filingspip install --upgrade edgartools
Special thanks to @mpreiss9 for sharing detailed methodology on handling 200+ companies with XBRL standardization, which inspired our comprehensive documentation and future enhancement roadmap.
Test Coverage: 2,228 tests passing
Python Support: 3.8, 3.9, 3.10, 3.11, 3.12
This release brings enterprise-grade configuration and fixes a major storage configuration issue.
This release brings enterprise-grade configuration and fixes a major storage configuration issue.
Configurable SEC Domains (PR #490 by @yodaiken)
EDGAR_BASE_URL, EDGAR_DATA_URL, EDGAR_XBRL_URLConfigurable Rate Limiting (PR #491 by @yodaiken)
EDGAR_RATE_LIMIT_PER_SECBulk Downloads Respect Storage Config (PR #493 by @OvO-vel)
download_bulk_data() now properly respects use_local_storage() configurationSee CHANGELOG.md for complete technical details.
Special thanks to @yodaiken and @OvO-vel for these excellent contributions!
pip install --upgrade edgartools
Fix gzip decompression errors (#487): Added retry logic for corrupted gzip index downloads from SEC
pip install --upgrade edgartools
Full changelog: https://github.com/dgunning/edgartools/blob/main/CHANGELOG.md#4271---2025-11-10
Added integrated test harness for live filing validation and quality monitoring:
Added integrated test harness for live filing validation and quality monitoring:
Integrated lightweight, git-free issue tracking workflow:
current_page property in CurrentFilings class - documentation examples now work correctlyxlink:label over id for XBRL footnote identification - reduced warning spam in older filings (100+ warnings → deduplicated DEBUG messages)<ITEM> and <RULE> tags in SGML parserclick to optional test-harness dependency group: pip install edgartools[test-harness]All 2,184 tests passing successfully.
pip install edgartools==4.27.0
For test harness features:
pip install edgartools[test-harness]==4.27.0
See CHANGELOG.md for complete details.
Issue #480: Critical Documentation Gaps in Skills Package
Issue #480: Critical Documentation Gaps in Skills Package
set_identity() requirement to all documentation entry pointsto_context() method (5-10x token efficiency)Issue #481: Skills Documentation Restructuring for Token Efficiency
common-questions.md (366 lines)advanced-guide.md (256 lines)Documentation Token Optimization Across Skills Package
objects.md: 803 → 753 lines (~200-250 token reduction)
obj.text() to obj.to_context() in tablesdata-objects.md: 587 → 556 lines (~120-150 token reduction)
SKILL.md: 482 → 460 lines (~150 token reduction)
Enhanced Agent Documentation Navigation
skill.get_document_content() API for programmatic accessobj.text() → obj.to_context())pip install --upgrade edgartools
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.26.1...v4.26.2
Closes #480, #481
This is an emergency patch release to fix a critical packaging issue in v4.26.0.
This is an emergency patch release to fix a critical packaging issue in v4.26.0.
edgar/ai/skills/core/*.md files are now properly included in the distributed wheelpip install --upgrade edgartools
For AI features including MCP support:
pip install --upgrade edgartools[ai]
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.26.0...v4.26.1
Before (deprecated but still works): `python company.text() xbrl.text() `
This release brings major enhancements to crowdfunding filing analysis with AI-native workflows and comprehensive API standardization.
Track complete crowdfunding offering lifecycles from initial filing through termination with the new Campaign class.
from edgar import Company
company = Company("0001656159")
filing = company.get_filings(form="C").latest()
campaign = filing.get_campaign()
print(campaign.to_context()) # AI-optimized summary
print(campaign.status) # Active, Terminated, Completed
print(campaign.total_raised) # Total amount raised
print(campaign.timeline) # Chronological filing history
Features:
Consistent .to_context() method across all core classes for seamless AI agent interaction.
Before (deprecated but still works):
company.text()
xbrl.text()
After (recommended):
company.to_context()
xbrl.to_context()
filing.to_context()
filings.to_context()
Impact: 58% token reduction for AI workflows with better API discoverability.
969 lines of AI-native documentation for Form C crowdfunding filings with rich context generation at 3 detail levels.
Campaign Lifecycle Tracking (edgar/offerings/campaign.py - 694 lines)
AI-Native Form C Documentation (edgar/offerings/docs/FormC.md - 969 lines)
Workflow Documentation
API Standardization with .to_context()
Company.text() → Company.to_context()XBRL.text() → XBRL.to_context()Filing and Filings classes.text() methods deprecated with warningsREADME Modernization
Issue #475: Multi-Period Cash Flow Statements Missing Data
Invalid Escape Sequence Fix
pip install --upgrade edgartools
For AI features:
pip install edgartools[ai]
.to_context() APIThe .text() method is deprecated but still works with a warning:
# Update your code from:
context = company.text(detail='standard')
# To:
context = company.to_context(detail='standard')
This change applies to:
Company.text() → Company.to_context()XBRL.text() → XBRL.to_context()The old methods will be removed in version 5.0.
Thank you to everyone who reported issues, provided feedback, and contributed to making EdgarTools better!
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.25.0...v4.26.0
This release brings major improvements to Claude Skills integration with delightful convenience functions and beautiful ASCII art, making AI integrati
This release brings major improvements to Claude Skills integration with delightful convenience functions and beautiful ASCII art, making AI integration dramatically simpler and more joyful.
One-Line Installation
from edgar.ai import install_skill, package_skill
# Install to ~/.claude/skills/ with one function call
install_skill()
# Create ZIP for Claude Desktop upload
package_skill()
Features:
~/.claude/skills/edgartools/ for immediate usepip install --upgrade edgartools
Thank you to everyone who contributed to this release through issues, discussions, and feedback!
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
This release focuses on reliability improvements and AI agent documentation quality.
This release focuses on reliability improvements and AI agent documentation quality.
Form4 Wrong API Fix
.transactions attribute.common_stock_sales, .common_stock_purchasesSearch Method Confusion Fix
filing.search(query) - search filing text (BM25 content search)filing.docs.search(query) - search Filing API documentationOverall Impact: Average Skills API test score improved from 7.5 → 8.1 (+8%)
edgar/ai/skills/sec_analysis/data-objects.md - Comprehensive data objects documentationedgar/ai/skills/sec_analysis/form-types-reference.md - Form types referenceedgar/ai/skills/sec_analysis/quickstart-by-task.md - Task-oriented quickstart guideSkills API validation showed significant improvements:
See CHANGELOG.md for complete details.
pip install --upgrade edgartools
Thanks to all contributors who helped with this release!
This release focuses on improving access to fresh filings and expanding support for historical SEC data formats.
This release focuses on improving access to fresh filings and expanding support for historical SEC data formats.
edgar/httpclient.py - Cache optimizationedgar/entity/submissions.py - Removed session-level cachingedgar/thirteenf.py - TXT format parseredgar/sgml/sgml_parser.py - UNDERWRITER tag supportpip install edgartools==4.23.0
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.22.0...v4.23.0
Zero breaking changes - all existing APIs remain fully compatible. MCP imports maintain backward compatibility via deprecation warnings.
Major release introducing comprehensive AI-native capabilities to make EdgarTools the most learner-friendly and AI-agent-friendly SEC data library.
Every major EdgarTools object now includes rich, searchable documentation via the .docs property:
.text() methods for token-efficient AI agent contextfrom edgar import Company
company = Company("AAPL")
company.docs # Interactive rich documentation
company.docs.search("get financials") # Search documentation
context = company.text(detail='standard', max_tokens=500) # AI-optimized context
New extensible skill system for specialized SEC analysis:
from edgar.ai import list_skills, get_skill
skills = list_skills()
skill = get_skill("SEC Filing Analysis")
helpers = skill.get_helpers()
revenue_trend = helpers['get_revenue_trend']("AAPL", periods=3)
Streamlined Model Context Protocol implementation:
edgar/ai/mcp/ subpackagefilter_amendments parameter handling in XBRLS.from_filings()Zero breaking changes - all existing APIs remain fully compatible. MCP imports maintain backward compatibility via deprecation warnings.
pip install edgartools --upgrade
Special thanks to the community for feedback and feature requests that shaped this release!
See CHANGELOG.md for complete details.
This point release includes critical bug fixes and code quality improvements in the current_filings module.
This point release includes critical bug fixes and code quality improvements in the current_filings module.
Current Filings Module: Multiple bug fixes and improvements - Fixed critical bugs and improved error handling
(.*) matched to last dash instead of first(.*?) in edgar/current_filings.py:31next() and previous() methods lost the owner filter when paginatingowner=self.owner parameter in get_current_entries_on_page() callsowner=self.owner parameter in lines 154 and 166parse_title() used assert which can be disabled with -O flagraise ValueError() with descriptive message (line 68)_get_current_filing_by_accession_number() crashed when accession not foundmask.index(True) raises ValueError if True not in maskTests: Added comprehensive test suite with 10 tests covering all fixes in tests/test_current_filings_parsing.py
Impact: Current filings pagination now works correctly, better error messages, no production crashes
Current Filings Display: Eliminated pandas dependency - Refactored to use PyArrow direct access
self.data.to_pandas() created unnecessary pandas DataFrame conversiontests/manual/bench_current_filings_display.py for performance validationpip install edgartools==4.21.3
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.21.2...v4.21.3
Generated with Claude Code
Issue #466: Dimension column always False in XBRL statements (REGRESSION)
Issue #466: Dimension column always False in XBRL statements (REGRESSION)
Fixed critical regression where the dimension column in statement DataFrames incorrectly showed False for all line items, including dimensional data (Revenue by Product/Geography).
Root Cause: Key name mismatch introduced in Issue #463 DataFrame refactoring (v4.21.0). Code looked for 'dimension' key but XBRL parser uses 'is_dimension'.
Solution: Changed item.get('dimension', False) to item.get('is_dimension', False) in edgar/xbrl/statements.py:318
Impact:
dimension=TrueTests: 6 regression tests pass (Issue #416 tests un-skipped + 3 new Issue #466 tests)
Timeline: Fixed within 5 hours of classification
pip install --upgrade edgartools
Or install specific version:
pip install edgartools==4.21.2
Verify the fix works:
from edgar import Company
# Dimensional data should now show dimension=True
filing = Company("AAPL").get_filings(form="10-K", year=2024).latest()
df = filing.xbrl().statements.income_statement().to_dataframe()
# Check dimensional rows exist
dimensional_rows = df[df['dimension'] == True]
print(f"Found {len(dimensional_rows)} dimensional rows") # Should be > 0
Closes #466
User Impact: None - documentation improvements and internal cleanup only Breaking Changes: None Release Type: Point release (housekeeping)
This point release contains technical debt cleanup and documentation improvements with zero user impact.
items field data source
EntityFiling.items attribute explaining it sources from SEC metadataXBRL Parser Dead Code Cleanup - Removed ~1,988 lines of unreachable dead code from XBRL parsing subsystem
edgar/xbrl/parser.py, 1,903 lines) - completely replaced by modular parser architecture in edgar/xbrl/parsers/apply_calculation_weights() from edgar/xbrl/parsers/calculation.py (85 lines) - unused after Issue #463 removed weight application during parsingXBRL Package Code Quality Improvements - Fixed 38 linting issues in edgar/xbrl package
except: clause, removed unused variableInstallation:
pip install --upgrade edgartools
User Impact: None - documentation improvements and internal cleanup only
Breaking Changes: None
Release Type: Point release (housekeeping)
Issue #463: XBRL Value Transformations and Metadata Columns - Major enhancement to XBRL statement handling
Issue #463: XBRL Value Transformations and Metadata Columns - Major enhancement to XBRL statement handling
balance, weight, preferred_sign) to all statement DataFramespresentation=True parameter applies HTML-matching transformations# Get raw values with metadata
df = statement.to_dataframe()
# Columns: concept, label, periods..., balance, weight, preferred_sign
# Get presentation values (matches SEC HTML)
df_pres = statement.to_dataframe(presentation=True)
# Cash flow outflows shown as negative to match HTML display
Issue #464: Missing Comparative Periods in 10-Q Statements - Fixed incomplete period selection
Removed Normalization Mode - The normalize parameter has been removed from Statement.to_dataframe() and related APIs
normalize=True parameter usage. For display purposes, use presentation=True instead.XBRL API Documentation - Comprehensive updates to XBRL API documentation
balance, weight, and preferred_sign columnsUpdated 32 tests to handle metadata columns added in Issue #463
Install: pip install edgartools==4.21.0
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.20.1...v4.21.0
Zero breaking changes (all new columns are additive)
Released: 2025-10-17
This point release addresses two critical issues reported by @Velikolay and delivers major performance improvements.
Added comprehensive sign metadata to DataFrame exports:
balance column: Accounting classification (debit/credit)weight column: Calculation relationship weights (+1/-1)preferred_sign column: Expected sign conventionImpact: Users can now access XBRL semantic information without corrupting instance values. Critical for proper accounting classification and calculation verification.
Fixed Balance Sheets showing only current period instead of comparative periods:
Impact: Balance Sheets now consistently show 2 complete comparative periods (current + prior year).
Added period_key column for reliable time series analysis:
| Metric | Before | After | Improvement |
|---|---|---|---|
| Period Selection Time | 4+ seconds | < 500ms | 10-50x faster |
| DataFrame Conversions | 40+ per selection | 1 retrieval | 40x reduction |
| Period Coverage | Current only | Current + Prior | 2x periods |
Dynamic Thresholds:
Flexible Concept Matching:
Additional Fixes:
pip install --upgrade edgartools
Special thanks to @Velikolay for reporting both critical issues with excellent reproduction cases!
See CHANGELOG.md for complete details.
Previous Release: v4.20.0 (Oct 15, 2025) Next Release: v4.21.0 (planned for late October)
XBRL DataFrame Unit and Point-in-Time Support - Enhanced XBRL DataFrame exports with comprehensive unit and temporal information
unit column showing the measurement units for each fact (USD, shares, pure numbers, etc.)point_in_time boolean column to distinguish instant facts (point-in-time balances) from duration facts (period aggregates)to_dataframe() method on XBRL statements and factsMCP Server Token Efficiency - Optimized financial statement display for AI agents
to_llm_string() for plain text, borderless output optimized for LLM consumptionMCP Tool Clarity and Focus - Streamlined MCP server to 2 core workflow-oriented tools
ai_docs/ directory (1,469 lines) in favor of unified documentation approachSee CHANGELOG.md for complete release history.
Locale Cache Corruption (#457): Fixed critical issue where cached HTTP responses with locale-specific timestamps caused ValueError during deserializat
ValueError during deserialization. The library now automatically clears corrupted cache files on first use with a one-time operation, ensuring seamless functionality for international users..locale_fix_457_applied) to prevent repeated clearingMCP Workflow Tools - Comprehensive transformation of MCP server from basic tools to workflow-oriented tools
MCP Workflow Tools - Comprehensive transformation of MCP server from basic tools to workflow-oriented tools
edgar_company_research - Comprehensive company intelligence gatheringedgar_analyze_financials - Multi-period financial analysis with trend insightsedgar_filing_intelligence - Smart search and content extraction from filingsedgar_market_monitor - Real-time and historical market monitoringedgar_compare_companies - Cross-company screening and comparisonIssue #460: Quarterly Income Statement Fiscal Period Labels - Fixed quarterly period labels showing fiscal years 1 year ahead
enhanced_statement.py:
calculate_fiscal_year_for_label() to calculate fiscal year from period_end date based on company's fiscal year end monthdetect_fiscal_year_end() to automatically determine fiscal year end from FY factsIssue #457: Locale-Dependent Date Parsing - Fixed ValueError in non-English system locales
time.strptime() which respects LC_TIME locale. With Chinese locale, dates like "Fri, 10 Oct 2025" become "周五, 10 10月 2025", causing parsing failurepip install --upgrade edgartools==4.19.0
Sections Wrapper Class: New convenient interface for accessing filing sections
Sections class provides rich display of all available sections in a filingbusiness, risk_factors, mda, financialsfiling = Company("AAPL").get_filings(form="10-K").latest()
sections = filing.sections # Rich display shows all available sections
business = sections.business # Access by property
item1 = sections["Item 1"] # Access by item number
Issue #455: Per-Share Metric Scaling in XBRL Balance Sheets - Fixed incorrect scaling of per-share metrics
Issue #453: Missing Item 1C (Cybersecurity) in 10-K Structure - Added support for Cybersecurity disclosure section
Fixed regression where segment member concepts were incorrectly filtered from dimensional displays.
Fixed regression where segment member concepts were incorrectly filtered from dimensional displays.
Problem: After Issue #450 fix, dimensional member concepts (like us-gaap_ProductMember, us-gaap_ServiceOtherMember) were being filtered from Income Statements with dimensional breakdowns.
Root Cause: Member filtering logic was too aggressive, removing Members without values even in dimensional display contexts where they serve as category headers.
Solution: Enhanced filtering logic to detect dimensional display mode and keep Member concepts in dimensional displays while continuing to filter them from Statement of Equity.
Impact: Product and service segment values now correctly appear in dimensional income statements.
Fixed three critical rendering issues plus added clearer labeling:
📦 Installation: pip install edgartools==4.17.1
🔗 PyPI: https://pypi.org/project/edgartools/4.17.1/
Comprehensive tools for local storage visibility, analytics, and optimization:
Comprehensive tools for local storage visibility, analytics, and optimization:
storage_info() function with Rich Panel displaycheck_filing() and check_filings_batch() for offline detectionanalyze_storage() provides optimization recommendationsoptimize_storage(), cleanup_storage(), clear_cache()from edgar import storage_info, analyze_storage, optimize_storage
# View storage statistics
info = storage_info() # Beautiful Rich panel display
# Get optimization recommendations
analysis = analyze_storage()
# Compress files to save space (dry-run first)
result = optimize_storage(dry_run=True)
result = optimize_storage(dry_run=False)
Eliminated duplicate fiscal periods in quarterly balance sheets:
validate_quarterly_period_end() to verify period_end matches expected monthdetect_fiscal_year_end() to automatically detect company's fiscal year end# Before: ['Q3 2025', 'Q2 2025', 'Q3 2025', 'Q1 2025'] ❌ Duplicate!
# After: ['Q3 2025', 'Q2 2025', 'Q1 2025', 'Q3 2024'] ✅ Unique!
Company("AAPL").balance_sheet(annual=False)
Fixed incorrect revenue for companies with fiscal year-end changes:
pip install --upgrade edgartools
See CHANGELOG.md for complete details.
XBRL Code Refactoring - Eliminated duplication and improved maintainability
edgar/xbrl/parsers/concepts.py centralizes positive value concepts and legitimate negative conceptsInstallation
pip install edgartools==4.16.1
Full Changelog: https://github.com/dgunning/edgartools/blob/main/CHANGELOG.md
Breaking Changes: None - all changes are backward compatible
Direct DataFrame export capability for custom financial analysis and ML workflows.
New Method: EntityFacts.to_dataframe()
include_metadata=Truecolumns parameterExample:
from edgar import Company
from edgar.enums import PeriodType
company = Company("AAPL")
facts = company.get_facts(period_type=PeriodType.ANNUAL)
# Basic export
df = facts.to_dataframe()
# With metadata
df_full = facts.to_dataframe(include_metadata=True)
# Custom columns
df_slim = facts.to_dataframe(columns=['concept', 'fiscal_year', 'numeric_value'])
# Filter and analyze
revenue = df[df['concept'].str.contains('Revenue')]
Comprehensive support for filings covering multiple entities (Issue #400).
New Properties:
filing.is_multi_entity - Detect multi-entity filingsfiling.all_ciks - Get all CIKs in filingfiling.all_entities - Get all entity detailsVisual Enhancements:
Example:
from edgar import find
filing = find("0001193125-24-000123")
if filing.is_multi_entity:
print(f"Filing covers {len(filing.all_ciks)} entities:")
for entity in filing.all_entities:
print(f" - {entity.company_name} (CIK: {entity.cik})")
Fixed confusing empty columns in older XBRL filings (2016-2018).
Problem: Older filings included periods with only empty strings, creating blank columns in financial statements.
Solution: Enhanced period filtering to detect and remove periods containing only empty string values.
Impact: Cleaner financial statement displays for historical filings.
pip install --upgrade edgartools
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.15.0...v4.16.0
🤖 Generated with Claude Code
Co-Authored-By: Claude noreply@anthropic.com
This release brings significant improvements to developer experience with intuitive period filtering APIs and comprehensive ETF support, plus importan
This release brings significant improvements to developer experience with intuitive period filtering APIs and comprehensive ETF support, plus important bug fixes for SGML parsing.
company.get_facts(period_type=PeriodType.ANNUAL)<TEXT> sections was incorrectly flagged as HTMLpip install edgartools==4.15.0
from edgar import Company
from edgar.entity import PeriodType
# Direct filtering (new intuitive API)
company = Company('AAPL')
annual_facts = company.get_facts(period_type=PeriodType.ANNUAL)
quarterly_facts = company.get_facts(period_type=PeriodType.QUARTERLY)
# Query interface (new)
quarterly_revenue = facts.query().by_period_type(PeriodType.QUARTERLY).by_concept("Revenue").execute()
# EntityFacts filtering (new)
annual_filtered = facts.filter_by_period_type(PeriodType.ANNUAL)
from edgar.funds import Fund
# ETF ticker resolution now works seamlessly
spy_fund = Fund("SPY") # Now works perfectly!
series = spy_fund.get_series() # Get ticker-specific series
# Holdings with automatic ticker resolution
holdings = spy_fund.latest_portfolio_holdings()
for holding in holdings:
print(f"{holding.ticker} - {holding.name}") # Automatic ticker resolution
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.14.2...v4.15.0
This release significantly improves the user experience when encountering SEC API errors by replacing generic error messages with specific, actionable
This release significantly improves the user experience when encountering SEC API errors by replacing generic error messages with specific, actionable guidance.
Problem Solved: Users previously received unhelpful "Unknown SGML format" errors when SEC returned error responses, making it difficult to diagnose and resolve issues.
Solution: Added intelligent error detection and custom exception classes that provide clear, actionable guidance for common SEC API issues.
Custom Exception Classes:
SECIdentityError: For invalid or missing EDGAR_IDENTITY issuesSECFilingNotFoundError: For missing filings and AWS S3 NoSuchKey errorsSECHTMLResponseError: For other unexpected HTML/XML responsesEnhanced Error Detection:
Actionable Error Messages:
Before:
ValueError: Unknown SGML format
After:
SECIdentityError: SEC rejected request due to invalid or missing EDGAR_IDENTITY.
Please set a valid identity using set_identity('Your Name your.email@domain.com').
See https://www.sec.gov/os/accessing-edgar-data
This enhancement makes EdgarTools more user-friendly and helps developers quickly resolve common SEC API issues.
Published to PyPI: https://pypi.org/project/edgartools/4.14.2/
Fix missing values in 20-F filings - Added IFRS taxonomy support to resolve empty financial statements for foreign companies filing 20-F forms. Compan
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.14.0...v4.14.1
Zero breaking changes - fully backward compatible
This release delivers significant architectural improvements with enhanced XBRL period selection reliability and major code organization enhancements.
🔧 Unified XBRL Period Selection System
🏗️ Large File Architecture Refactoring
🐛 Critical Bug Fixes
⚡ Infrastructure Improvements
pip install edgartools==4.14.0This release represents a significant step forward in EdgarTools reliability and architectural clarity while maintaining the simple, powerful API users expect.
Zero breaking changes - all existing functionality preserved and enhanced
FEAT-411: Standardized Financial Concepts API - Complete implementation of standardized financial concept access
get_revenue() - handles various revenue concept names across companiesget_net_income() - standardizes net income accessget_total_assets() - consistent asset reportingget_total_liabilities() - standardized liability accessget_shareholders_equity() - equity across entity typesget_operating_income() - operating income normalizationget_gross_profit() - gross profit with fallback calculation_parse_order_attribute() method with proper fallback handlingedgar/entity/entity_facts.py: Extended with standardized financial concept methods (327 lines)edgar/entity/unit_handling.py: Comprehensive unit handling system (419 lines)edgar/entity/tools.py: Enhanced entity analysis tools (16 lines)tests/test_standardized_concepts.py: Complete test suite for new API (354 lines)tests/test_unit_handling.py: Unit handling validation tests (538 lines)edgar/xbrl/parser.py with robust order attribute parsing (57 lines modified)Release Date: 2025-09-18
Impact: This release significantly improves the developer experience by providing standardized access to financial concepts across different companies, eliminating the need for XBRL expertise.
Issue #412: Resolved missing historical balance sheet data for companies like TSLA
Issue #412: Resolved missing historical balance sheet data for companies like TSLA
Issue #438: Resolved missing revenue facts and duplicate entries in NVDA income statements
enhanced_statement.pySee CHANGELOG.md for complete details.
Resolved "ValueError: too many values to unpack (expected 2)" when parsing XBRL inline content with multiple '>' characters
_is_valid_sgml_tag() method to prevent interference from HTML/XBRL tags during header parsingsgml_header.py to split only on first '>' character using split('>', 1)This release resolves critical parsing failures that were preventing access to financial data from major companies like Tesla (TSLA) and other filings with complex XBRL inline content. Users can now reliably access financial data that was previously blocked by parsing errors.
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.12.0...v4.12.1
Major Feature: Portfolio Manager Enhancement for 13F Filings
Major Feature: Portfolio Manager Enhancement for 13F Filings
Addresses community feedback from Reddit users about missing 13F filing manager identification:
management_company_name, filing_signer_name, filing_signer_titleget_portfolio_managers(), get_manager_info_summary()FormType, PeriodType, StatementType enumerationsImportError: MappingProxyType by renaming edgar/types.py to edgar/enums.pyimport edgar
# Get latest 13F filing for Berkshire Hathaway
company = edgar.Company("BRK-A")
filing = company.get_filings(form="13F-HR").head(1)[0]
thirteen_f = filing.obj()
# Get the actual portfolio managers
managers = thirteen_f.get_portfolio_managers()
print(f"Portfolio Managers: {[m['name'] for m in managers]}")
# Output: ['Warren Buffett', 'Charles Munger', 'Gregory Abel', 'Ajit Jain']
Full Changelog: See CHANGELOG.md
Issue #427: Fixed XBRLS DataFrame column ordering and amendment filtering to ensure consistent and predictable data presentation
This patch release addresses critical fixes identified after the 4.11.0 release, focusing on data consistency and API stability improvements.
Full Changelog: https://github.com/dgunning/edgartools/compare/v4.11.0...v4.11.1
No Breaking Changes: Full backwards compatibility maintained
This release introduces significant improvements to XBRL processing and adds a powerful new Current Period API for simplified data access.
Simplified single-period data access without the complexity of multi-period filtering
import edgar
# Get Apple's latest 10-K
aapl = edgar.Company("AAPL")
filing = aapl.get_filings(form="10-K").latest()
current = filing.xbrl().current_period
# Clean, simple API for current period data
balance_sheet = current.balance_sheet()
income_statement = current.income_statement()
cash_flow = current.cashflow_statement()
# Support for raw XBRL concepts
raw_data = current.income_statement(raw_concepts=True)
# Individual fact lookup
cash_balance = current.get_fact('CashAndCashEquivalentsAtCarryingValue')
# Export as dictionary
data_dict = current.to_dict()
Benefits:
Create Filing objects directly from complete SGML submission text
# Create filings from raw SGML text
filing = Filing.from_sgml_text(sgml_content)
Rich product and service segment breakdowns now visible by default
# Enhanced dimensional data (now default)
stmt = xbrl.statements.income_statement() # Shows segment breakdowns
# Control dimensional display
df = stmt.to_dataframe(include_dimensions=False) # Disable if needed
Resolved inconsistent parameter naming across stitched statement methods
Before (inconsistent):
# Documentation showed this:
statements.income_statement(standard=True) # ❌ TypeError
# But only this worked:
statements.income_statement(standardize=True) # Confusing!
After (consistent):
# All methods now consistently accept 'standard' parameter:
statements.income_statement(standard=True) ✅
statements.balance_sheet(standard=True) ✅
statements.cashflow_statement(standard=True) ✅
statements.statement_of_equity(standard=True) ✅
statements.comprehensive_income(standard=True) ✅
Fixed missing parent totals in dimensional breakdowns
Tesla income statement now properly shows:
Previously, enabling dimensional display hid the parent totals, making key figures invisible.
pip install edgartools==4.11.0
# or upgrade existing installation
pip install --upgrade edgartools
standardize=True, change to standard=True# Traditional multi-period workflow (unchanged)
xbrls = XBRLS.from_filings([filing1, filing2, filing3])
statements = xbrls.statements
income = statements.income_statement(standard=True) # Updated parameter name
# New single-period workflow
current = filing.xbrl().current_period
income = current.income_statement() # Simplified API
This release represents a significant step forward in making XBRL data more accessible while maintaining EdgarTools' core principles of simplicity, accuracy, and elegance.
The Current Period API makes financial data analysis accessible to beginners, while the enhanced dimensional display and API consistency improvements benefit power users performing complex multi-company analysis.
Try it out and let us know what you think!
Contributors: @dgunning with community feedback from @RanFeldesh and others
Happy analyzing! 📈
CurrentReport (6-K/8-K) missing financials attribute (#332): Fixed AttributeError when accessing financials on 6-K and 8-K filings. CurrentReport now
This patch release adds the issue #332 fix that was committed after 4.10.0 was already released to PyPI.
Nothing published for this version
Remove the dependency on the packaging library. This will ease installation issues caused through library conflicts
packaging library. This will ease installation issues caused through library conflictsAdd comprehensive_income() method to XBRL Statements class for consistent API access to comprehensive income statements
comprehensive_income() method to XBRL Statements class for consistent API access to comprehensive income statements (#396)Fix annual period selection showing quarterly values (#408) by improving the filtering of periods when selecting annual statements
Made the period detection selection logic more lenient to allow periods with limited data
Reduce logging level for the httpxthrottlecache library to avoid excessive debug logs
httpxthrottlecache library to avoid excessive debug logsAdd edgar.entity.company_subsets module to allow for easy access to company subsets like sp500, nasdaq100, etc.
edgar.entity.company_subsets module to allow for easy access to company subsets like sp500, nasdaq100, etc.fetch_daily_filing_index which used a different date format from the one used for quarterly indexeshttpxthrottlecacheEnsure only HTTP 200 responses are cached in the HTTP cache
http2, if installed_make_request_conditional to ensure proper revalidation of cached responsesmoneyfmt functionNothing published for this version
Fix bug where local storage downloads failed due to an error in the rate limiter handling of async http requests
Fix bug in period selection for quarterly statements from XBRL that caused some statements to not display data
Your coding agent can read these notes before it upgrades. Set up the MCP server →