adsfolio.client

Base HTTP client for NASA ADS with rate limiting and caching.

class adsfolio.client.ADSClient(token=None, timeout=(3.05, 30.0))[source]

Bases: object

High-level NASA ADS client.

Provides access to all API modules (Search, Export, Libraries, etc.) through a unified interface.

Examples

>>> client = ADSClient()
>>> results = client.search.query("author:Einstein", rows=5)
>>> bibtex = client.export.export(["2020ApJ...900..100S"], format="bibtex")
Parameters:
static abstract_url(bibcode)[source]

Build the ADS abstract URL for a bibcode.

Parameters:

bibcode (str) – ADS bibcode.

Returns:

URL to ADS abstract page.

Return type:

str

close()[source]

Close the HTTP resources owned by this client.

Return type:

None

download_pdf(bibcode, output_dir='.', link_types=None, force_print_html=False, timeout=30, printed_suffix='__printed')[source]

Download a paper PDF by ADS bibcode via link-gateway.

Parameters:

  • bibcode (str) – ADS bibcode to fetch.

  • output_dir (str or pathlib.Path, optional) – Destination directory for downloaded/printed PDFs.

  • link_types (sequence of str, optional) – ADS gateway link types to try in order. Defaults to (“PUB_PDF”, “EPRINT_PDF”, “AUTHOR_PDF”).

  • force_print_html (bool, optional) – If True and only HTML landing pages are found, print final HTML page to PDF using Playwright as a fallback.

  • timeout (int, optional) – Request timeout in seconds.

  • printed_suffix (str, optional) – Suffix for printed fallback files. It must form a safe filename.

Returns:

Saved PDF path on success, else None. Existing direct and printed downloads remain unchanged. A new download receives a numeric suffix when its intended filename exists.

Return type:

pathlib.Path or None

Raises:

ValueError – If the bibcode or printed suffix cannot form a safe filename.

Notes

Direct responses require a PDF header. An HTML error response causes the downloader to try its next source instead of saving HTML as PDF.

download_pdfs(bibcodes, output_dir='.', link_types=None, force_print_html=False, timeout=30, printed_suffix='__printed', show_progress=True, progress_desc='Downloading ADS PDFs', progress_leave=False, max_workers=8)[source]

Download PDFs for multiple bibcodes.

Parameters:

  • bibcodes (sequence of str) – Bibcodes to download.

  • output_dir (str or pathlib.Path, optional) – Destination directory for downloaded/printed PDFs.

  • link_types (sequence of str, optional) – Gateway link types to try in order.

  • force_print_html (bool, optional) – If True, print HTML pages when direct PDF retrieval fails.

  • timeout (int, optional) – Request timeout in seconds.

  • printed_suffix (str, optional) – Suffix for printed fallback files.

  • show_progress (bool, optional) – Show progress bar using tqdm when available. Default: True.

  • progress_desc (str, optional) – Description text for progress bar.

  • progress_leave (bool, optional) – Leave completed progress bar on screen.

  • max_workers (int, optional) – Maximum number of parallel download workers. Use 1 for serial mode. Default: 8.

Returns:

Mapping from bibcode to downloaded file path (or None on failure).

Return type:

dict[str, pathlib.Path | None]

property export[source]

Access Export API.

property journals[source]

Access Journals API.

property libraries[source]

Access Libraries API.

property metrics[source]

Access Metrics API.

rate_limits()[source]

Get current rate limit status.

Return type:

dict

property search[source]

Access Search API.

class adsfolio.client.BaseClient(token=None, timeout=(3.05, 30.0))[source]

Bases: object

Low-level HTTP client for NASA ADS.

Handles authentication, rate limiting, and error handling.

Parameters:
close()[source]

Close the underlying HTTP session.

Return type:

None

delete(endpoint)[source]

Make a DELETE request to the API.

Parameters:

endpoint (str)

Return type:

dict

get(endpoint, params=None)[source]

Make a GET request to the API.

Parameters:

  • endpoint (str) – API endpoint (e.g., “/search/query”).

  • params (dict, optional) – Query parameters.

Returns:

JSON response.

Return type:

dict

property headers: dict[source]

Standard headers for API requests.

post(endpoint, data=None)[source]

Make a POST request to the API.

Parameters:

  • endpoint (str) – API endpoint.

  • data (dict, optional) – JSON payload.

Returns:

JSON response.

Return type:

dict

post_raw(endpoint, data=None, params=None, headers=None)[source]

Make a POST request with a raw payload (non-JSON body).

Parameters:

  • endpoint (str) – API endpoint.

  • data (str | bytes, optional) – Raw payload body.

  • params (dict, optional) – Query parameters.

  • headers (dict, optional) – Extra headers merged over default auth headers.

Returns:

JSON response (or {“text”: …} for non-JSON responses).

Return type:

dict

put(endpoint, data=None)[source]

Make a PUT request to the API.

Parameters:

  • endpoint (str)

  • data (dict | None)

Return type:

dict

property token: str[source]

Get token, loading from config if needed.