fix(entity): period_length was accepted, documented, and never read (#1177)

[dgunning]

Fixes #1177. Bead edgartools-07lk.10.2, under edgartools-07lk.10 — the 6.0 unified-error-policy work (GH #933).

The defect

EntityFacts.income_statement(period_length=3) and .cash_flow_statement(period_length=3) returned the annual statement. The parameter sat in both signatures and both docstrings — "Optional filter for period length in months (3=quarterly, 12=annual)" — and was referenced zero times in either body (entity_facts.py:1851-1876 and 2029-2054 before this change). _build_enhanced_statement() has no such parameter to receive it. Per git log -S, it has never been wired since the Facts API landed in 3b44ade1.

This is the silent-failure class 6.0 is closing, in its purest form: a documented input accepted and discarded, wrong data returned, no warning. Same shape as 07lk.10.1 (the hollow Financials), which shipped in 5.54.0.

The fix — honour it, and deprecate it

Staged additively per the 07lk.23 rule. EntityFacts._resolve_period() collapses the three spellings for one concept into a single value:

input	result
period_length=3	'quarterly' + DeprecationWarning naming period='quarterly'
period_length=12	'annual' + same
contradicts period= or annual=	ValidationError(parameter='period_length')
any other value (0, 6, 9, 24, −3)	ValidationError
invalid period=	ValidationError — IS-A ValueError, message unchanged

6.0 removes period_length. period= is the supported spelling and the only one that can also express 'ttm'.

Two default changes make contradiction detection possible, both behaviour-preserving:

• period defaults to None rather than 'annual', so an explicit request is distinguishable from the default. None still resolves to 'annual'.
• cash_flow() had annual=True as a default and forwards period_length, so it would have contradicted itself on every call. Its default is None now, which resolves identically.

Why this is a fix and not a break

There was no way to pass period_length and get what the docstring promised, so no caller can have depended on the old behaviour deliberately. Numbers may change for callers who passed it — those numbers were annual figures under a quarterly label.

Verification

• tests/issues/regression/test_issue_1177_period_length.py, 25 tests.
• Behavioural gate verified: reverting entity_facts.py makes period_length=3 fail for both methods (the builder receives annual=True), and passes after. period_length=12 passes either way — correct, since ignoring it coincidentally gave annual.
• Full fast suite 4204 passed / 9 skipped; tests/issues 2255 passed / 1 xfailed.
• docs/upgrade/6.0.md section added at landing time, per the 07lk.18 standard.

Note

balance_sheet() never accepted period_length and is untouched.

🤖 Generated with Claude Code