Release v4.20.1 - Critical XBRL Fixes & Performance

Release v4.20.1 - Critical XBRL Fixes & Performance Improvements

Released: 2025-10-17

This point release addresses two critical issues reported by @Velikolay and delivers major performance improvements.

🚀 Key Improvements

Issue #463: XBRL Sign Handling - Balance & Weight Support

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 convention

Impact: Users can now access XBRL semantic information without corrupting instance values. Critical for proper accounting classification and calculation verification.

Issue #464: Missing Past Period Data - 10-50x Faster!

Fixed Balance Sheets showing only current period instead of comparative periods:

• Expanded period search: 4 → 10 instant periods to capture fiscal year ends
• Dynamic thresholds: Adapts to company size (40% of richest period)
• Statement-specific requirements: 30 facts for BS, 20 for IS, 15 for CF
• Concept diversity: 10+ unique concepts required for Balance Sheets
• Performance: 4+ seconds → < 500ms (eliminated 40+ DataFrame conversions)

Impact: Balance Sheets now consistently show 2 complete comparative periods (current + prior year).

Period Key Column

Added period_key column for reliable time series analysis:

• Machine-readable identifiers (e.g., '2024-Q3', '2024-FY')
• Sortable format for chronological operations
• Enables trend calculations without parsing labels

📊 Performance Metrics

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

🔧 Technical Details

Dynamic Thresholds:

• Adaptive fact thresholds: 40% of richest period (min 10, max 40)
• Small companies with sparse data no longer rejected
• Concept diversity ensures Balance Sheet completeness

Flexible Concept Matching:

• Single essential concept matches multiple XBRL variations
• Handles company-specific taxonomy implementations
• Pattern groups for robust period detection

Additional Fixes:

• Bristol Myers future date bug (error handler now preserves document date filter)
• Performance test threshold (adjusted for acceptable caching overhead)
• Issue #408 regression tests (updated for improved filtering)

✅ Quality Assurance

• 1875 tests passing (0 failures)
• Zero breaking changes (all new columns are additive)
• Comprehensive test coverage (19 new tests for Issue #464)
• Cross-company verification (tested across 20+ companies)

📦 Installation

pip install --upgrade edgartools

🙏 Credits

Special thanks to @Velikolay for reporting both critical issues with excellent reproduction cases!

📝 Full Changelog

See CHANGELOG.md for complete details.

---

Previous Release: v4.20.0 (Oct 15, 2025)
Next Release: v4.21.0 (planned for late October)