adsfolio.citekeys

Citation keys for BibTeX export, for papers inside and outside ADS.

A KeyPolicy chooses one KeyStyle for ADS papers (papers with a bibcode) and one for other papers. A key that the user typed, or that came with an imported BibTeX entry, always wins over the style. assign_keys never makes up a key: it reports papers without a key and keys that two papers share, so that the caller can ask the user.

Template and Scholar keys contain ASCII characters only. anyascii changes other characters, for example “Muñoz” to “Munoz” and “Straße” to “Strasse”. Typed and imported keys keep their characters.

class adsfolio.citekeys.KeyAssignment(keys=<factory>, missing=<factory>, clashes=<factory>)

Bases: object

Keys for a group of papers, with the problems that stop an export.

keys maps each paper ID to its key. missing lists papers that have no key. clashes maps each shared key to the papers that share it.

Parameters:

• keys (dict[Any, str])

• missing (list[Any])

• clashes (dict[str, list[Any]])

clashes: dict[str, list[Any]]

property complete: bool

Return whether every paper has its own key.

keys: dict[Any, str]

missing: list[Any]

class adsfolio.citekeys.KeyPolicy(ads=KeyStyle.BIBCODE, other=KeyStyle.DOI, template='{first_author_initials}{year}', author_format='surname_initials', max_authors=3, authors_when_truncated=1, author_separator='+', author_truncation_suffix='+')

Bases: object

Key styles for ADS papers and for other papers.

Parameters:

• ads (KeyStyle) – Style for papers with an ADS bibcode.

• other (KeyStyle) – Style for papers without a bibcode. KeyStyle.BIBCODE is not allowed here.

• template (str) – Template for KeyStyle.TEMPLATE, with the placeholders of custom citation styles, for example {first_author_initials}{year}.

• author_format (str, int, int) – How {authors} writes the author list in a template. The defaults match the default Rename filenames: surname and initials, up to three authors, and the first author alone for a longer list.

• max_authors (str, int, int) – How {authors} writes the author list in a template. The defaults match the default Rename filenames: surname and initials, up to three authors, and the first author alone for a longer list.

• authors_when_truncated (str, int, int) – How {authors} writes the author list in a template. The defaults match the default Rename filenames: surname and initials, up to three authors, and the first author alone for a longer list.

• author_separator (str) – Text between authors, and after a shortened author list. Both default to +, as in DoeJA+RoeA and DoeJA+.

• author_truncation_suffix (str) – Text between authors, and after a shortened author list. Both default to +, as in DoeJA+RoeA and DoeJA+.

ads: adsfolio.citekeys.KeyStyle = 'bibcode'

author_format: str = 'surname_initials'

author_separator: str = '+'

author_truncation_suffix: str = '+'

authors_when_truncated: int = 1

classmethod from_mapping(payload)

Build a policy from saved settings, using defaults for gaps.

Parameters:

payload (collections.abc.Mapping[str, Any] | None)

Return type:

adsfolio.citekeys.KeyPolicy

max_authors: int = 3

other: adsfolio.citekeys.KeyStyle = 'doi'

template: str = '{first_author_initials}{year}'

to_mapping()

Return the policy as JSON-compatible settings.

Return type:

dict[str, Any]

class adsfolio.citekeys.KeyStyle(*values)

Bases: str, enum.Enum

How a citation key is made when the paper has no key of its own.

BIBCODE = 'bibcode'

DOI = 'doi'

MANUAL = 'manual'

SCHOLAR = 'scholar'

TEMPLATE = 'template'

property label: str

Return the name shown in the application.

adsfolio.citekeys.assign_keys(papers, policy)

Assign keys to papers and report missing and shared keys.

Parameters:

• papers (iterable of tuple) – One (id, record, own_key) tuple per paper: its ID, its metadata record, and its own key (or "").

• policy (KeyPolicy) – Key styles to apply.

Returns:

Keys, papers without a key, and keys that several papers share. The caller asks the user to resolve problems before an export.

Return type:

KeyAssignment

adsfolio.citekeys.citation_key(record, policy, *, own_key='')

Return the key for one paper, or an empty string when none applies.

Parameters:

• record (mapping) – Paper metadata, or a record with a metadata mapping.

• policy (KeyPolicy) – Styles for ADS papers and other papers.

• own_key (str) – A key that the user typed or that came with an imported entry. It always wins.

Return type:

str

adsfolio.citekeys.sanitize_key(key)

Replace characters that BibTeX keys cannot hold with _.

Spaces, commas, braces, parentheses, quotes, #, %, ~, \, and = are replaced. Other characters, such as / and . in a DOI, stay as they are.

Parameters:

key (str)

Return type:

str

adsfolio.citekeys.scholar_key(metadata)

Return a Google Scholar style key, or an empty string.

The key is the first author’s surname, the year, and the first title word that is not in SCHOLAR_STOP_WORDS, all in lowercase ASCII. For “Einstein, A.” (1905), “On the Electrodynamics of Moving Bodies”, the key is einstein1905electrodynamics.

Parameters:

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

Return type:

str