adsfolio.pdf.reference_lookup

Match bibliographic reference hints against the current PDF’s identity.

class adsfolio.pdf.reference_lookup.ReferenceLookupResult(matches, rejected=(), used_own_identifiers=False)[source]

Bases: object

Keep verified reference candidates separate from rejected search hints.

Parameters:

matches (adsfolio.pdf.identifier.AdsQueryResult)
rejected (tuple[str, ...])
used_own_identifiers (bool)

matches: adsfolio.pdf.identifier.AdsQueryResult

rejected: tuple[str, ...] = ()

used_own_identifiers: bool = False

adsfolio.pdf.reference_lookup.lookup_exact_identifier(identifier, kind, value, providers, cache_documents=None, path=None)[source]

Find exact DOI or arXiv metadata in the selected provider order.

Parameters:

identifier (PdfIdentifier) – Resolver with an optional ADS client.
kind (str) – Identifier type, either doi or arxiv.
value (str) – Exact DOI or version-free arXiv identifier.
providers (sequence of DoiProvider) – Enabled providers in priority order.
cache_documents (callable, optional) – Callback for independently cached ADS documents.
path (Path, optional) – Current PDF whose identifiers a successful provider must prove.

Returns:

Candidates from the first suitable provider. Multiple verified candidates retain their ambiguity. If all candidates fail the PDF check, return the first provider’s candidates for review or refusal.

Return type:

AdsQueryResult

Raises:

ADSError or ProviderError – A lookup failed and no later provider supplied metadata.
ValueError – The identifier type or value is invalid.

adsfolio.pdf.reference_lookup.match_reference_to_pdf(identifier, path, result, providers, cache_documents=None)[source]

Verify reference candidates and recover through the PDF’s own identifiers.

Parameters:

identifier (PdfIdentifier) – Resolver with an optional ADS client.
path (Path) – Current PDF to inspect without changing its contents.
result (AdsQueryResult) – Initial ADS result for a bibliographic reference hint.
providers (sequence of DoiProvider) – Enabled providers in priority order for recovery.
cache_documents (callable, optional) – Callback for independently cached ADS documents.

Returns:

Matching candidates, rejected hints, and the recovery state.

Return type:

ReferenceLookupResult

Notes

A reference is a search hint, so a coauthor match cannot establish identity. Explicit DOI and bibcode updates must not call this recovery operation. Without trusted PDF identifiers, retain the original candidates for review. A partial result cannot establish a unique automatic match.