Latest Results
Pymarc exception-class-name parity verification + docs (#185)
* Pymarc exception-class-name parity verification + documentation
Closes #155
bd-0x73.6's narrow scope per the 2026-05-03 re-scope: verify that a
pymarc-shaped error-handling code path keeps working after a port,
and document the small gaps where it doesn't.
Adds tests/python/test_pymarc_exception_parity.py — 47 cases that
pin:
- Every pymarc 5.3.1 exception class name a typical except clause
catches is importable from both mrrc.exceptions and the top-level
mrrc package (10 names: RecordLengthInvalid, RecordLeaderInvalid,
RecordDirectoryInvalid, BaseAddressInvalid, BaseAddressNotFound,
EndOfRecordNotFound, TruncatedRecord, FieldNotFound,
FatalReaderError, BadSubfieldCodeWarning).
- Each shared-name class is a proper Exception/Warning subclass and,
for the exceptions, inherits from MrrcException so callers can
catch the mrrc base class instead of PymarcException.
- pymarc names mrrc deliberately omits (NoFieldsFound,
WriteNeedsRecord, NoActiveFile, BadLeaderValue, MissingLinkedFields)
remain absent — guarding against accidental drift — and each
omission carries a one-line rationale in the test source.
- A pymarc-shape except RecordDirectoryInvalid: actually catches
what mrrc raises on the E101 non-ASCII-tag fixture.
- A port using except MrrcException: catches every typed variant.
Extends docs/guides/migration-from-pymarc.md with the class-name
mapping table, the omissions table with rationale per omission, and
an explicit section on the FatalReaderError inheritance-hierarchy
divergence (mrrc keeps the fatal record-level classes as siblings
under MrrcException; FatalReaderError in mrrc means "recovered-error
cap exceeded" specifically). Two pymarc-compatible migration recipes
spelled out for that divergence.
No code changes — the verification is the deliverable.
Bead: bd-0x73.6
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Consolidate pymarc-compat docs: catalog in reference, recipes in guide
Splits the responsibilities cleanly between the two error-handling
docs to remove the duplication my earlier commit introduced:
docs/reference/error-handling.md (the catalog — for users writing
new mrrc code):
- Updates the stale "MARCReader.current_exception / current_chunk"
section. The reference said "mrrc does not currently expose these
reader-side attributes" — predated PR #182 (bd-0x73.7). Replaced
with the actual landed semantics plus the encoding-strictness
and byte-read-error divergences.
- Adds a "Known hierarchy divergences from pymarc" subsection
noting the FatalReaderError parentage difference (its tree
diagram showed the actual mrrc shape but didn't call out the
comparison to pymarc) and the PymarcException → MrrcException
base-class rename.
- Expands the omissions row in the mapping table into a full
sub-table with rationale and mrrc-equivalent behavior for
NoFieldsFound, WriteNeedsRecord, NoActiveFile, BadLeaderValue,
MissingLinkedFields.
docs/guides/migration-from-pymarc.md (the porter's recipe — for
users with existing pymarc code in front of them):
- Drops the duplicated class-name mapping table and the omissions
table that just landed; replaced with a one-sentence summary and
a link to the reference for the catalog.
- Keeps the inline migration recipes (base-class rename, the two
FatalReaderError catch patterns) since porters want them inline,
not "go read the reference."
- Trims explanatory prose for the FatalReaderError divergence and
links to the reference for the rationale.
Net diff: -66 noise lines in the guide, +93 substance lines in the
reference. CHANGELOG entry updated to reflect the split.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Pymarc exception-class-name parity verification + docs (#185)
* Pymarc exception-class-name parity verification + documentation
Closes #155
bd-0x73.6's narrow scope per the 2026-05-03 re-scope: verify that a
pymarc-shaped error-handling code path keeps working after a port,
and document the small gaps where it doesn't.
Adds tests/python/test_pymarc_exception_parity.py — 47 cases that
pin:
- Every pymarc 5.3.1 exception class name a typical except clause
catches is importable from both mrrc.exceptions and the top-level
mrrc package (10 names: RecordLengthInvalid, RecordLeaderInvalid,
RecordDirectoryInvalid, BaseAddressInvalid, BaseAddressNotFound,
EndOfRecordNotFound, TruncatedRecord, FieldNotFound,
FatalReaderError, BadSubfieldCodeWarning).
- Each shared-name class is a proper Exception/Warning subclass and,
for the exceptions, inherits from MrrcException so callers can
catch the mrrc base class instead of PymarcException.
- pymarc names mrrc deliberately omits (NoFieldsFound,
WriteNeedsRecord, NoActiveFile, BadLeaderValue, MissingLinkedFields)
remain absent — guarding against accidental drift — and each
omission carries a one-line rationale in the test source.
- A pymarc-shape except RecordDirectoryInvalid: actually catches
what mrrc raises on the E101 non-ASCII-tag fixture.
- A port using except MrrcException: catches every typed variant.
Extends docs/guides/migration-from-pymarc.md with the class-name
mapping table, the omissions table with rationale per omission, and
an explicit section on the FatalReaderError inheritance-hierarchy
divergence (mrrc keeps the fatal record-level classes as siblings
under MrrcException; FatalReaderError in mrrc means "recovered-error
cap exceeded" specifically). Two pymarc-compatible migration recipes
spelled out for that divergence.
No code changes — the verification is the deliverable.
Bead: bd-0x73.6
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* Consolidate pymarc-compat docs: catalog in reference, recipes in guide
Splits the responsibilities cleanly between the two error-handling
docs to remove the duplication my earlier commit introduced:
docs/reference/error-handling.md (the catalog — for users writing
new mrrc code):
- Updates the stale "MARCReader.current_exception / current_chunk"
section. The reference said "mrrc does not currently expose these
reader-side attributes" — predated PR #182 (bd-0x73.7). Replaced
with the actual landed semantics plus the encoding-strictness
and byte-read-error divergences.
- Adds a "Known hierarchy divergences from pymarc" subsection
noting the FatalReaderError parentage difference (its tree
diagram showed the actual mrrc shape but didn't call out the
comparison to pymarc) and the PymarcException → MrrcException
base-class rename.
- Expands the omissions row in the mapping table into a full
sub-table with rationale and mrrc-equivalent behavior for
NoFieldsFound, WriteNeedsRecord, NoActiveFile, BadLeaderValue,
MissingLinkedFields.
docs/guides/migration-from-pymarc.md (the porter's recipe — for
users with existing pymarc code in front of them):
- Drops the duplicated class-name mapping table and the omissions
table that just landed; replaced with a one-sentence summary and
a link to the reference for the catalog.
- Keeps the inline migration recipes (base-class rename, the two
FatalReaderError catch patterns) since porters want them inline,
not "go read the reference."
- Trims explanatory prose for the FatalReaderError divergence and
links to the reference for the rationale.
Net diff: -66 noise lines in the guide, +93 substance lines in the
reference. CHANGELOG entry updated to reflect the split.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Latest Branches
-35%
-34%
dependabot/uv/urllib3-2.7.0 -20%
feat/pymarc-exception-class-parity © 2026 CodSpeed Technology