adsfolio.pdf.identity_repair

Reversible repair of PDFs that are attached to the wrong paper.

The repair is explicit and manifest-driven. Each manifest entry names one catalog attachment, the PDF hash it was verified against, and the full ADS document that the PDF really is. Every check runs before any change is made. Applying an entry reassociates only that attachment with the correct document, replaces the automatic bibliographic metadata, renames the file, and writes a durable journal, a database backup, and PDF copies so the operation can be undone. PDF bytes are never modified or overwritten.

exception adsfolio.pdf.identity_repair.IdentityRepairError[source]

Bases: RuntimeError

A preflight check failed, or an applied repair could not be completed.

class adsfolio.pdf.identity_repair.RepairEntry(path, sha256, location_id, attachment_id, document_id, metadata_before, proposed_ads_record, authorized_locked_fields=(), reviewed_parser_errors=(), audit_reference='')[source]

Bases: object

One verified wrong association from the manifest.

Notes

“path” is the absolute PDF path inside the library root and “sha256” the hash of the verified bytes. “location_id” and “attachment_id” must stay unchanged; “document_id” is the wrongly associated document, or None to skip that check. “metadata_before” holds fields the catalog must still contain. “proposed_ads_record” is the full ADS document of the paper the PDF really is. “authorized_locked_fields” lists locked fields the plan may overwrite; a change to any other locked field is rejected. reviewed_parser_errors and audit_reference record an explicit audit of partially readable evidence, without granting automatic verification.

Parameters:
attachment_id: int
audit_reference: str = ''
authorized_locked_fields: tuple[str, ...] = ()
document_id: int | None
location_id: int
metadata_before: dict[str, Any]
path: str
proposed_ads_record: dict[str, Any]
reviewed_parser_errors: tuple[str, ...] = ()
sha256: str
adsfolio.pdf.identity_repair.apply_repairs(catalog, root, entries, settings, journal_dir)[source]

Preflight, back up, and apply every entry; revert everything on failure.

SQLite cannot hold one transaction across catalog methods (each commits), so every item records its steps in the journal and a failure reverts the recorded steps from exact row snapshots. If a revert step itself fails, the journal phase is failed_partial and lists what still needs undo_repair; the database is never restored wholesale.

Parameters:

  • catalog (PdfCatalog) – Catalog holding the library. No other writer may be active.

  • root (Path) – Library root.

  • entries (sequence of RepairEntry) – Manifest entries; all are checked before the first change.

  • settings (RenameSettings) – Rename format.

  • journal_dir (Path) – Directory for the journal and the backup.

Returns:

The journal file (phase applied).

Return type:

Path

Raises:

IdentityRepairError – A check failed or an item could not be applied. When the revert succeeded, nothing has changed.

adsfolio.pdf.identity_repair.build_plan(catalog, root, entries, settings)[source]

Check every entry and return the exact changes.

Library files and catalog rows are not modified.

Parameters:

  • catalog (PdfCatalog) – Catalog holding the library.

  • root (Path) – Library root; every manifest path must be inside it.

  • entries (sequence of RepairEntry) – Manifest entries.

  • settings (RenameSettings) – Rename format. A target that already exists gets the numeric suffix of unique_destination; the existing file is never touched.

Returns:

JSON-compatible plan with root-relative old and new names, hashes, IDs, and the metadata before and after, per item.

Return type:

dict

Raises:
adsfolio.pdf.identity_repair.load_manifest(path)[source]

Read a JSON list of manifest entries.

Raises:

IdentityRepairError – The file is not a list of objects with the required fields.

Parameters:

path (pathlib.Path)

Return type:

list[adsfolio.pdf.identity_repair.RepairEntry]

adsfolio.pdf.identity_repair.undo_repair(catalog, journal_path)[source]

Reverse a completed repair from its journal.

Every item is checked first: the repaired file, the catalog rows, and the target document must be exactly as the repair left them, and the original path must be free. An intervening edit or collision refuses the whole undo before anything changes.

Parameters:

  • catalog (PdfCatalog) – Catalog the repair was applied to.

  • journal_path (Path) – Journal written by apply_repairs.

Returns:

The journal file (phase undone).

Return type:

Path

Raises:

IdentityRepairError – The journal phase does not allow undo, a check fails, or a revert step fails (the journal then lists what remains).