adsfolio.pdf.doi_providers

Metadata provider abstractions for DOI lookup.

class adsfolio.pdf.doi_providers.DoiProvider(*values)

Bases: str, enum.Enum

Supported metadata providers for DOI lookup.

ADS = 'ads'

CROSSREF = 'crossref'

DATACITE = 'datacite'

exception adsfolio.pdf.doi_providers.ProviderError

Bases: Exception

Base error for external DOI provider lookups.

exception adsfolio.pdf.doi_providers.ProviderNetworkError

Bases: adsfolio.pdf.doi_providers.ProviderError

Network connection or timeout failure contacting DOI provider.

exception adsfolio.pdf.doi_providers.ProviderRateLimitError

Bases: adsfolio.pdf.doi_providers.ProviderError

Rate limit exceeded by DOI provider.

adsfolio.pdf.doi_providers.fetch_crossref_doi(doi, *, session=None, timeout=(3.05, 15.0))

Fetch metadata for an exact DOI from Crossref.

Parameters:

• doi (str) – Exact DOI string.

• session (requests.Session, optional) – Reusable HTTP session.

• timeout (tuple of float) – Connect and read timeout in seconds.

Returns:

Normalized document mapping if found, otherwise None on HTTP 404.

Return type:

dict or None

Raises:

• ValueError – If doi is not a valid DOI format.

• ProviderRateLimitError – If Crossref returns status 429.

• ProviderNetworkError – If network connection or timeout fails.

• ProviderError – If Crossref returns a 5xx/other error, malformed payload, or mismatched DOI.

adsfolio.pdf.doi_providers.fetch_datacite_doi(doi, *, session=None, timeout=(3.05, 15.0))

Fetch metadata for an exact DOI from DataCite.

Parameters:

• doi (str) – Exact DOI string.

• session (requests.Session, optional) – Reusable HTTP session.

• timeout (tuple of float) – Connect and read timeout in seconds.

Returns:

Normalized document mapping if found, otherwise None on HTTP 404.

Return type:

dict or None

Raises:

• ValueError – If doi is not a valid DOI format.

• ProviderRateLimitError – If DataCite returns status 429.

• ProviderNetworkError – If network connection or timeout fails.

• ProviderError – If DataCite returns a 5xx/other error, malformed payload, or mismatched DOI.