EntityFacts: EPS Getter Method and 8-K HTML Financial Exhibit Parsing

[amcamc92]

First of all, thank you for the outstanding work on EntityFacts. The addition of standardized getter methods has been a game-changer for consistent financial data access.

I’d like to propose two potential enhancements that could add significant value:

1. Standardized Getter for EPS:

A unified method such as get_eps() could normalize Earnings Per Share retrieval. Companies use varying tags (e.g., basic vs. diluted EPS), making it difficult to automate consistent access. Having a standardized getter would greatly simplify financial modeling and screening.

2. Parsing of 8-K HTML Financial Exhibits:

Many companies release key financials (including Q4 data) in HTML exhibits attached to 8-Ks.
These datasets are often more up to date than 10-K/10-Q filings. Enabling structured extraction of these tables would provide a richer, more timely dataset for analysis.

Both features would complement the existing design philosophy of EntityFacts by making financial data retrieval more consistent and comprehensive.

Are those potential improvements something that could be considered?

Thanks again!

[dgunning]

Technical Analysis of EntityFacts EPS Getter and 8-K HTML Parsing

Thank you @amcamc92 for these thoughtful feature proposals! Both suggestions align well with EdgarTools' core principles of simplifying financial data access while maintaining accuracy. Let me provide technical analysis for each proposal and gather community input.

1. Standardized EPS Getter Method

Technical Assessment

This is an excellent addition to our existing standardized getter pattern. Looking at the codebase, we already have standardized getters like:

• get_revenue()
• get_net_income()
• get_total_assets()
• get_shareholders_equity()

An get_eps() method would fit perfectly into this pattern.

Implementation Considerations

EPS Concept Variations Found in Codebase:

• us-gaap:EarningsPerShareBasic
• us-gaap:EarningsPerShareDiluted
• us-gaap:EarningsPerShareBasicAndDiluted

Proposed API Design:

def get_eps(self, period: Optional[str] = None, 
           unit: Optional[str] = None,
           diluted: bool = True) -> Optional[float]:
    """
    Get standardized Earnings Per Share value across all companies.
    
    Args:
        period: Optional period in format "YYYY-QN" or "YYYY-FY"
        unit: Optional unit filter (defaults to USD/shares)
        diluted: If True, prefer diluted EPS; if False, prefer basic EPS
        
    Returns:
        EPS value as float, or None if not available
    """

Backwards Compatibility: ✅ This would be a pure addition with no breaking changes.

Unit Handling: The codebase shows EPS uses USD/shares units, which our existing unit normalization should handle correctly.

2. 8-K HTML Financial Exhibit Parsing

Technical Assessment

This is a more complex but valuable enhancement. The codebase shows we already have:

• Strong 8-K parsing capabilities in edgar.company_reports.EightK
• HTML table extraction in edgar.files.htmltools.extract_tables()
• Attachment handling in edgar._filings.Attachments

Implementation Considerations

Current 8-K Capabilities:

• ✅ Parse 8-K items (1.01, 2.03, 9.01, etc.)
• ✅ Extract exhibit attachments
• ✅ HTML table extraction via pandas
• ✅ Rich text processing

Enhancement Opportunities:

1. Structured Financial Table Detection - Pattern matching for financial exhibits
2. Automated Data Extraction - Convert HTML tables to structured facts
3. Integration with EntityFacts - Merge 8-K data with existing facts API

Proposed API Design:

# Access through existing EightK class
eightk = filing.obj()  # 8-K filing object
exhibits = eightk.financial_exhibits()  # New method

# Or through EntityFacts integration
facts = company.get_facts(include_8k_exhibits=True)

Complexity Considerations:

• 📊 Medium-High Implementation Effort - Requires pattern recognition for financial tables
• 🧠 Domain Knowledge Required - Understanding various 8-K exhibit formats
• ⚡ Performance Impact - May slow down facts loading if not optimized

Community Questions

For EPS Getter:

1. Should we default to diluted or basic EPS? (I propose diluted as it's more conservative)
2. Any preference for fallback behavior when preferred EPS type is unavailable?
3. Would a companion get_eps_detailed() method (like existing detailed getters) be valuable?

For 8-K HTML Parsing:

1. Which 8-K exhibit types are most valuable for your use cases? (e.g., earnings releases, acquisition details)
2. Should this be opt-in due to performance considerations?
3. Would you prefer real-time parsing or cached/preprocessed exhibit data?
4. How important is handling of non-standard table formats vs. focusing on common patterns?

Example Usage Scenarios

EPS Getter:

company = Company("AAPL")
facts = company.get_facts()

# Get latest diluted EPS
eps = facts.get_eps()

# Get basic EPS for specific period
eps_basic = facts.get_eps(period="2023-FY", diluted=False)

# Compare across periods
for period in ["2021-FY", "2022-FY", "2023-FY"]:
    eps = facts.get_eps(period=period)
    print(f"{period}: ${eps:.2f}")

8-K Exhibit Integration:

# Get recent 8-K with financial exhibits
filings = company.get_filings(form="8-K").latest(5)
for filing in filings:
    eightk = filing.obj()
    if financial_tables := eightk.financial_exhibits():
        print(f"Found {len(financial_tables)} financial tables")

Next Steps

For EPS Getter (Ready for Implementation):

1. ✅ Clear technical path using existing patterns
2. ✅ Low complexity, high value
3. 🎯 Proposed Timeline: Could be implemented in next minor release

For 8-K HTML Parsing (Requires Planning):

1. 📋 Need community input on priority exhibit types
2. 🔬 Requires research phase to analyze common exhibit patterns
3. 🧪 Prototype development to validate approach
4. 🎯 Proposed Timeline: Research → Prototype → Community feedback → Implementation

Both features would enhance EdgarTools' goal of making financial data more accessible while maintaining our focus on accuracy and user experience.

Community: Please share your thoughts on API design preferences and use case priorities!

[dgunning]

Sorry, I had one of my agents research the approach

I will put these on the feature backlog and see if they can be done in an upcoming release

[amcamc92]

Thanks, Dwight!

A few thoughts after reviewing your agent’s research:

• Some companies used to report basic and diluted EPS as a single fact, and later switched to separate basic and diluted facts.

• Ideally, the behavior should ensure the data is complete across all quarters/years.

• I agree that diluted EPS should be the primary focus, but as a fallback, it would make sense to fill gaps with basic or even a combined basic+diluted value when no better data is available.

• A reconstruction strategy could also be applied when both Net Income and the number of shares are reported for the missing periods.

On the HTML tables parser: in my experience, the formats and structures of exhibits vary widely. This would require a careful study of patterns and enough flexibility in the approach to build something truly robust.

Hope this helps, and thanks again!