adsfolio.pdf.renamer

Template-based PDF renaming engine.

exception adsfolio.pdf.renamer.MissingTemplateFieldsError(missing_fields)[source]

Bases: ValueError

Report missing metadata required by a filename template.

Parameters:

missing_fields (collections.abc.Sequence[str])

Return type:

None

missing_fields

Template field names that have no metadata value.

Type:

tuple of str

class adsfolio.pdf.renamer.PdfRenamer(client=None)[source]

Bases: object

Render rename templates and optionally apply them to disk.

Parameters:

client (ADSClient | None)

batch_rename(sidecar, template='{authors}_{bibcode}-{title}', dry_run=True, author_format='surname_initials', max_authors=3, authors_when_truncated=1, char_policy='keep', move_resolved_from=None, move_resolved_to=None, author_separator='+', author_truncation_suffix='+', current_filenames=None)[source]

Rename tracked PDFs with verified ADS or ready local metadata.

If both move directories are supplied, resolved files below move_resolved_from are placed in move_resolved_to after the new filename is rendered. Non-ADS records are renamed in place.

Records whose identity is not proven by the PDF itself are skipped, including in a dry run. Their tracked names and reasons are kept in identity_refused until the next call.

current_filenames, when supplied, limits processing to these current paths relative to the catalog root. An empty sequence selects no files. A Unicode alias selects a current path only when its directory entry proves the match.

Use the selected template without substitution. Skip records when a referenced field has no value. Record unchanged targets in unchanged and other skipped reasons in skipped. Clear these mappings for each call.

Parameters:
Return type:

list[tuple[str, str]]

rename_tracked_file(state, source_path, metadata, template='{authors}_{bibcode}-{title}', dry_run=True, author_format='surname_initials', max_authors=3, authors_when_truncated=1, char_policy='keep', author_separator='+', author_truncation_suffix='+', target_directory=None)[source]

Plan or apply a rename for one tracked resolved PDF.

Raises:

MissingTemplateFieldsError – The template references fields without metadata. No move occurs.

Parameters:
Return type:

pathlib.Path

render(template, metadata, author_format='surname_initials', max_authors=3, authors_when_truncated=1, char_policy='keep', author_separator='+', author_truncation_suffix='+')[source]

Render a filename from metadata and rename template.

Parameters:
Return type:

str

sanitize_filename(name, max_bytes=240)[source]

Normalize a filename to a filesystem-safe form.

Parameters:
Return type:

str

adsfolio.pdf.renamer.identity_view(record)[source]

Flatten a catalog or sidecar record into one metadata mapping.

Nested metadata values are overridden by top-level record fields, matching how readiness checks read the same record.

Parameters:

record (collections.abc.Mapping[str, Any])

Return type:

dict[str, Any]

adsfolio.pdf.renamer.recover_stale_record(state, relative_path, *, apply)[source]

Reverify a changed PDF against its cached ADS record.

Parameters:
Returns:

Flat, rename-ready metadata, or None if recovery does not apply.

Return type:

dict or None

Raises:

IdentityValidationError – The cached record, PDF, catalog, or shared locations cannot be verified.

Notes

Recovery also handles a changed file before the catalog scans it. It never fetches a provider record or changes the shared document metadata. Recovery retains prior identity proof and content versions as history.

adsfolio.pdf.renamer.verify_record_identity(pdf_path, record, *, sha256=None, manual_confirmation=False, manual_conflict_override=False, provider_document=None, state=None, client=None, providers=(DoiProvider.ADS, DoiProvider.CROSSREF, DoiProvider.DATACITE))[source]

Check that a stored record is proven to describe the PDF’s bytes.

Parameters:

  • pdf_path (Path) – PDF that a write or rename would affect.

  • record (Mapping[str, Any]) – Catalog or sidecar record, flat or with nested metadata.

  • sha256 (str, optional) – Digest the proof must be tied to. Defaults to the record’s digest.

  • manual_confirmation (bool, optional) – Set only for an explicit, user-reviewed confirmation of an unknown identity. A known conflict is never overridden.

  • manual_conflict_override (bool, optional) – Allow a specifically reviewed conflict with a fresh provider record.

  • provider_document (Mapping[str, Any], optional) – Authoritative raw ADS or provider document for the record. When omitted, a valid stored proof is checked first. Otherwise, the cached ADS document for the record’s primary Bibcode is used when available.

  • state (Sidecar or CentralPdfRegistryState, optional) – Catalog state used to look up the cached document.

  • client (ADSClient, optional) – Client for automatically fetching an unverifiable stored ADS candidate. Valid stored proofs need no request. An omitted client keeps checks local.

  • providers (sequence of DoiProvider, optional) – Enabled providers. Automatic ADS requests require ADS in this sequence.

Returns:

Identity proof to store under IDENTITY_KEY.

Return type:

dict[str, Any]

Raises: