Clarify whether `XBRL.entity_info["reporting_end_date"]` means maximum instant-context coverage or the filing report date

[synfonia-llc]

Feature Category

• New API functionality
• Performance improvement
• Developer experience improvement
• Documentation enhancement
• Tool/utility addition

Problem Statement

Is your feature request related to a problem? Please describe.

XBRL.entity_info exposes both document_period_end_date and reporting_end_date, but the public meaning of reporting_end_date is unclear. In EdgarTools 5.53.0 it is the maximum date among every instant context in the instance, not necessarily the filing's period of report.

That distinction matters because an instant context can describe a cover-page share count, a contract date, a credit-facility date, or another post-period event. A caller can reasonably read the current field name as the report-period end and silently apply the wrong cutoff.

Who would benefit from this feature?

• Beginner Python users working with SEC filings
• Financial analysts and researchers
• Advanced developers building financial applications
• Data scientists working with financial datasets

Proposed Solution

Describe the solution you'd like

Please define the contract for both date fields in the API documentation and docstrings:

• If reporting_end_date is intended to mean maximum instant-context coverage, document that explicitly and consider a clearer alias such as max_instant_context_date.
• If it is intended to mean the filing's period of report, derive it from document-period metadata and expose the maximum instant-context date separately.
• State whether the values are date, datetime, string, or nullable across supported parsing routes.

An additive alias plus clarified documentation would preserve existing behavior while giving callers a semantically explicit field.

Describe alternatives you've considered

Callers can compute both values independently from document_period_end_date and the context collection, but every caller must then rediscover the distinction. Documentation alone would reduce ambiguity; an explicit alias would make misuse less likely.

Use Case Example

How would you use this feature?

from pathlib import Path

from edgar.xbrl import XBRL

# Run from a directory containing the unpacked accession package.
xbrl = XBRL.from_directory(
    Path("0000950170-23-047713") / "xbrl"
)

period_end = xbrl.entity_info["document_period_end_date"]
maximum_instant = max(
    context.period["instant"]
    for context in xbrl.contexts.values()
    if context.period.get("type") == "instant"
)

print("document period end:", period_end)
print("current reporting_end_date:", xbrl.entity_info["reporting_end_date"])
print("maximum instant context:", maximum_instant)

For Oracle accession 0000950170-23-047713, the output is:

document period end: 2023-08-31
current reporting_end_date: 2023-09-07
maximum instant context: 2023-09-07

The latest instant is used by dei:EntityCommonStockSharesOutstanding, not by the filing's period-of-report fact.

Implementation Considerations

Complexity Level:

• Simple (minor API addition)
• Moderate (new functionality with existing patterns)
• Complex (significant architectural changes)

Backwards Compatibility:

• This feature maintains backwards compatibility
• This feature might break existing code (please explain below)
• Unsure about compatibility impact

The release implementation deliberately iterates all instant contexts and retains the maximum date. The relevant pinned source is InstanceParser._extract_entity_info(). An additive alias and documentation can preserve that behavior.

Additional Context

This was reproduced with EdgarTools 5.53.0, CPython 3.14.4, and locally cached Oracle 10-K/10-Q packages. In all 12 tested filings, document_period_end_date matched the filing report date while reporting_end_date was later and matched the maximum instant-context date.

Examples included:

• Q1 FY2024: 2023-08-31 versus 2023-09-07, associated with shares outstanding;
• FY2024: 2024-05-31 versus 2024-06-20, associated with lease-related contexts;
• Q3 FY2026: 2026-02-28 versus 2026-03-06, associated with credit-facility contexts; and
• FY2026: 2026-05-31 versus 2026-06-22, associated with a purchase-obligation context.

This request does not assert that the current calculation is wrong. It asks the maintainer to confirm and document which meaning the public field promises.

Related Issues/Features:

A bounded search of open and closed issues for reporting_end_date on August 31, 2026 did not identify an exact match. Please recheck before submission.

---

Feature requests are evaluated based on EdgarTools' core principles: Simple yet powerful, accurate financials, beginner-friendly, and joyful UX.