fix(schedule13): no sale or purchase from ownership figures a filing leaves out

[monody0007]

Problem

OwnershipComparison added up aggregate_amount and percent_of_class over reporting_persons, and the Schedule 13D/G parsers stored a figure the filing does not report as 0. When one of the two filings leaves its figures out, the other filing's whole position shows up as bought or sold. A filing can leave them out in three ways:

• Amendments. The schema makes every figure on a reporting person's cover page optional on 13D/A and 13G/A (docs/sec/schedule13/schema-reference.md: m on 13D/13G, o on the amendments). The reporting-person row itself is still mandatory. safe_int() / safe_float() turned an absent element into 0.
• Pre-2025 header-only filings (has_structured_data is False). Their reporting persons carry placeholder zeros.
• Structured XML with an empty <reportingPersons>.

Reproduction with the fixtures in tests/data/beneficial_ownership/. Turn the Aadi Bioscience 13D (2,100,000 + 2,435,000 shares) into a 13D/A: add previousAccessionNumber and amendmentNo, and drop the six optional figures from both reporting persons. Compared with the original, main returns shares_change == -4535000, percent_change == -18.4 and is_liquidating == True. The same change to the Jushi Holdings 13G (two 10,000,000-share rows) gives -20000000.

Why this is staged for 5.x

The simplest fix would make these values None. But that changes public numeric types, and engineering/6.0-release-plan.md ("Branching and release model") says main keeps shipping 5.x with fixes that don't break anyone. Incompatible changes wait for the 6.0 window, and each item ships an additive half in 5.x first. The same approach was used for FactQuery.to_dataframe(), where fiscal_year stays int64 until 6.0 and is listed under Still to come in docs/upgrade/6.0.md. So this PR ships the additive half and leaves every existing field and property with the type it has on main.

An earlier revision of this PR made the fields Optional right away. The previous head (fad3358) also made shares_change / percent_change return None for header-only filings. This revision drops both type changes.

Change

• ReportingPerson.unreported_fields (new, frozenset[str]) names the ownership figures the filing leaves out. The parsers fill it for absent or non-numeric elements. A header-only person gets all six.
• ReportingPerson.reported(figure) (new) returns the figure, or None if the filing leaves it out. A reported 0 returns 0. An unknown field name raises ValidationError.
• The six fields keep their int / float types and still hold the placeholder 0. The same goes for total_voting_power, total_dispositive_power, total_shares and total_percent.
• OwnershipComparison.reported_shares_change / reported_percent_change (new) return None when either filing has no rows, or when any reporting person leaves out that figure. Shares and percent are checked separately.
• is_accumulating, is_liquidating, is_unchanged now use those new properties, so an unknown change sets none of them. They stay bool. This is the fix for the fabricated sale or purchase.
• shares_change, percent_change, get_summary() still return the same numbers as on main. When they count an unreported figure as 0, they now emit a FutureWarning saying that 6.0 returns None and naming the reported_* replacement. The warning text is fixed, so Python's default filter shows it once per call site. get_summary() also gains the keys reported_shares_change and reported_percent_change.
• Display: to_context() prints "not reported" and the Rich tables print "unavailable" for unreported figures, instead of 0.
• Typing: safe_int() / safe_float() get typing.overload signatures. The parsers call them with default=None to tell a missing figure from a reported 0, which the old int / float annotations did not allow. The default call still returns int / float. There is no runtime change.
• Unchanged: a reported 0 is still 0 everywhere. Rows are still summed, so aggregation for joint filers whose rows overlap is not fixed here. The guide already says so.

Docs and changelog:

• changelog.d/1379.fixed.md covers the direction flags and the warning.
• changelog.d/1379.added.md covers the new accessors.
• docs/upgrade/6.0.md gets one Still to come row for the 6.0 flip: the fields, totals, shares_change, percent_change and the summary values become None. Following that page's rule, nothing is added above that table, because nothing in this PR changes what existing code receives.
• docs/guides/schedule13dg-data-object-guide.md documents the new accessors and shows a None-safe comparison example.

The regression tests are in tests/issues/regression/test_issue_1379_schedule13_unreported_figures.py, with the provenance line CONTRIBUTING asks for. The tests this PR had added to tests/beneficial_ownership/test_beneficial_ownership.py moved there, so that file is unchanged from main.

Tests

All tests run offline with -p tests._offline_harness, which blocks sockets, and use the local fixtures. There are no cassettes and no SEC calls. The amendment fixtures are built from the existing XML to match the table in the repo's schema reference. They were not validated against the SEC XSD, which is not in the repository.

pytest -p tests._offline_harness -p no:pytest-retry -v tests/issues/regression/test_issue_1379_schedule13_unreported_figures.py

• This branch: 14 passed (12 functions; two are parametrised over 13D and 13G).

• Same test file against edgar/ from main (73491ae): 10 failed, 4 passed. Four failures are assert True is False on the direction flags: the header-only, no-rows, 13D/A and 13G/A comparisons report a purchase or sale. The other six are the new accessors being absent.

• test_rich_persons_table_shows_unreported_figures_as_unavailable checks every cell of the Rich persons table. One person leaves out its shares and shared voting power, and the other person reports every figure. The earlier tests only checked the Total Shares: line. Two mutations of rendering.py now fail both cases (13D and 13G), where before they passed every test:

  • putting the per-person cells back to the raw fields gives '0' != 'unavailable';
  • counting a missing sole or shared power as 0 in the Voting Power cell gives '0' / '10,000,000' != 'unavailable'.

• Before the latest commit, the test file had 12 cases. Against the earlier head of this PR (fad3358), those 12 cases gave 9 failed, 3 passed. The 13D/A and 13G/A comparisons still fail is_liquidating is False (assert True is False). test_unreported_figures_keep_their_5x_types fails with TypeError: unsupported format string passed to NoneType.__format__, because f"{comparison.shares_change:+,}" against a header-only filing gets None. The rest are the new accessors being absent.

• Controls that pass on main, on fad3358 and on this branch:

  • an explicit zero (selling out is still -4,535,000, and 0 → 0 is unchanged);
  • a single-person sale of 500,000;
  • a 13G/A that reports its figures (−4,000,000, −2.0 points).

  The three controls also assert that no FutureWarning is raised when every figure is reported.

• test_unreported_figures_keep_their_5x_types also passes on main. It checks that format(person.aggregate_amount, ',') and f"{comparison.shares_change:+,}" still work for a header-only filing.

pytest -p tests._offline_harness -p no:pytest-retry -q -m 'not network' tests/beneficial_ownership \
  tests/issues/regression/test_issue_802_schedule13_cusip_nested.py \
  tests/issues/regression/test_issue_804_schedule13_event_date_alias.py \
  tests/issues/regression/test_issue_840_schedule13_partial_object.py \
  tests/issues/regression/test_issue_1379_schedule13_unreported_figures.py

57 passed, 1 deselected. The deselected test is the network test test_aapl_pre_mandate_sc13g_ground_truth, which was not run.

Other checks:

• TestSchedule13DToContext in tests/display/test_to_context.py needs the SEC, so it was not run.
• ruff check on the touched files reports the same three findings as on main (S110 twice, F841) and none new.
• pyright (1.1.414) on edgar/beneficial_ownership/schedule13.py: the two default=None argument errors on safe_int / safe_float are gone, and there are no new errors. pyright is not run in CI.
• scripts/check_regression_provenance.py: OK, 402 files. scripts/check_regression_skips.py: OK.
• scripts/release/assemble_changelog.py --check: 6 fragments ready.

Prepared with AI assistance (Claude); the results above come from local test runs.