adsfolio.references

Local references with optional ADS identities and PDF attachments.

Paste BibTeX with parse_bibtex() to preview it, then save it with LocalReferences.import_bibtex(). Exports work without an ADS connection.

exception adsfolio.references.CitationKeyError(assignment, references)

Bases: ValueError

Export stopped because papers have no key or share a key.

Parameters:

• assignment (KeyAssignment)

• references (Mapping[int, Mapping[str, Any]])

Return type:

None

assignment

Keys found, papers without a key, and shared keys.

Type:

KeyAssignment

references

The selected references by document ID, for display.

Type:

dict

class adsfolio.references.LocalReferences(catalog, policy=None)

Bases: object

Manage local references using an existing PdfCatalog connection.

The caller owns and closes catalog. Edits and imports preserve document IDs; no operation merges records or contacts ADS automatically.

Parameters:

• catalog (PdfCatalog)

• policy (KeyPolicy | None)

add(*, cite_key, fields, entry_type='misc', source='manual', bibcode=None)

Add a reference without requiring a PDF or ADS bibcode.

Empty fields save a draft. Export requires at least one field.

Parameters:

• cite_key (str)

• fields (collections.abc.Mapping[str, str])

• entry_type (str)

• source (str)

• bibcode (str | None)

Return type:

dict[str, Any]

ads_bibtex_requests(document_ids)

Return {bibcode: fingerprint} for papers without saved ADS BibTeX.

A paper is listed when no ADS result is saved for its current ADS metadata. A saved “ADS has no entry” result is not listed again.

Parameters:

document_ids (collections.abc.Sequence[int])

Return type:

dict[str, str]

attach_pdf(document_id, path)

Link a PDF at its current path without copying or renaming it.

Parameters:

• document_id (int)

• path (pathlib.Path)

Return type:

dict[str, Any]

check_citations(cited_keys)

Find cited keys that are not current keys, and their current keys.

A key that equals the key of a reference is current. For another key, each 19-character part is compared with the bibcode and the alternate bibcodes of each reference. An ADS bibcode has 19 characters. A preprint bibcode becomes an alternate bibcode after publication.

Parameters:

cited_keys (collections.abc.Iterable[str]) – Keys that a paper cites, for example from its .aux file.

Returns:

One item for each cited key that is not current, in input order. The value lists the current keys of the matched references. An empty list means that no reference matched.

Return type:

dict

export_bibtex(document_ids, *, exclude_fields=())

Export selected records offline, including required crossref parents.

exclude_fields names fields to leave out of every entry, ignoring letter case, for example ("abstract",).

Unknown IDs, empty drafts, absent parents, and cycles fail before any text is returned. Imports retain original text; output preserves field semantics, not original whitespace or macro spelling.

Parameters:

• document_ids (collections.abc.Sequence[int])

• exclude_fields (collections.abc.Collection[str])

Return type:

str

get(document_id)

Return one reference or raise ValueError for an unknown ID.

Parameters:

document_id (int)

Return type:

dict[str, Any]

import_bibtex(text, *, source='bibtex')

Import all entries atomically; duplicate keys or DOIs leave no changes.

Parameters:

• text (str)

• source (str)

Return type:

list[dict[str, Any]]

list()

Return references and their known PDF locations, including missing files.

Return type:

list[dict[str, Any]]

original_bibtex(document_id)

Read the shared import; manually added references return None.

Parameters:

document_id (int)

Return type:

str | None

set_cite_key(document_id, key)

Save the citation key that the user typed for one reference.

A local reference stores the key in its BibTeX entry. Another paper stores it as its own key, which wins over the key style. An empty key removes the own key of a paper that is not a local reference.

Raises:

ValueError – If the reference is unknown, or the key holds characters that BibTeX rejects.

Parameters:

• document_id (int)

• key (str)

Return type:

None

store_ads_bibtex(entries, requests)

Save fetched ADS BibTeX for the requested papers.

Parameters:

• entries (collections.abc.Mapping[str, str]) – Entry text by Bibcode, from ExportAPI.export_entries().

• requests (collections.abc.Mapping[str, str]) – The {bibcode: fingerprint} map from ads_bibtex_requests. A requested Bibcode without an entry is saved as “ADS has no entry”.

Returns:

The number of saved entries.

Return type:

int

update(document_id, *, cite_key=None, entry_type=None, fields=None)

Edit one reference; fields replaces its complete editable field mapping.

Changing a key used by another reference’s crossref is rejected. Update those links first to avoid creating dangling references.

Parameters:

• document_id (int)

• cite_key (str | None)

• entry_type (str | None)

• fields (collections.abc.Mapping[str, str] | None)

Return type:

dict[str, Any]

adsfolio.references.ads_bibtex_fingerprint(metadata)

Return a hash of the ADS fields that a saved ADS BibTeX entry reflects.

A saved entry is used only while this hash is unchanged. After an ADS refresh changes these fields, export asks ADS for the entry again.

Parameters:

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

Return type:

str

adsfolio.references.parse_bibtex(text)

Preview BibTeX without changing the catalog.

Parameters:

text (str) – Complete BibTeX text. String macros are expanded; nested braces, LaTeX commands, custom fields, and cross-reference keys are retained.

Returns:

Each entry has cite_key, entry_type, fields, and source. Preambles are retained; import stores the original input once.

Return type:

list of dict

Raises:

ValueError – If the text is malformed, has duplicate keys, or contains no entries.