adsfolio.config

Configuration and token management for NASA ADS.

Token is searched in order: 1. Environment variable ADS_API_TOKEN 2. ~/.ads/token 3. .ads-token (current directory) 4. Interactive prompt (saved to ~/.ads/token)

exception adsfolio.config.ADSError[source]

Bases: Exception

Base exception for NASA ADS errors.

exception adsfolio.config.AuthenticationError[source]

Bases: adsfolio.config.ADSError

Raised when authentication fails.

class adsfolio.config.Config[source]

Bases: object

Configuration management for NASA ADS.

API_BASE = 'https://api.adsabs.harvard.edu/v1'

DEFAULT_FIELDS: ClassVar[list[str]] = ['bibcode', 'title', 'author', 'year', 'pub', 'citation_count']

ENV_VAR = 'ADS_API_TOKEN'

SETUP_FILENAME = 'setup.json'

SETUP_SCHEMA_VERSION = 2

classmethod check_rate_limit()[source]

Return whether a request can proceed without using the quota reserve.

Once the ADS reset time has passed, allow a request to refresh the previously reported quota. ADS reports the reset as a Unix timestamp.

Return type:: bool

config_dir_override: ClassVar[pathlib.Path | None] = None

classmethod get_config_dir()[source]

Get platform-appropriate config directory.

Return type:: pathlib.Path

classmethod get_rate_limits()[source]

Get current rate limit status.

Return type:: dict

classmethod get_setup_path()[source]

Path for persisted interactive setup profile.

Return type:: pathlib.Path

classmethod get_token(*, prompt=True)[source]

Get NASA ADS token from various sources.

Order of precedence: 1. Environment variable ADS_API_TOKEN 2. Config file (~/.config/ads/token or ~/.ads/token) 3. Local .ads-token file 4. Interactive prompt (saves to config)

Parameters:: prompt (bool, optional) – Allow prompting when standard input is an interactive terminal. Set to False for GUI token lookup.
Returns:: The API token.
Return type:: str
Raises:: AuthenticationError – If no token can be found or created.

classmethod get_token_paths()[source]

Return list of paths to check for token, in order.

Return type:: list[pathlib.Path]

classmethod get_user_setup()[source]

Return the publication profile using legacy flat API field names.

Return type:: dict

classmethod load_identify_settings()[source]

Load normalized global Identify behavior.

Return type:: IdentifySettings

classmethod load_key_policy()[source]

Load the citation key styles, or the defaults when unset or invalid.

Return type:: KeyPolicy

classmethod load_rename_settings()[source]

Load normalized global Rename behavior.

Return type:: RenameSettings

classmethod load_user_profile()[source]

Load the normalized global publication profile.

Return type:: UserProfile

classmethod save_identify_settings(settings)[source]

Atomically persist global Identify behavior without changing identity.

Parameters:: settings (IdentifySettings)
Return type:: Path

classmethod save_key_policy(policy)[source]

Atomically persist the citation key styles.

Parameters:: policy (KeyPolicy)
Return type:: Path

classmethod save_rename_settings(settings)[source]

Atomically persist global Rename behavior without changing identity.

Parameters:: settings (RenameSettings)
Return type:: Path

classmethod save_token(token)[source]

Save token to config directory.

Parameters:: token (str) – Token string to save.
Returns:: Path where token was saved.
Return type:: Path

classmethod save_user_profile(profile)[source]

Atomically persist the global publication profile.

Parameters:: profile (UserProfile)
Return type:: Path

classmethod save_user_setup(orcid, query_names=None, debut_year=None, retire_year=None, library_ids=None, *, end_year=None)[source]

Save identify-optimization profile used by adsfolio pdf identify.

Parameters:

orcid (str) – ORCID identifier (recommended).
query_names (list[str], optional) – Optional author names for fallback matching.
debut_year (int, optional) – Earliest publication year to include in prefetch.
end_year (int, optional) – Latest publication year to include in prefetch.
library_ids (list[str], optional) – ADS library IDs to include in prefetch.
retire_year (int | None)

Return type:

pathlib.Path

classmethod token_source()[source]

Describe where the active token comes from, or None without one.

Returns:: The environment variable name or the absolute token file path.
Return type:: str or None

classmethod update_rate_limits(headers)[source]

Update rate limit info from response headers.

Parameters:: headers (dict)
Return type:: None

exception adsfolio.config.RateLimitError[source]

Bases: adsfolio.config.ADSError

Raised when rate limit is exceeded.

exception adsfolio.config.RequestTooLongError[source]

Bases: adsfolio.config.ADSError

Indicate that ADS rejected an oversized request URL.