Remove the DataFetcher-era methods now that locators and rootfilespec.reader exist

[nsmith-]

🤖 AI generated content

Follow-up to the Locator migration (#59) and to the reader interface added in #112. Two generations of "get me the object" API now coexist; the older one should go, in a PR of its own.

Older interface (takes fetch_data: DataFetcher = Callable[[int, int], ReadBuffer] and does the read inside the object):

• ROOTFile.get_TFile, ROOTFile.get_StreamerInfo (src/rootfilespec/bootstrap/TFile.py:185, :204) — duplicated by tfile_locator / streamerinfo_locator, including the validation logic, which has already drifted between the two copies
• TFile.get_KeyList (TFile.py:263), TDirectory.get_KeyList (src/rootfilespec/bootstrap/TDirectory.py:109) — duplicated by keylist_locator
• TKey.read_object(fetch_data, objtype=...) (src/rootfilespec/bootstrap/TKey.py:98-143) — still the implementation behind TKey.read_from / TypedTKey.read_from, which call it with a lambda returning the buffer; invert that so read_from(buffer) is the implementation
• the DataFetcher alias itself (src/rootfilespec/serializable.py:353)

Middle generation (takes Callable[[Locator], ReadBuffer]): ROOT3a3aRNTuple.get_header / get_footer, FooterEnvelope.get_pagelists, PageListEnvelope.get_pages, RPageDescription.get_page, REnvelopeLink and RNTuple.from_anchor. These fetch eagerly inside library code, which is at odds with docs/design.md ("objects describe where data is; callers decide when and how to fetch it"). rootfilespec.reader.Fetcher.buffer has the matching shape today so they keep working; decide whether RNTuple.from_anchor stays as a convenience (then probably taking a Fetcher) or moves next to FileReader.

To do:

• Remove the methods of the first list, make read_from(buffer) the primary implementation on TKey
• Decide the fate of the second list
• Convert tests/test_rntuple_hardcoded.py::test_read_multiple_rntuples, the last test on the old interface (kept that way in Vendor root-io-spec and fix the first three quick wins from the bootstrap review #112 so these methods stay covered until they are removed)
• Update docs/design.md
• Note the removal in the changelog / release notes: API-breaking for downstream users (the hydrator, the uproot integration draft in Integration with Uproot  #46)

Related: #112, #59, #46, #81 (comparing the key image at the front of a record with the key-list copy — the natural place is the new read_from).

Assisted-by: claude-code:claude-fable-5-1

[sathabbott]

@nsmith- do you mind if i take this over? if you do mind, can you handle it before i start working on rootfilespec again? my claude is very hung up on this. lol

[nsmith-]

Yeah in fact this almost did not go far enough:

These fetch eagerly inside library code, which is at odds with docs/design.md ("objects describe where data is; callers decide when and how to fetch it").

the middle generation is also not what where we want to end up. What we want is that both older and middle generation is migrated to the locator pattern. The migration in #59 did not seem to finish the job, leaving some of the RNTuple classes not migrated to the *_locator(...) API style.

Go ahead and set it at this as a standalone PR (finish the Locator migration)

[sathabbott]

🤖 AI generated content

Thanks. Plan for "finish the Locator migration", as one PR; shout if you'd go another way on any of these:

• Remove the DataFetcher methods and alias. TKey.read_from(buffer) becomes the implementation, with no behaviour change (the TKey.read_object: trailing-byte arithmetic for TKeyList is wrong when the record is compressed #82 / RNTuple anchor: verify the checksum, tolerate other anchor lengths, implement fMaxKeySize chunking #85 items stay separate). Checks that only get_TFile / get_StreamerInfo have move into the locators first.
• Remove every middle-generation fetcher: get_header, get_footer, REnvelopeLink.read_envelope, get_pagelists, get_pages, get_page. The chain is anchor → header_locator / footer_locator → pagelist_locators → page_locators.
• Remove RNTuple.from_anchor. Add a pure RNTuple.from_envelopes(header, footer, pagelists) with the checksum consistency checks, and put the fetching convenience next to FileReader in rootfilespec.reader.
• RPageDescription stops being a locator itself. Pages are read through page_locator (from [rntuple] Store page checksums #55), which covers the checksum trailer.
• Update docs/design.md, add a test that no public method in bootstrap / rntuple takes a fetch callable, and list the breaking changes in the PR description for the release notes.