adsfolio.library_sync

Qt-free local selection and ADS library synchronization helpers.

class adsfolio.library_sync.AddDocumentsResult(acknowledged=(), already_present=(), failed=(), status_unknown=(), unattempted=(), cancelled=False, error=None)

Bases: object

Structured outcome for preflight or batched document additions.

Parameters:

• acknowledged (tuple[str, ...])

• already_present (tuple[str, ...])

• failed (tuple[str, ...])

• status_unknown (tuple[str, ...])

• unattempted (tuple[str, ...])

• cancelled (bool)

• error (Exception | None)

acknowledged: tuple[str, ...] = ()

Bibcodes accepted by completed add requests.

already_present: tuple[str, ...] = ()

Bibcodes known to be present before an add request.

cancelled: bool = False

Whether cancellation prevented the next request from starting.

error: Exception | None = None

The exception that stopped processing, if any.

failed: tuple[str, ...] = ()

Bibcodes in a request rejected with an ADS-declared error.

status_unknown: tuple[str, ...] = ()

Bibcodes in a request whose transport outcome is uncertain.

unattempted: tuple[str, ...] = ()

Bibcodes left out because processing stopped before their request.

class adsfolio.library_sync.AdsLibraryService(client)

Bases: object

Coordinate local Bibcodes with the ADS libraries API.

Parameters:

client (ADSClient)

MAX_DOCUMENTS_PER_REQUEST = 2000

add_documents(library_id, bibcodes, *, already_present=(), cancelled=<function AdsLibraryService.<lambda>>)

Add Bibcodes in bounded sequential requests.

Parameters:

• library_id (str) – Destination ADS library identifier.

• bibcodes (sequence of str) – Bibcodes to add, normalized and deduplicated in source order.

• already_present (sequence of str, optional) – Bibcodes known to be in the destination already.

• cancelled (callable, optional) – Predicate checked before every add request.

Returns:

Structured partial outcome for the operation.

Return type:

AddDocumentsResult

Raises:

PermissionError – If a listed destination is not writable.

create_destination(name, description, public)

Create an empty ADS library after validating its name.

Parameters:

• name (str) – New library name.

• description (str) – New library description.

• public (bool) – Whether the new library should be public.

Returns:

Metadata returned by ADS for the newly created library.

Return type:

LibraryDestination

Raises:

ValueError – If name is empty after trimming.

export_library(library_id, format='bibtex', *, cancelled=None)

Read the complete remote library and export its bibliography.

Parameters:

• library_id (str) – Accessible remote ADS library, including libraries with read permission.

• format (str, optional) – A format from ExportAPI.BIBLIOGRAPHY_FORMATS.

• cancelled (callable, optional) – Check for cancellation between network operations.

Returns:

Full bibliography and sorted Bibcodes, an empty result for an empty library, or a cancelled result without partial bibliography text.

Return type:

LibraryExportResult

Raises:

• ADSError – If library pagination is incomplete or export records are missing.

• ValueError – If the library identifier or format is invalid.

list_destinations()

Return ADS libraries in the order supplied by the API.

Return type:

tuple[adsfolio.library_sync.LibraryDestination, …]

preflight(library_id, bibcodes)

Classify requested Bibcodes against the current remote library.

Missing Bibcodes are returned in AddDocumentsResult.unattempted because no add request has been made.

Parameters:

• library_id (str)

• bibcodes (collections.abc.Sequence[str])

Return type:

adsfolio.library_sync.AddDocumentsResult

reconcile_and_retry(library_id, bibcodes, *, cancelled=<function AdsLibraryService.<lambda>>)

Reload remote state and retry only Bibcodes still absent.

Parameters:

• library_id (str)

• bibcodes (collections.abc.Sequence[str])

• cancelled (collections.abc.Callable[[], bool])

Return type:

adsfolio.library_sync.AddDocumentsResult

class adsfolio.library_sync.BibcodeSelection(bibcodes, source_files, ineligible_files, local_duplicate_files)

Bases: object

Stable local Bibcode selection and exclusion counts.

Parameters:

• bibcodes (tuple[str, ...])

• source_files (int)

• ineligible_files (int)

• local_duplicate_files (int)

bibcodes: tuple[str, ...]

Unique eligible Bibcodes in first-seen order.

ineligible_files: int

Number of records that were not eligible for synchronization.

local_duplicate_files: int

Number of eligible records whose Bibcode was already seen locally.

source_files: int

Number of records considered.

class adsfolio.library_sync.LibraryDestination(id, name, permission, public, num_documents)

Bases: object

Immutable ADS library metadata used by callers and UI code.

Parameters:

• id (str)

• name (str)

• permission (str)

• public (bool)

• num_documents (int)

id: str

ADS library identifier.

name: str

Human-readable ADS library name.

num_documents: int

Number of documents reported by ADS.

permission: str

Permission reported by ADS for the current user.

public: bool

Whether the ADS library is public.

property writable: bool

Return whether the current user may add documents.

class adsfolio.library_sync.LibraryExportResult(text, bibcodes, cancelled=False)

Bases: object

Complete remote bibliography, or an explicitly cancelled operation.

Parameters:

• text (str)

• bibcodes (tuple[str, ...])

• cancelled (bool)

bibcodes: tuple[str, ...]

cancelled: bool = False

text: str

adsfolio.library_sync.collect_identified_bibcodes(records)

Collect eligible Bibcodes from local identification records.

Parameters:

records (iterable of mapping) – Local records containing status, document identity, and Bibcode data.

Returns:

First-seen unique Bibcodes and counts for all excluded or duplicate source records.

Return type:

BibcodeSelection