adsfolio.pdf.document_identity_evidence

Corroborate PDF identity evidence from mutual DocInfo, text, and provider matches.

This module provides a narrowly scoped helper to corroborate a PDF’s self-stated identity without relying on file names, fixed journal names, or numeric heuristics.

class adsfolio.pdf.document_identity_evidence.DocumentDoiEvidence(doi, reason='')[source]

Bases: object

Store a corroborated DOI or the reason corroboration failed.

Parameters:

doi (str or None) – Verified document DOI, or None after a refusal.
reason (str) – User-visible reason for a refusal. Empty on success.

doi: str | None

reason: str = ''

class adsfolio.pdf.document_identity_evidence.PageCitationEvidence(matched, reason='')[source]

Bases: object

Store the result of the page-1 citation check.

Parameters:

matched (bool) – True when page 1 shows the provider record’s citation data.
reason (str) – User-visible reason for a refusal. Empty on success.

matched: bool

reason: str = ''

adsfolio.pdf.document_identity_evidence.check_document_doi_evidence(pdf_bytes, provider_document)[source]

Check the metadata DOI against the first page and provider record.

All of these conditions must hold:

DocInfo /Subject contains exactly one explicitly labeled DOI, or /WPS-ARTICLEDOI contains one article DOI.
The first page repeats that DOI with exact token boundaries.
The metadata and provider titles match after documented formatting normalization.
The provider record explicitly lists the same DOI.

Parameters:

pdf_bytes (bytes) – Immutable bytes of the PDF to check.
provider_document (Mapping[str, Any]) – Authoritative provider record containing the title and DOI.

Returns:

Normalized DOI on success. Otherwise, the reason for refusal.

Return type:

DocumentDoiEvidence

Notes

Title comparison folds case and collapses whitespace. It normalizes canonical Unicode, curly quotation marks, and spaced subtitle separators. It also accepts balanced provider display tags and valid HTML entities. Title content and unknown tags remain significant. Each resulting title part must match exactly. DOI tokens retain their punctuation and use exact token boundaries. When only the publisher article DOI is present, page 1 must also contain the full provider title. In that case the DocInfo title may omit dashes, but its remaining characters must match.

adsfolio.pdf.document_identity_evidence.check_page_citation_evidence(pdf_bytes, provider_document)[source]

Check that page 1 shows the provider record’s citation data.

This check is for PDFs that state no DOI or arXiv ID, such as scans of papers published before DOIs. Page 1 must show all of these:

The full provider title as the only text on its lines. Footnote marks, digits, and punctuation may surround it. Case, spacing, typographic dashes and quotes, and words hyphenated across a line break do not matter.
The first author’s surname as a whole word.
The publication year as a whole number.
The volume and then the first page, on one text line, as whole tokens. An example is “ICARUS 73, 462–481 (1988)”.

A DOI on page 1 that the provider record does not list refuses the match. A line that holds only the heading Erratum, Errata, Corrigendum, Correction, Addendum, or Retraction also refuses it. Such a notice repeats the title and citation of the original paper.

Parameters:

pdf_bytes (bytes) – Immutable PDF contents.
provider_document (Mapping[str, Any]) – Authoritative record with title, author, year, volume, and page.

Returns:

The result and, after a refusal, the first failed condition.

Return type:

PageCitationEvidence

adsfolio.pdf.document_identity_evidence.corroborate_document_doi_evidence(pdf_bytes, provider_document)[source]

Return the document DOI when metadata, page 1, and provider agree.

Parameters:

pdf_bytes (bytes) – Immutable PDF contents.
provider_document (Mapping[str, Any]) – Authoritative metadata containing the title and DOI.

Returns:

Corroborated DOI, or None when a required check fails.

Return type:

str or None