NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #4016 most downloaded on PyPI
Python library to access and analyze SEC Edgar filings, XBRL financial statements, 10-K, 10-Q, and 8-K reports
Latest stable
6.2.0
Last release 4 days ago
15 Nov 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
455 releases · first in 2022
Drag across the ruler to compare, or tap a release to open it.
Homepage Fallback When SGML Unavailable — When the SEC returns empty content for a filing's full submission text (.txt), Filing.sgml() now falls back
Homepage Fallback When SGML Unavailable — When the SEC returns empty content for a filing's full submission text (.txt), Filing.sgml() now falls back to the filing's homepage index page instead of raising an exception. The fallback provides document attachments with valid URLs for html(), xml(), xbrl(), and text(). Network errors and permanent errors still propagate correctly (#674)
Cache Bypass Actually Works Now — The 5.20.1 retry-with-cache-bypass for empty SGML responses was silently ineffective because httpxthrottlecache reuses a single client instance, ignoring bypass_cache after initial creation. The retry now uses a direct httpx request that completely bypasses the cache layer (#672)
BDC Pipe-Separated Investment Identifiers — Recent BDC filings (e.g., Blue Owl) use pipe-separated format (Company | Type | Issuer Category) for investment identifiers instead of comma-separated. The parser now handles both formats
Empty SEC responses permanently cached — Empty or error responses from SEC SGML endpoints were stored in the local cache indefinitely, blocking filing
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Empty SEC responses permanently cached — Empty or error responses from SEC SGML endpoints were stored in the local cache indefinitely, blocking filing downloads on all subsequent requests. The fetcher now detects empty/error payloads and retries once with cache bypass (#672)
Automatic cache clear on upgrade — On first run after upgrading to 5.20.1, the local SGML cache is automatically cleared once to remove any stale empty responses cached under prior versions. No manual intervention required.
Graceful test skip on transient SEC responses — Network tests that exercise SGML downloads now skip with an informative message on transient empty SEC responses instead of failing CI.
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.20.0...v5.20.1
Empty SEC Responses Permanently Cached — Empty or error responses from SEC SGML endpoints were stored in the local cache indefinitely, meaning subsequent requests would silently return empty content rather than retrying against the network. The fetcher now detects empty/error payloads and retries once with cache bypass before giving up (#672) (45574373)
Automatic Cache Clear on Upgrade — On first run after upgrading to 5.20.1, the local SGML cache is automatically cleared once to remove any stale empty responses that were cached under prior versions. No manual intervention required (45574373)
Graceful Test Skip on Transient SEC Responses — Network tests that exercise SGML downloads now detect transient empty responses from SEC and skip with an informative message instead of failing the suite (4fc4a889)
Fund data objects improvements: Overhauled fund entity data objects for better performance, cohesion, and memory safety. Funds are now more efficient
fact_id field is now exposed in the XBRL facts DataFrame, making it easier to uniquely identify and cross-reference individual XBRL facts.Fund Data Object Improvements — Performance, cohesion, and memory safety improvements across fund data objects (0b020c3)
fact_id in XBRL Facts DataFrame — The unique fact identifier is now exposed in the XBRL facts DataFrame for traceability and cross-referencing (0785b87)
SGML Parser Diagnostic Errors — "Unknown SGML format" errors now include content previews, response length, and pattern-specific messages for rate limiting, empty responses, and SEC error pages (bf8a58a)
BDC Test Reliability — Switched BDC integration tests from ARCC to Blue Owl (CIK 1812554) due to ARCC's latest 10-K returning empty content from SEC (84c58ee)
Fix fund lookups broken by SEC endpoint removal: The SEC removed the cgi-bin/series endpoint (now returns 404 for all requests), breaking all fund tic
cgi-bin/series endpoint (now returns 404 for all requests), breaking all fund ticker, series, and class lookups. Rewrote get_fund_object() to use the still-working browse-edgar endpoint with a two-step resolve-then-fetch approach.FundShareholderReport data object for N-CSR/N-CSRS filings — parse fund shareholder reports into structured data
to_facts_dataframe() on EarningsRelease and FinancialTable — convert earnings data to structured DataFramesFortyF Data Object (40-F Canadian MJDS) — New data object for Form 40-F annual reports filed by ~200 Canadian cross-listed companies (Shopify, Royal B
FortyF Data Object (40-F Canadian MJDS) — New data object for Form 40-F annual reports filed by ~200 Canadian cross-listed companies (Shopify, Royal Bank, Barrick Gold, etc.). Unlike 10-K filings, the 40-F wrapper is an iXBRL shell — the actual business content lives in the Annual Information Form (AIF) exhibit. FortyF identifies the AIF via a 5-tier priority chain and extracts NI 51-102 sections with regex-based detection and three-layer disambiguation (TOC entries, cross-references, page footers). Validated across 24 Canadian filers with 92% business extraction and 100% items detection.
.business, .risk_factors, .corporate_structure, .dividends, .capital_structure, .directors_and_officers, .legal_proceedingsforty_f["business"] matches "Description Of The Business".aif_html, .aif_text for downstream rendering and LLM input.mda_attachment, .mda_html, .mda_text for filers that include a separate MD&A (e.g. Manulife)to_context() for LLM agentsedgar/company_reports/forty_f.pyEntityFacts Discovery Methods — New search_concepts() and available_periods() methods on EntityFacts let users explore what concepts and periods a company actually has before querying, instead of guessing names and getting silent None returns (20ba29d)
Helpful Warnings on Silent None Returns — get_fact(), get_annual_fact(), and get_concept() now emit UserWarning with fuzzy "did you mean?" suggestions via difflib and tips pointing to search_concepts() / available_periods() when they return None (2837d4e)
XBRL Notes/Disclosures Access — Five new convenience methods on the XBRL object (.notes, .disclosures, .list_tables(), .get_table(), .get_disclosure()) so users can discover and access all XBRL tables directly without navigating through Statements first (7006bc9)
Filing.obj_type Property — Preview what .obj() will return (e.g. 'TenK', 'Form4') without parsing the filing. Returns None for unsupported form types (618519b)
get_operating_income() on Financials — XBRL concept-first lookup with label fallback, matching the get_revenue() pattern (#663)
cash_flow_statement() Alias — Added cash_flow_statement() as an alias for cashflow_statement() on all surfaces (Company, Financials, XBRL) for discoverability (b8558eb)
Period Format Normalization — Either "2023-FY" or "FY 2023" now works everywhere. EntityFacts and MultiPeriodStatement used different formats, causing silent failures when passing periods between APIs. Both formats are now accepted transparently at API boundaries (f33d02a)
$(0.09) as separate <td> cells for $, (, 0.09, ). The parentheses are now reassembled correctly (26902468)MCP Server: all tool calls failing with outputSchema validation error — The @tool decorator was defaulting every tool to advertise outputSchema in its
@tool decorator was defaulting every tool to advertise outputSchema in its MCP definition, but the call handler returns text content. This caused all 9 MCP tools to fail with "outputSchema defined but no structured output returned". Fixed by only including outputSchema when explicitly provided. (GH #662)Full Changelog: https://github.com/dgunning/edgartools/compare/v5.17.0...v5.17.1
MCP filing support for Foreign Private Issuers (FPI) — The edgar_filing MCP tool now handles 20-F and 6-K filings with IFRS concept mappings, enabling
MCP filing support for Foreign Private Issuers (FPI) — The edgar_filing MCP tool now handles 20-F and 6-K filings with IFRS concept mappings, enabling financial analysis of international filers (#660)
New MCP tools — Major expansion of the MCP tool surface:
edgar_text_search — full-text search across SEC filingsedgar_screen — company screening with output schemas and promptsedgar_monitor — monitor filings activityedgar_trends — analyze filing trends over timeportfolio_diff — compare portfolio holdings across periodsview parameter for StitchedStatement and MultiFinancials — Dimensional filtering now available when working with stitched (multi-period) statements, matching the single-statement API
search_filings() library API — Extracted from MCP tool into a standalone library function for programmatic full-text filing search
DEF 14A documentation — New guide on accessing board and director data from proxy statements
MTD balance sheet resolution — Fixed validation of standard-name matches across all cascade steps so that essential concepts like Assets and Liabilities are correctly resolved for companies like MetLife (GH #659)
STZ income statement — Fixed resolution when ComprehensiveIncome fallback is filtered out during cascade
DIS cash flow stitching — Fixed stitching when companies switch between aggregate and continuing-operations concepts across periods (#646)
RenderedStatement serialization — Fixed pickle and JSON serialization bugs
MCP entry point — Fixed the edgartools-mcp entry point configuration
view parameter on stitched statementsFull Changelog: https://github.com/dgunning/edgartools/compare/v5.16.3...v5.17.0
RenderedStatement serialization — RenderedStatement now supports to_dict() / from_dict() for JSON-safe serialization of rendered financial statements.
RenderedStatement serialization — RenderedStatement now supports to_dict() / from_dict() for JSON-safe serialization of rendered financial statements. Cell formatters are pre-applied on serialize; passthrough lambdas are used on deserialize, enabling round-trip transport of rendered statements without requiring XBRL context.
TTM period control in MCP tool — The edgar_company MCP tool now accepts period='ttm' to request trailing-twelve-month income and cash flow statements directly from the tool interface.
max_periods threading — Company.income_statement() and Company.cashflow_statement() now correctly forward the periods parameter through to the TTM statement builder. Previously, max_periods was ignored when period='ttm', always returning the default number of periods (PR #650, contributor: @baqamisaif)xbrl.py reduces _find_facts_for_element() from O(nodes × contexts) to O(nodes)facts.py merged into one with early exitRenderedStatementFull Changelog: https://github.com/dgunning/edgartools/compare/v5.16.2...v5.16.3
This is a patch release containing three bug fixes and documentation improvements.
This is a patch release containing three bug fixes and documentation improvements.
XBRL stitching label collision (9554e999): Fixed a collision in XBRL stitching where labels were used as dictionary keys. The fix switches to using the concept identifier as the dict key, preventing data loss when multiple concepts share the same label.
MCP tool returning null for narrative sections (#654, 2b397e11): Fixed the edgar_filing MCP tool incorrectly returning null when fetching narrative content (Item 1, Item 7, MD&A, etc.) from 10-Q and 10-K filings. Narrative sections are now reliably returned.
Notebook runtime errors in XBRL2-FactQueries (76361d25): Cleared runtime errors in the XBRL2-FactQueries notebook so it runs cleanly from top to bottom without manual intervention.
pip install --upgrade edgartools
Stitching: standard_concept propagation — Stitched statements now correctly propagate standard_concept metadata through the pipeline, fixing missing c
Stitching: standard_concept propagation — Stitched statements now correctly propagate standard_concept metadata through the pipeline, fixing missing column in DataFrames (#649)
Stitching: duplicate row merging — When multiple filings map different tags to the same standard_concept, rows are now merged instead of duplicated (e.g., BRO equity showing two lines) (#643)
Stitching: current/noncurrent debt disambiguation — Added tag-name hints so long-term debt is no longer incorrectly reclassified as current debt during stitching (e.g., FOX) (#644)
DECK Income Before Tax mapping — Removed incorrect exclusion and added GAAP mapping for DECK's income-before-tax tag (#648)
EarningsRelease: split-cell negative signs — Fixed parenthesized negative notation not being detected when split across table cells (#633)
EarningsRelease: duplicate column names — Fixed crash in scaled_dataframe when earnings tables contain duplicate column headers
matches_form: double /A appending — Fixed matches_form() incorrectly appending /A twice for amendment matching
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.16.0...v5.16.1
CompanyNotFoundError - Company("INVALID") now raises CompanyNotFoundError with intelligent suggestions instead of silently returning a broken sentinel
CompanyNotFoundError - Company("INVALID") now raises CompanyNotFoundError with intelligent suggestions instead of silently returning a broken sentinel entity. This change makes the API more predictable and user-friendly. Import with from edgar import CompanyNotFoundError.
Truststore SSL Support - Added use_system_certs() function for OS-native certificate store integration via truststore. This dramatically improves SSL handling in corporate and VPN environments where custom certificate chains are common. Users no longer need to disable SSL verification.
Datamule Storage Integration - Added datamule as an alternative filing source, providing faster access to frequently-used filings (addresses #212). The system automatically falls back to SEC EDGAR when needed.
use_system_certs() for OS-native certificate store via truststore libraryEntity.latest() returning incomplete results for large n valuesDocumentation & Examples
use_system_certs() over verify_ssl=FalseTesting & Quality
Internal
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.15.3...v5.16.0
pyrate-limiter 4.0 Compatibility — Fixed import failure with pyrate-limiter 4.0+
max_delay, raise_when_fail, and retry_until_max_delay parameters from Limiter.__init__()pyrate-limiter==3.9.0 to pyrate-limiter>=3.0.0pip install --upgrade edgartools
Fix confusing NoneType error when company facts download fails
EarningsRelease Data Accuracy — Fixed critical bugs in earnings data processing
EarningsRelease Data Accuracy — Fixed critical bugs in earnings data processing (#633)
scaled_dataframe() never applying scaling due to object-dtype checkXBRL Notes Extraction — Fixed TextBlock concepts being misclassified as abstract, preventing proper notes extraction
Statement Type Compatibility — Fixed StatementType enum compatibility with get_statement() method
Test Suite Organization — Major restructuring for better maintainability and performance
Verification Framework — Added Verification Constitution and roadmap for test suite overhaul
…edgar_compare, edgar_ownership), removing deprecated legacy handlers.
to_context() on Statements — LLM-optimized text representation for passing XBRL statement data to language models.edgar_company, edgar_search, edgar_filing, edgar_compare, edgar_ownership), removing deprecated legacy handlers.install_skill() now uses symlinks so skills auto-sync with package updates.__str__ methods — Added __str__ and to_context() on Company, Filings, EntityFilings, and Financials for optimized LLM output.cashflow_statement() — Renamed cash_flow() to cashflow_statement() for consistency with income_statement() and balance_sheet().Filing serialization: Fixed Filing.save()/load() to properly serialize SGML content before pickling
Filing.save()/load() to properly serialize SGML content before pickling (#631)This patch release focuses on improving reliability of filing serialization and stock split detection accuracy.
SGML Parser 10x Faster — Rewrote SGML parser from line-by-line to offset scanning with lazy content references. Parse times drop from 52ms to 5.5ms fo
SGML Parser 10x Faster — Rewrote SGML parser from line-by-line to offset scanning with lazy content references. Parse times drop from 52ms to 5.5ms for large filings (Apple 10-K, 9.3MB). Peak memory reduced 275x (23.4MB to 0.1MB). Form 4 parsing is 71x faster (96ms to 1.3ms) by removing a network call from header parsing.
SGML Max File Size — Raised max content size from 200MB to 500MB to handle large filings with embedded images.
XBRL Fiscal Period Queries — get_facts_by_fiscal_period() and get_facts_by_fiscal_year() now return data instead of empty DataFrames. Reporting period
XBRL Fiscal Period Queries — get_facts_by_fiscal_period() and get_facts_by_fiscal_year() now return data instead of empty DataFrames. Reporting periods were missing the fiscal_year and fiscal_period fields needed for these queries. (#622)
13F Holdings Rendering — Fixed crashes when issuer or ticker values contain NaN in holdings comparison and holdings history views.
Entity Classification — SC 13D filings no longer incorrectly classify an entity as a company.
N-PORT Parsing 10x Faster — Rewrote N-PORT fund report XML parsing from BeautifulSoup to lxml. Parse times drop from 2.4s to 245ms for large funds (3,800+ holdings). Memory usage reduced by 6x.
CUSIP Ticker Resolution 10x Faster — Replaced DataFrame lookups with dict-based resolution for CUSIP-to-ticker mapping. Eliminates noisy log warnings for placeholder CUSIPs used by foreign-domiciled securities.
pip install edgartools==5.13.1
Major Performance Gains: Replaced BeautifulSoup with lxml's etree for parsing 13F information tables
holdings_view(): Improved default display with configurable limits to prevent terminal floodingcompare_holdings(): Compare current vs previous quarter holdings with:
holding_history(periods=4): Multi-quarter tracking with:
📦 Install: `pip install edgartools==5.13.0`
Nothing published for this version
Nothing published for this version
Added pandas 3.0 compatibility while maintaining Python 3.10 support
Pandas Compatibility
Date Handling
Table Parsing
<thead> elementsEarnings Detection
has_earnings property consistent with earnings property behavior📦 Install: pip install edgartools==5.12.1
New edgar/earnings.py module for extracting financial tables from 8-K earnings releases
edgar/earnings.py module for extracting financial tables from 8-K earnings releasesto_context(), to_html(), to_json(), to_markdown()has_earnings, earnings property, statement shortcutsget_income_statement(), get_balance_sheet(), get_cash_flow_statement()BDCEntity class for individual BDC analysis with filings and SOI accessBDCEntities collection with get_by_cik() and get_by_ticker() methodsPortfolioInvestment model for individual holdings with PIK rate supportis_active property and visual status indicatorsDataQuality metrics and data availability checksTooManyRequestsError with actionable guidance for usersRemoteProtocolError to retryable exceptions for bulk downloadshttpxthrottlecache from >=0.1.6 to >=0.3.0hishel dependency (no longer needed in httpxthrottlecache v0.3.0)Full Changelog: https://github.com/dgunning/edgartools/compare/v5.11.2...v5.12.0
Fixed get_revenue() and other financial methods returning None for companies like TSLA
get_revenue() and other financial methods returning None for companies like TSLAlatest_tenk and latest_tenq returning amended filings (10-K/A, 10-Q/A) which often lack complete XBRL dataamendments=False filter to exclude amended filingspyrate-limiter to version 3.9.0 to avoid API breakage in 4.0⚠️ EntityFacts financial methods now default to annual (FY) periods instead of most recent
get_revenue(), get_net_income(), get_total_assets(), get_total_liabilities(), get_shareholders_equity(), get_operating_income(), get_gross_profit(), and their _detailed() variantsfacts.get_revenue() returned most recent fact (could be quarterly Q3 data)facts.get_revenue() returns most recent annual FY data (falls back to most recent if no annual available)facts.get_revenue(annual=False)facts.get_revenue(period="2024-Q3")facts.get_revenue(period="2024-FY") or facts.get_revenue(annual=True) (default)get_financials() behaviorpip install --upgrade edgartools
Pinned pandas to <3.0 to avoid breaking changes
Timezone Handling
Pandas 3.0 Compatibility
Income Statement Selection (Issue #608)
Ttm split by @baqamisaif in https://github.com/dgunning/edgartools/pull/602
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.10.2...v5.11.0
Fix `dimension_member_label` in query API
Fix dimension_member_label in query API (#603)
xbrl.query().by_dimension() now shows correct labels (e.g., "YouTube ads" instead of "Google Services")Preserve parent items during revenue deduplication (#604)
pip install edgartools==5.10.2
Fixed non-deterministic results when loading Filing from pickle across Python processes
pip install edgartools==5.10.1
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.10.0...v5.10.1
Nothing published for this version
Statement View Control - Added view parameter to all Financials statement methods (income_statement, balance_sheet, cashflow_statement, etc.) with thr
view parameter to all Financials statement methods (income_statement, balance_sheet, cashflow_statement, etc.) with three modes: STANDARD, DETAILED, SUMMARYis_breakdown field to StatementRow to distinguish face dimensions from breakdown dimensionsFull Changelog: https://github.com/dgunning/edgartools/compare/v5.9.0...v5.9.1
Nothing published for this version
All three fixes improve data accuracy and reliability when parsing XBRL financial statements. No breaking changes or API modifications.
All three fixes improve data accuracy and reliability when parsing XBRL financial statements. No breaking changes or API modifications.
```bash pip install edgartools==5.8.3 ```
Compare changes: https://github.com/dgunning/edgartools/compare/v5.8.2...v5.8.3
TwentyF Convenience Properties - Added properties for common 20-F sections matching TenK API style:
TwentyF Convenience Properties - Added properties for common 20-F sections matching TenK API style:
business / company_information → Item 4risk_factors / key_information → Item 3management_discussion / operating_review → Item 5directors_and_employees, major_shareholders, financial_information, controls_and_proceduresIndustry Extensions
20-F Section Extraction - Fixed pattern extractor selecting cross-references instead of main section headers. 20-F sections now return full content instead of truncated snippets.
Section Boundary Artifacts - Removed trailing page numbers and next section headers from extracted text for cleaner output.
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.8.1...v5.8.2
Fixed resolver incorrectly selecting tax disclosure statements instead of main income statement
total_shares and total_percent for corporate control chain filingstotal_percent at 100% to handle rounding artifacts in source datapip install edgartools==5.8.1
Potential breaking changes to dimension column naming
Release Date: 2026-01-04
EdgarTools 5.8.0 is a feature release that introduces major improvements to XBRL statement handling, dimension filtering, and Statement of Equity rendering. This release replaces confusing boolean parameters with semantic enums, fixes critical balance sheet and equity statement bugs, and adds opt-in matrix rendering for equity statements.
Replace the confusing include_dimensions boolean with a clear, semantic StatementView enum that offers three distinct presentation modes:
from edgar import Filing
from edgar.xbrl import StatementView
filing = Filing(company='Apple Inc', cik='320193', form='10-K',
filing_date='2024-09-28', accession_no='0000320193-24-000123')
financials = filing.xbrl()
# STANDARD view: Face presentation matching SEC Viewer (default for rendering)
income = financials.income_statement(view=StatementView.STANDARD)
print(income) # Clean, dimensional breakouts hidden
# DETAILED view: All dimensional data included (default for to_dataframe)
income_df = income.to_dataframe(view=StatementView.DETAILED)
# Returns DataFrame with dimension columns for analysis
# SUMMARY view: Non-dimensional totals only
income_summary = financials.income_statement(view=StatementView.SUMMARY)
# Returns only top-level aggregates without segment breakouts
Key Benefits:
include_dimensions still works with deprecation warning (removed in v6.0)Related Issue: edgartools-dvel (GH-574)
Structured dimension fields now available in both statement DataFrames and XBRL facts queries:
# Statement DataFrames now include:
# - dimension: Axis name (e.g., 'srt:ProductOrServiceAxis')
# - member: Member value (e.g., 'us-gaap:ProductMember')
# - dimension_label: Full format (e.g., 'Product and Service: Products')
# - dimension_member_label: Just the member (e.g., 'Products')
# XBRL facts queries have matching columns
# Note: by_dimension() queries automatically include dimension columns
product_facts = financials.facts.query().by_dimension('srt:ProductOrServiceAxis').to_dataframe()
# Filter by specific dimensions
product_revenue = product_facts[product_facts['dimension_member_label'] == 'Products']
For multi-dimensional items, dimension_member_label uses the LAST (most specific) dimension's member label, fixing ambiguities like "Operating segments" vs "Americas".
New in 5.8.0: Calling by_dimension() automatically includes dimension columns in the query results, since you're explicitly working with dimensional data.
Related Issue: GH-574
New opt-in matrix format for companies with simple equity structures:
equity = financials.statement_of_equity()
# Standard list format (default - most reliable)
print(equity) # Hierarchical presentation
# Opt-in matrix format for cleaner visualization
equity_df = equity.to_dataframe(matrix=True)
# Components as columns: Common Stock, APIC, Retained Earnings, AOCI, etc.
# Activities as rows: Net Income, Dividends, Stock-based comp, etc.
Why opt-in? SEC equity statement formats vary significantly by company. Matrix format works well for companies with simple structures (AAPL, GOOGL, MSFT) but not for complex ones (JPM with many AOCI sub-components). Making it opt-in ensures predictable, reliable output by default.
Related Issue: edgartools-uqg7 (GH-574)
Fixed critical bug where beginning balance values were incorrectly matched to ending balance rows in Statement of Equity DataFrames.
The Problem:
# Before: Beginning balance showed ending values!
equity_df = equity.to_dataframe()
# "Balance at 2023-01-01" row incorrectly showed 2023-12-31 values
The Fix:
Related Issue: edgartools-096c (GH-572)
Fixed bug where balance sheet items with certain concept patterns weren't properly recognized or rendered.
Related Issue: edgartools-17ow (GH-570)
Fixed statement resolver to prefer main equity statements over parentheticals for Oracle and similar companies.
The Problem: Some companies (ORCL) have both main and parenthetical equity statements. The resolver was sometimes selecting the wrong one.
The Fix:
Related Issue: edgartools-8ad8
None. This release maintains full backward compatibility with v5.7.x.
include_dimensions parameter in statement methods is deprecatedview=StatementView.DETAILED instead of include_dimensions=Trueview=StatementView.STANDARD instead of include_dimensions=Falsepip install --upgrade edgartools
After installing, verify your version:
import edgar
print(edgar.__version__) # Should print 5.8.0
Thank you to all contributors who helped with this release!
Special thanks for issue reports and feedback on:
Version 5.9.0 will focus on:
Version 6.0.0 (future major release) will include:
include_dimensions parameter5b82f208 refactor: Make matrix rendering opt-in for equity statements (GH-574)
7c2fffe1 feat: Add matrix rendering for Statement of Equity (GH-574)
264b8982 fix: Prefer main equity statement over parenthetical in resolver
dde205c6 feat: Add StatementView enum for semantic dimension filtering (GH-574)
06f04456 Filter the new dimension columns from xbrl facts when include_dimension=False
5e544da8 test: Add dimension_member_label to METADATA_COLUMNS in regression tests
6ba736f5 feat: Add structured dimension fields to XBRL facts query results (GH-574)
0037d66c fix: Preserve dimension_label and add dimension_member_label (GH-574)
b6f73b3a fix: Correct Statement of Equity roll-forward instant period matching (GH-572)
Structured Dimension Fields in Statement DataFrames (Issue #574)
Structured Dimension Fields in Statement DataFrames (Issue #574)
dimension_axis, dimension_member, and dimension_label columns to statement DataFramesDefinition Linkbase-Based Dimension Filtering (Issue #577)
Filter XBRL Structural Elements from DataFrames
Statement of Equity Period Selection (Issue #572)
8-K Item Parsing Validation
pip install edgartools==5.7.4
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.7.3...v5.7.4
Balance Sheet Item Ordering (Issue #575)
Balance Sheet Item Ordering (Issue #575)
_reorder_by_calculation_parent() method to enforce proper ordering based on calculation linkbaseEmpty Filings Table ArrowTypeError
Release 5.7.3 is a patch release addressing two P0 bugs: balance sheet item ordering and empty filings table handling. Both issues have regression tests to prevent recurrence.
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.7.2...v5.7.3
No breaking changes from v5.7.0/v5.7.1.
This release fixes several issues with the include_dimensions=False default introduced in v5.7.0.
Statement of Equity and Comprehensive Income NaN values (#571): Fixed a regression where these statements showed NaN values after the dimension filtering changes. Statement-type aware filtering now correctly handles equity statements that require certain dimensional data.
Missing Balance Sheet line items (#568, #569): Fixed issues where some balance sheet items were incorrectly filtered out:
preferred_signpip install edgartools --upgrade
No breaking changes from v5.7.0/v5.7.1.
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.7.1...v5.7.2
This release fixes a data accuracy regression introduced in v5.7.0 that caused Statement of Equity and Comprehensive Income to show mostly NaN values.
This release fixes a data accuracy regression introduced in v5.7.0 that caused Statement of Equity and Comprehensive Income to show mostly NaN values.
include_dimensions=False default filtered out dimensional data that these statements requirestatement_of_equity() and comprehensive_income() to include_dimensions=TrueStitchedStatements class for multi-period analysisinclude_dimensions=False for previous behaviorpip install --upgrade edgartools
from edgar import Company
company = Company("AAPL")
filing = company.get_filings(form="10-K").latest()
stmt = filing.xbrl().statements.statement_of_equity()
df = stmt.to_dataframe()
# Should now have values for concepts like:
# - StockIssuedDuringPeriodValueNewIssues
# - Dividends
# - ShareBasedCompensation
This release is highly recommended for all users working with equity statements.
Full changelog: https://github.com/dgunning/edgartools/blob/main/CHANGELOG.md
`include_dimensions` now defaults to `False`: Financial statement methods now show only primary statement lines that match the face of SEC filings. Us
include_dimensions now defaults to False: Financial statement methods now show only primary statement lines that match the face of SEC filings. Users wanting dimensional breakdowns must explicitly pass include_dimensions=True.# Clean view (now the default)
income = xbrl.statements.income_statement() # 25 rows, matches 10-K
# Full dimensional detail when you need it
income = xbrl.statements.income_statement(include_dimensions=True) # 54 rows
Company("AAPL").business_category # 'Operating Company'
Company("SPY").business_category # 'ETF'
Company("JPM").business_category # 'Bank'
Company("O").business_category # 'REIT'
Helper methods: is_fund(), is_financial_institution(), is_operating_company()
Company("BABA").is_foreign # True (Cayman Islands)
Company("BABA").filer_type # 'Foreign'
Company("RY").filer_type # 'Canadian'
Company("AAPL").filer_type # 'Domestic'
pip install edgartools --upgrade
Migration note: If your code relies on dimensional breakdowns appearing by default, add include_dimensions=True to your statement calls.
Issue #564: XBRL Assets values were incorrectly rounded, breaking the balance sheet equation.
Issue #564: XBRL Assets values were incorrectly rounded, breaking the balance sheet equation.
When multiple XBRL facts existed for the same concept/context with different precision (decimals attribute), the code selected the first fact encountered rather than the most precise one.
This caused incorrect values:
_get_fact_precision() and _select_most_precise_fact() helpersBalance sheet equation now balances correctly: Assets = Liabilities + Equity ✓
Thanks to @mpreiss9 for reporting this issue.
Release 5.6.3 focuses on EntityFacts statement display improvements and bug fixes.
Release 5.6.3 focuses on EntityFacts statement display improvements and bug fixes.
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.6.2...v5.6.3
XBRL presentation mode: Fix presentation mode not applying to columns with None values
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.6.1...v5.6.2
Type Checker Issues in Source Code - Added type ignore comments for lxml.etree imports, fixed EntityFilings import path, zero type errors in main sour
pip install edgartools==5.6.1
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.6.0...v5.6.1
Critical: Statement.to_dataframe() Period Filtering
Critical: Statement.to_dataframe() Period Filtering (#548)
Fiscal Year Labeling for Early FYE Companies
Primary Data Preference in Quarterly Periods
Label Column Width with Text Wrapping
Display Design Language System
edgar/display/ package for consistent rich output formattingInsider Transactions Example
Release 5.6.0 is a critical bug fix release addressing period filtering issues in Statement.to_dataframe() (#548), along with a major enhancement introducing the Display Design Language System for consistent, professional output formatting.
This release is recommended for all users, especially those using Statement.to_dataframe() for data analysis.
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.5.0...v5.6.0
Fund statement support for BDCs and investment companies - Extended financial statement capabilities to Business Development Companies and investment
detail parameter - Company.to_context() now supports detail='minimal', 'standard', or 'full' for controlling output verbosityCompany.to_context() plain text formatmcp dependency to allow newer versionsyear parameter means calendar year, not fiscal year (Issue #541)Company.to_context() API examples in ai-integration.mdFull Changelog: https://github.com/dgunning/edgartools/compare/v5.4.0...v5.5.0
This release significantly expands EntityFacts coverage with 15 industry-specific extensions containing 396 concepts learned from 1,298 company filing
This release significantly expands EntityFacts coverage with 15 industry-specific extensions containing 396 concepts learned from 1,298 company filings.
| Industry | Concepts | Key Metrics |
|---|---|---|
| Banking | 83 | Deposits, loan provisions, net interest income |
| Hospitality | 49 | RevPAR, occupancy, ADR |
| Insurance | 45 | Premiums, reserves, claims |
| Utilities | 29 | Regulatory assets, rate base |
| Telecom | 24 | Subscriber metrics, ARPU |
| + 10 more... |
pip install edgartools==5.4.0
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.3.2...v5.4.0
This is a critical patch release fixing a data accuracy bug in financial statement metadata.
This is a critical patch release fixing a data accuracy bug in financial statement metadata.
parent_concept Column Missing Values Due to Dictionary Key Collision (#542)
parent_concept showed None for 85%+ of financial statement concepts that should have parent values_add_metadata_columns() when the same concept appeared multiple times (main item + dimensional breakdowns)parent_concept now correctly shows 'us-gaap_GrossProfit' instead of NoneAffected Users: Anyone analyzing financial statement hierarchies or parent-child relationships, especially for companies with dimensional data (product/geographic segments).
Files Changed: edgar/xbrl/statements.py
Testing: New regression test test_issue_542_parent_concept_dimensional.py verifies fix
Beads Issue: edgartools-0468
Release 5.3.2 is a critical patch release that fixes a data accuracy bug in financial statement parent_concept metadata. The fix ensures correct hierarchy information is preserved for concepts that appear multiple times (main item + dimensional breakdowns), improving metadata population rate from 14% to 72%.
This release maintains full backward compatibility with v5.3.1.
pip install --upgrade edgartools
Special thanks to @Velikolay (Nikolay Ivanov) for the high-quality bug report with detailed analysis.
Full Changelog: https://github.com/dgunning/edgartools/compare/v5.3.1...v5.3.2
This patch release focuses on bug fixes and code quality improvements.
This patch release focuses on bug fixes and code quality improvements.
Empty Document Handling in Filing.text() and Filing.markdown() (#3d576d0e)
Filing List Cache for New Filings (#a3e94c23)
lru_cache decorator from get_current_entries_on_page() functionSchedule 13D/G Joint Filer Aggregation (#fd69921a)
member_of_group field to fix joint filer aggregation (Phase 1)is_aggregate_exclude_shares boolean field to ReportingPerson for shares excluded from aggregate countno_cik boolean field to ReportingPerson for reporting persons without CIK numbersamendment_number field to Schedule13D and Schedule13G classes for tracking amendment sequenceextract_amendment_number() helper function to parse amendment numbers from form namestotal_shares and total_percent properties to exclude shares flagged with is_aggregate_exclude_shares == Truemember_of_group fieldThis release maintains full backward compatibility with v5.3.0.
pip install --upgrade edgartools
Full Changelog: https://github.com/dgunning/edgartools/blob/main/CHANGELOG.md#531---2025-12-16
🤖 Generated with Claude Code
EdgarTools 5.3.0 is a feature release that adds significant new capabilities for Asset-Backed Securities (ABS) filings, filer categorization, and XBRL
Release Date: 2025-12-15
EdgarTools 5.3.0 is a feature release that adds significant new capabilities for Asset-Backed Securities (ABS) filings, filer categorization, and XBRL standardization. This release also includes important bug fixes and code quality improvements.
Full parsing support for Asset-Backed Securities Distribution Reports:
from edgar import Filing
# Get a Form 10-D filing
filing = Filing(company='1234567', cik='1234567', form='10-D', filing_date='2024-01-15', accession_no='0001234567-24-000001')
# Access structured ABS data
ten_d = filing.obj()
print(ten_d.issuing_entity)
print(ten_d.depositor)
print(ten_d.distribution_period)
print(ten_d.abs_type) # CMBS, AUTO, CREDIT_CARD, RMBS, etc.
# Access CMBS XML asset data from EX-102 exhibits
if ten_d.has_cmbs_data:
cmbs_data = ten_d.cmbs_assets
Easy identification of filer status for regulatory and analytical purposes:
from edgar import Company
company = Company("AAPL")
# Check filer status
if company.is_large_accelerated_filer:
print("Large accelerated filer")
if company.is_smaller_reporting_company:
print("Smaller reporting company")
if company.is_emerging_growth_company:
print("Emerging growth company")
# Access full category details
category = company.filer_category
print(category.status) # FilerStatus.LARGE_ACCELERATED
Standardize financial analysis across companies without needing to know company-specific XBRL tag variants:
from edgar.standardization import SynonymGroups
# Get all known tag variants for revenue
revenue_tags = SynonymGroups.get_tags("Revenue")
# Returns: ['Revenues', 'SalesRevenueNet', 'RevenueFromContractWithCustomerExcludingAssessedTax', ...]
# Find the standardized concept for a company-specific tag
concept = SynonymGroups.get_concept("SalesRevenueNet")
# Returns: "Revenue"
# Use with EntityFacts for consistent cross-company analysis
facts = company.get_facts()
revenue_facts = facts[facts['concept'].isin(revenue_tags)]
get_icon_from_ticker to support tickers with hyphens (e.g., BRK-B) - issue #246This release maintains full backward compatibility with v5.2.0. No code changes are required for existing users.
pip install --upgrade edgartools
After installing, verify your version:
import edgar
print(edgar.__version__) # Should print 5.3.0
Thank you to all contributors who helped with this release!
For a complete list of changes, see CHANGELOG.md
New include_dimensions parameter for current period statements to control dimensional data inclusion
include_dimensions parameter for current period statements to control dimensional data inclusionpart_i_item_1, part_ii_item_1a) not being recognized in section ordering, which caused Part II items 1A, 2, and 3 to be skippedFull Changelog: https://github.com/dgunning/edgartools/compare/v5.1.0...v5.2.0
ProxyStatement Data Object for DEF 14A Filings
ProxyStatement Data Object for DEF 14A Filings
ProxyStatement class accessible via filing.obj() for DEF 14A filingsparent_abstract_concept Column in XBRL Facts
parent_abstract_concept column to XBRL facts DataFramesXBRL Date Discrepancy Correction (#513)
DocumentPeriodEndDate in XBRL instance documents<PERIOD> field as authoritative source for document period20-F Section Detection Enhancement
TOC Section Text Extraction
Notebooks Directory Structure (#531)
notebooks/ directoryFull Changelog: https://github.com/dgunning/edgartools/compare/v5.0.2...v5.1.0
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
One column per quarter.