adsfolio.citations

Plain-text citation domain models, validation, and rendering.

class adsfolio.citations.CitationFormatter[source]

Bases: object

Format citation strings against record metadata using a CitationStyle.

render(style, record)[source]

Render the given record metadata with the citation style.

Parameters:

style (CitationStyle) – Citation style definition.
record (Mapping[str, Any]) – Catalog or ADS paper record containing a ‘metadata’ mapping.

Returns:

Rendered citation string.

Return type:

str

class adsfolio.citations.CitationStyle(id, name, template, author_format='surname_initials', max_authors=3, authors_when_truncated=1, author_separator=', ', author_truncation_suffix=' et al.')[source]

Bases: object

Immutable custom citation style definition.

Parameters:

id (str) – Unique persistent identifier for this style.
name (str) – User-facing name of the style.
template (str) – Formatting template containing allowed placeholders.
author_format (str, default="surname_initials") – Format for author items (“surname”, “surname_initials”, “last_comma_first”).
max_authors (int, default=3) – Threshold above which author list is truncated.
authors_when_truncated (int, default=1) – Number of authors to retain when truncation occurs.
author_separator (str, default=", ") – Delimiter between authors.
author_truncation_suffix (str, default=" et al.") – Suffix appended when author count exceeds max_authors.

author_format: str = 'surname_initials'

author_separator: str = ', '

author_truncation_suffix: str = ' et al.'

authors_when_truncated: int = 1

classmethod from_mapping(payload)[source]

Create a CitationStyle from a mapping with normalization of malformed values.

Parameters:: payload (Mapping[str, Any]) – Raw dictionary or mapping defining a citation style.
Returns:: Validated immutable citation style instance.
Return type:: CitationStyle

id: str

max_authors: int = 3

name: str

template: str

to_mapping()[source]

Serialize citation style to a dictionary.

Returns:: Serialized representation of this style.
Return type:: dict[str, object]

exception adsfolio.citations.CitationStyleError[source]

Bases: ValueError

Report an invalid citation style or style collection.

adsfolio.citations.citation_preference_key(style_id)[source]

Build preference storage key for a citation style ID.

Parameters:: style_id (str) – Style ID string.
Returns:: Key in the form ‘citation:<style_id>’.
Return type:: str
Raises:: CitationStyleError – If style_id is empty or whitespace.

adsfolio.citations.initial_citation_styles()[source]

Return default citation styles provided out-of-the-box.

Returns:: Tuple containing the default ‘My bibcode 1’ style.
Return type:: tuple[CitationStyle, …]

adsfolio.citations.new_citation_style(existing_names, existing_ids)[source]

Generate a new CitationStyle with lowest unused positive number in name.

Parameters:

existing_names (Iterable[str]) – Existing style names to avoid name collisions.
existing_ids (Iterable[str]) – Existing style IDs to avoid ID collisions.

Returns:

New citation style with unique name and ID.

Return type:

CitationStyle

adsfolio.citations.validate_citation_styles(styles)[source]

Validate an entire collection of CitationStyles.

Parameters:: styles (Sequence[CitationStyle]) – Collection of citation styles.
Raises:: CitationStyleError – If duplicate names or IDs exist in the collection, or any style is invalid.
Return type:: None