Document AuthorityRecord/HoldingsRecord and their readers; fix stale stubs

[dchud]

Fills in the Python API reference for the non-bibliographic record types, and corrects the canonical type stubs that turned out to be wrong.

Docs (docs/reference/python-api.md)

• AuthorityRecord — full section: leader/errors properties; heading/tracing/note/linking accessors (heading, heading_text, see_from_tracings, see_also_tracings, notes, linking_entries); general field accessors (record_type, get_field, get_field_or_err, get_fields, get_control_field, to_json).
• HoldingsRecord — full section: holdings-specific accessors with their MARC tags (locations 852, captions_* 853-855, enumeration_* 863-865, textual_holdings_* 866-868) plus the general accessors.
• AuthorityMARCReader / HoldingsMARCReader — new sections with constructor keywords (recovery_mode defaults to "permissive" here, unlike MARCReader's "strict"; validation_level) and iteration examples.
• Added a "choosing a reader" table cross-linking the three readers; noted there are no dedicated authority/holdings writers.
• Retired the "full API surface is not yet covered" placeholders from PR Add get_field / get_field_or_err to AuthorityRecord and HoldingsRecord #216.

Stub fix (mrrc/_mrrc.pyi)

While documenting, the canonical stubs for both record types were found materially wrong and were rewritten to match the PyO3 surface:

• phantom fields() method (doesn't exist)
• control_field() → actually get_control_field()
• leader declared as a method → it's a property
• get_fields() typed List[Field] → actually Optional[List[Field]]
• ~9 (authority) / ~13 (holdings) real members omitted entirely

Every documented method was verified at runtime against tests/data/simple_authority.mrc and simple_holdings.mrc; the phantom methods confirmed absent.

.cargo/check.sh green (565 Rust tests, doc tests, clippy, ruff, mkdocs build).

Closes #217

Bead: bd-0x73.21.10

[codspeed-hq]

Merging this PR will not alter performance

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 8 improved benchmarks
❌ 8 regressed benchmarks
✅ 44 untouched benchmarks
⏩ 18 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
❌	WallTime	test_parallel_read_4x_1k	95.3 ms	109.1 ms	-12.6%
⚡	WallTime	test_pipeline_sequential_extraction_4x_10k	124 ms	110.9 ms	+11.76%
⚡	WallTime	test_process_4_files_sequential	103.4 ms	93.6 ms	+10.44%
❌	WallTime	test_threaded_reading_4x_10k	980.4 ms	1,119.2 ms	-12.41%
⚡	WallTime	test_process_8_files_parallel_4_threads	279.6 ms	241.6 ms	+15.73%
❌	WallTime	test_threaded_with_title_extraction_4x_10k	972.2 ms	1,141.4 ms	-14.82%
❌	WallTime	test_parallel_read_4x_10k	980 ms	1,121.3 ms	-12.6%
❌	WallTime	test_threaded_reading_4x_1k	91.8 ms	108.1 ms	-15.04%
⚡	WallTime	test_pipeline_parallel_extraction_4x_10k_threaded	158.2 ms	138.9 ms	+13.84%
⚡	WallTime	test_process_4_files_parallel_4_threads	135.6 ms	112.4 ms	+20.56%
❌	WallTime	test_parallel_read_with_extract_4x_10k	1 s	1.2 s	-13.59%
❌	WallTime	test_threading_speedup_4x_10k	945.1 ms	1,128.9 ms	-16.28%
❌	WallTime	test_file_parallel_4x_10k_with_extraction	1.1 s	1.3 s	-13.86%
⚡	WallTime	test_pipeline_sequential_1x_10k	24.1 ms	21.9 ms	+10.12%
⚡	WallTime	test_pipeline_parallel_4x_10k_threaded	130.7 ms	115 ms	+13.69%
⚡	WallTime	test_bytesio_vs_file_isolation	55.2 ms	50 ms	+10.5%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing docs/auth-holdings-python-api (0c754fc) with main (ce2e0e8)}

Footnotes

1. 18 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩